# fpzip precision: count representation bits, not mantissa bits

The fpzip 1.3.0 C API retains the high **p bits of the whole IEEE representation**.
For binary32, p=24 leaves 15 stored fraction bits, not the usual 24-bit
significand precision of a normal binary32 value. For binary64, p=32 leaves 20
stored fraction bits. The implicit leading significand bit is not a stored bit.

| Input type | prec | Sign | Exponent retained | Stored fraction retained |
|---|---:|---:|---:|---:|
| binary32 | 24 | 1 | 8 | 15 |
| binary32 | 16 | 1 | 8 | 7 |
| binary64 | 32 | 1 | 11 | 20 |
| binary64 | 24 | 1 | 11 | 12 |

Zero selects full precision. Version 1.3.0 accepts 2-32 for binary32 and even
4-64 for binary64. Below 9 or 12 respectively, truncation reaches exponent
bits. A precision count is not an absolute-error tolerance or output-byte budget.

## Native observation

The [probe](probe.cpp) supplies two fixed 4 by 2 arrays, one of each type.
Eight settings per array include full precision, truncated representations,
exponent-truncation controls and two invalid settings. Inputs and outputs
are recorded as hexadecimal bit patterns, preserving the distinction between
positive and negative zero. There are 12 successful configurations and four
expected API rejections, not 16 successful compression runs.

Release and Debug builds of unmodified fpzip revision
`4a539c06d98b1c029b08324a086d4b75689a2b72` produce identical [native records](native.jsonl).
The [independent verifier](verify.py) checks each decoded word against a
representation-bit mask, exact rational errors, metadata and stream lengths.
[Results](results.json) and the [execution receipt](receipt.json) carry the scope.

For the eight binary32 values, prec=9 occupies 36 bytes and prec=8 occupies
37 bytes. Full precision uses 59 bytes, including the optional fpzip header,
for 32 raw bytes. Lower precision does not guarantee a smaller individual
stream, and a small array may expand. No timings or workload compression ratios
were measured. This fixture is deliberately small and not representative.

## What Lorenzo prediction guarantees

For a 3D cell, let f100 denote the already reconstructed sample one x-step
behind the target, with analogous offset notation. The predictor is:

`prediction = f100 + f010 + f001 - f110 - f101 - f011 + f111`

The [2003 preprint](https://digital.library.unt.edu/ark:/67531/metadc1404787/m2/1/high_res_d/15004618.pdf),
sections 3-4, proves exactness for polynomials of total degree below dimension n,
assuming exact arithmetic. It does not say that every higher-degree polynomial
must fail. The following constructed unit-cube examples are executable in
the verifier:

| Field | Prediction at (1,1,1) | Actual | Residual |
|---|---:|---:|---:|
| x^2 + 2y^2 + 3z^2 + xy | 7 | 7 | 0 |
| xyz | 0 | 1 | 1 |
| x^4 | 1 | 1 | 0 |

The mixed cubic requires a correction; x^4 cancels across the unused
coordinates. Predictor exactness is not a standalone lossless codec contract.
Boundary handling, residual coding, rounding and reconstructed-value feedback
also matter.

The paper's two 4D examples do not establish that adding a time dimension
always helps. Its fluid-mixing data were quantized to one byte and temporally
subsampled by 100; the reported 3D slice output was smaller than the 4D output.
Those are published observations from that population, not this native test.

## Reproduce

Requires Git, CMake, GNU C++ with C++11 support, and Python 3 standard library.
No Python packages or network calls are required by the verifier. Clone the
upstream BSD-3-Clause project separately; it is not redistributed here.

```bash
git clone --branch 1.3.0 https://github.com/LLNL/fpzip.git fpzip-source
git -C fpzip-source checkout 4a539c06d98b1c029b08324a086d4b75689a2b72
python3 -B reproduce.py /absolute/path/to/fpzip-source
python3 -B verify.py
python3 -B -m unittest discover -s . -p test_verify.py
python3 -B -O -m unittest discover -s . -p test_verify.py
```

Run from the directory containing all files in this packet. The reproducer
checks the pinned clean source, builds SAFE arithmetic in two temporary
directories, runs upstream tests, replays the probe, requires equal native
captures, then regenerates native.jsonl, results.json and receipt.json.
Temporary compiler output is removed on exit. Receipt timestamps and host
metadata are expected to change; native results should be compared separately.

## Evidence and boundaries

- [fpzip API and representation domain](https://github.com/LLNL/fpzip/blob/4a539c06d98b1c029b08324a086d4b75689a2b72/include/fpzip.h)
- [Pinned bit mapping](https://github.com/LLNL/fpzip/blob/4a539c06d98b1c029b08324a086d4b75689a2b72/src/pcmap.inl)
- [Pinned predictor implementation](https://github.com/LLNL/fpzip/blob/4a539c06d98b1c029b08324a086d4b75689a2b72/src/write.cpp)
- [LLNL project and 2006 paper bibliography](https://computing.llnl.gov/projects/fpzip)
- [Lorenzo term](https://hesela.dev/terms/lorenzo-predictor/) and [fpzip term](https://hesela.dev/terms/fpzip/)

The native inputs are finite normals and signed zeros, not infinities, NaNs or
subnormals. No cross-platform portability, application-level error bound or
paper-performance replication is claimed. The exact-arithmetic predictor
examples are separate from fpzip's floating-point predictor. All counts and
errors refer to the retained input arrays and pinned codec configuration.
