# zfp: choose the error budget before the storage budget

A small absolute error can erase a small signal. In this native zfp 1.0.1
example, fixed precision 16 maps both small nonzero entries of
`[1, 2^-30, -2^-40, 0]` to zero. The maximum absolute error is 2^-30;
the maximum pointwise relative error is 100%.

## What was executed

[probe.c](probe.c) calls the unmodified zfp library on seven constructed
binary32 arrays using eight settings each: fixed rates 8 and 16, precisions
16 and 24, absolute tolerances 1e-3 and 1e-6, zero tolerance, and reversible
mode. The 56 rows include smooth and rough 8 by 8 arrays, a scaled smooth
array, a 5 by 3 edge-block case, signed zeros and two four-value controls.
They are not representative workload samples.

[native.jsonl](native.jsonl) contains hexadecimal inputs and reconstructions,
complete compressed bytes, effective API parameters and bitwise comparisons.
[results.json](results.json) contains hashes and exact-rational error
calculations. [verify.py](verify.py) independently reconstructs the inputs,
checks the complete case matrix and computes the error denominators.
[test_verify.py](test_verify.py) includes malformed-evidence controls.

## Observed contrasts

| Input and setting | Original bytes | Payload bytes | Maximum absolute error |
| --- | ---: | ---: | ---: |
| Smooth 8 by 8, rate 8 | 256 | 64 | 0 |
| Rough 8 by 8, rate 8 | 256 | 64 | 0.771484375 |
| Smooth 8 by 8, tolerance 1e-3 | 256 | 40 | 0 |
| Rough 8 by 8, tolerance 1e-3 | 256 | 160 | 0.000186920166015625 |
| Partial 5 by 3, rate 8 | 60 | 32 | 0 |
| Decimal four-value control, tolerance 0 | 16 | 24 | approximately 5.47e-9 |
| Decimal four-value control, reversible | 16 | 16 | 0 |

The same fixed-rate payload size permits different errors. A fixed error
setting permits different sizes. The API returns an effective tolerance of
2^-10 for the requested 1e-3. All 14 positive-tolerance cases met their
effective tolerance; this finite check is not a universal guarantee.

The partial array needs two padded 4 by 4 blocks: 2 x 16 x 8 = 256 bits,
or 32 bytes. Dividing by the 15 original values gives 256/15, approximately
17.07 payload bits per input value, not 8. With the default 64-bit stream
words, the final payload is rounded to a whole word; the four-value rate-8
case therefore occupies 8 bytes although its block budget is 32 bits.
Payload excludes headers, external metadata, unused allocation and caches.

The decimal control stores binary32 approximations to 1, 0.1, 0.01 and 0.001.
Errors are relative to those stored values, not ideal decimal fractions.
Signed-zero controls distinguish zero numerical error from byte identity.
All seven reversible rows match the input bytes exactly.

## Why the distinctions matter

The [2014 paper](https://doi.org/10.1109/TVCG.2014.2346458) investigates
fixed-rate block coding and random access. Its evaluation uses
double-precision physics-simulation fields and application-specific
quality measures, including visualization and simulation behavior.
Those results do not establish a safe bit rate for an unrelated workload.

The [2019 error analysis, v3](https://arxiv.org/abs/1805.00546v3)
models the individual encoding and decoding steps. Sections 5-6 separate
block-relative from componentwise error and test the bounds using
constructed blocks and simulation fields. The relationship depends on
within-block dynamic range. It is not a statistical confidence interval.
The related journal DOI is 10.1137/18M1168832.

The [versioned algorithm](https://zfp.readthedocs.io/en/release1.0.1/algorithm.html)
uses exponent alignment and a block transform before bit-plane coding.
The [mode documentation](https://zfp.readthedocs.io/en/release1.0.1/modes.html)
distinguishes a storage budget, coefficient precision and absolute accuracy.
The [FAQ](https://zfp.readthedocs.io/en/release1.0.1/faq.html) explains finite
precision limits and why zero tolerance must not be substituted for
reversible compression.

Choose a numerical acceptance test before choosing a rate. Record units,
zero handling, scalar type, shape, layout, codec version and mode. Test
downstream quantities separately; matching a local tolerance alone does not
validate a scientific conclusion.

## Reproduce

Source: [LLNL/zfp 1.0.1](https://github.com/LLNL/zfp/tree/f40868a6a1c190c802e7d8b5987064f044bf7812),
commit `f40868a6a1c190c802e7d8b5987064f044bf7812`, BSD-3-Clause.
Only the Hesela probe and its outputs are distributed here. Paper PDFs and
third-party library sources are not redistributed.

Observed environment: Linux x86-64, GCC 13.3.0; serial Release build,
64-bit stream words, default ZFP_ROUND_NEVER, no headers or custom strides.
Run these commands in a directory containing the five linked evidence files:

```sh
git clone --branch 1.0.1 --depth 1 https://github.com/LLNL/zfp.git zfp
git -C zfp rev-parse HEAD
cmake -S zfp -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=OFF -DBUILD_TESTING=OFF -DBUILD_UTILITIES=OFF -DBUILD_EXAMPLES=OFF -DZFP_WITH_OPENMP=OFF
cmake --build build -j 2
cc -std=c99 -O2 -Wall -Wextra -Werror -I zfp/include probe.c build/lib/libzfp.a -lm -o probe
./probe > replay.jsonl
cmp replay.jsonl native.jsonl
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
```

Confirm the printed commit before building. Exact byte replay is expected
for the stated implementation/settings; do not silently replace the recorded
evidence when testing a different version. No timing, power-loss, nonfinite,
subnormal, 3D/4D, binary64 or repeated-simulation behavior was measured.
Relative error excludes original zeros; their absolute errors are reported
separately. Block-relative errors use valid input entries of each block,
not padding. Numerical equality and bitwise equality are separate fields.
