# FPC residual costs and pFPC memory budgets

An exact integer worksheet, not a codec implementation, benchmark or paper replication.

## Worked example
Residual 0x0000000012345678 needs four ordinary bytes. FPC's eight payload-length
choices omit four, so this residual takes five. A pair requires 2 * 5 + 1 = 11
bytes including its shared control byte, before stream and block headers.
Residual cost alone says nothing about prediction accuracy on a workload.

The nine boundary rows cover zero and every ordinary byte length. Payload
choices are 0, 1, 2, 3, 5, 6, 7 and 8, following section 2 and the coding
explanation in [the implementation note](https://userweb.cs.txstate.edu/~burtscher/papers/tr08.pdf).

## Fair memory comparison
| Level | Threads | Predictor tables only |
| --- | --- | --- |
| 20 | 1 | 16 MiB |
| 20 | 4 | 64 MiB |
| 18 | 4 | 16 MiB |

These evaluate threads * 2^(level + 4), not resident memory. Buffers, stacks and
allocator overhead are excluded. The parameter is documented by the
[pFPC project](https://userweb.cs.txstate.edu/~burtscher/research/pFPC/).
Fixed per-thread and fixed total memory are different experimental controls.
This arithmetic does not predict which configuration wins.

## Reproduce
Use Python 3 and its standard library with ledger.py, test_ledger.py and results.json:

```sh
python3 -B ledger.py --check
python3 -B -m unittest discover -s . -p test_ledger.py
python3 -B -O -m unittest discover -s . -p test_ledger.py
```

Tests cover every byte-length boundary, eight codes, invalid inputs, memory
budgets and 1,007 integer bit-pattern XOR round trips with a fixed seed.
Some patterns encode signed zero, infinities or NaNs, but no float conversion
occurs. The algebraic identity does not establish full-codec support.

No third-party codec source, dataset or figure is redistributed. The worksheet
is original Hesela code. A length-code decoder is not an integrity checker.
Related definitions: [FPC](https://hesela.dev/terms/fpc/) and
[pFPC](https://hesela.dev/terms/pfpc/).
