transforms
ptwm_core::transforms::mantissa_zero
MantissaZeroStrip op — strip a uniform run of trailing zero bits from every byte of a quantized-weight mantissa plane.
ptwm_core::transforms::mantissa_zero
MantissaZeroStrip op — strip a uniform run of trailing zero bits from every byte of a quantized-weight mantissa plane.
ptwm_core::transforms::mantissa_zero
crates/ptwm-core/src/transforms/mantissa_zero.rs:1mod mantissa_zero`MantissaZeroStrip` op — strip a uniform run of trailing zero bits from every byte of a quantized-weight mantissa plane.
## Motivation
GPTQ / AWQ-style quantized checkpoints store weights with rounded
mantissas: an INT4-quantized weight, after dequantization back into
BF16 / FP16, has a mantissa whose low bits are always exactly zero.
After PTWM's standard `bit_reorder_ieee` + `byte_split` chain, the
mantissa plane is a flat byte stream where every element shares
the same uniform run of trailing zero bits. Without exploiting this
the downstream entropy coder sees a value range that is 2^k times
larger than the true alphabet, which costs roughly k bits per
element of compression on GGUF / GPTQ-style checkpoints.
## Scope of this op
The op handles the dominant case: a *uniform* `k` (1..=7) that holds
across every byte in the plane. The chain author (or the explorer)
picks `k` at chain-build time and the op stores it as a one-byte
parameter on the wire. At encode time the op validates that every
byte's low `k` bits are zero; if any byte fails the check the op
returns an error and the trial-encode dispatcher falls back to a
chain that does not include this op.
A non-uniform per-element variant (the "run-length" reading of the
issue title) would need a side bitmap and a sparse value buffer; it
is deliberately out of scope here. The uniform case captures the
published gap and stays a simple invertible byte transform.
ptwm_core::transforms::mantissa_zero::MantissaZeroStrip
crates/ptwm-core/src/transforms/mantissa_zero.rs:46pub struct MantissaZeroStripRight-shift every byte in a plane by `k` bits. Inverse left-shifts by `k`. The op requires that every input byte has at least `k` trailing zero bits — otherwise the right-shift would lose information and the inverse could not recover the original byte.
`k` is the wire-format parameter (1..=7). `k == 0` is rejected at
construction because it would make the op a pure no-op and adds
only cost; `k >= 8` is rejected because shifting a `u8` by 8 or
more zeroes every byte and loses any high-bit information.