Tuning
Tuning compression for a model
The static PRODUCTION_CHAINS table covers the common dtype + role
combinations. For an unfamiliar checkpoint — a new microscaling format,
an unusual weight distribution, an experimental quantisation — the
explorer enumerates more chain candidates and picks the smallest
trial-encoded result per tensor.
Discovered chains land inline in the resulting .ptwm container. They
decode on any PTWM install without changes — no source edits, no shared
configuration. Tuning is purely a compress-time concern.
Run the explorer on one model
ptwm compress model.safetensors --explore --out model.ptwm/
Sample output:
Compressing model.safetensors → model.ptwm (--explore budget 5000ms per group)
Explored 12 additional chain candidates across 2 (dtype, role) group(s) beyond the production defaults:
- dtype=0x001F role=packed_values: 8 candidate(s), first seen on model.weight
- dtype=0x0006 role=scale_block: 4 candidate(s), first seen on model.weight_scale
Output: 4.2 GB (input: 5.0 GB, ratio 0.8401)
Discovered chains are stored inline in the .ptwm container and decode on any PTWM install.
The explorer runs at most --explore-budget-ms per (dtype, role) pair
and yields at most --explore-max-candidates per pair. Defaults are
5000 ms and 32, respectively. Total wall-clock cost is approximately
budget × number-of-distinct-(dtype, role)-pairs.
Re-use discoveries on subsequent runs
PTWM caches every discovered chain template under
$XDG_CACHE_HOME/ptwm/chains/. Every --explore run consults the
cache, so the second time you compress a checkpoint of the same
model class, the BFS skips groups it has already covered.
ptwm chains cache info # list cached entries
ptwm chains cache clear # wipe the cache
To bypass the cache for one run:
ptwm compress model.safetensors --explore --no-cache
Share a tuned chain set
To publish a tuned set for one model family without committing it to the library:
ptwm chains export ./llama-3-nvfp4.chains
A peer can load the same set into their cache:
ptwm chains import ./llama-3-nvfp4.chains
Import validates every chain through is_legal_chain before storing it,
so a malformed bundle gets rejected without poisoning the cache.
When tuning pays off
| Tensor class | Typical ratio with defaults | Typical extra gain from --explore |
|---|---|---|
| bfloat16 / float16 / float32 weights | 0.55 – 0.75 | Negligible — production chains already cover the exponent-plane separation. |
| FP8 weights | 0.70 – 0.85 | Small — the explorer rarely beats the nibble-split default. |
| MXFP4 / NVFP4 paired tensors | 0.86 – 0.90 | Marginal at the byte level; scale-codec dominates the savings. |
| Unfamiliar dtype / role with no production entry | n/a → 1.0 (passthrough) | Often substantial — the explorer can replace passthrough with a real chain. |
The last row is where exploration earns its keep. For familiar dtypes,
the production table is already tuned and --explore mostly confirms
it.
Run tests/ptwm/benchmarks/test_explore_savings.py -m slow for a
synthetic measurement of size and time deltas on your hardware.
Promoting a discovered chain into the library
The user cache and the export/import flow cover nearly all real use.
If a chain proves itself across many users and deserves to ship as a
default, a library maintainer runs ptwm chains promote on a captured
audit log to see a structural breakdown of the discovered chain — then
hand-writes a named builder in python/ptwm/preprocessing/_chains.py
following the existing CHAIN_* pattern and registers it in the
PRODUCTION_CHAINS table.