Lossless compression for PyTorch weights.
PTWM is a lossless weight-compression library for PyTorch checkpoints. It exploits the byte-level structure of IEEE 754 floats and the layout of microscaling formats (MXFP4 / NVFP4) to recover compression beyond what generic byte-level codecs reach, with parallel encode and decode through a native Rust extension.
from ptwm import Compressor, Decompressor, CompressionConfig, Format
import torch
config = CompressionConfig(input_format=Format.TORCH)
compressor, decompressor = Compressor(config), Decompressor()
tensor = torch.randn(1024, 1024, dtype=torch.bfloat16)
restored = decompressor.decompress(compressor.compress(tensor))
assert torch.equal(tensor, restored)
Components
Six pieces, each built around the byte-level structure of trained weights: a preprocessing graph that exposes low-entropy planes, codecs that operate on them, a self-describing container, and integrations for the standard loading paths.
Exponent-plane separation
IEEE 754 bit-reorder plus byte / nibble split isolates the exponent into its own plane. The resulting plane carries ≈ 2.6 bits/byte of entropy on trained weights; the raw byte stream appears near-uniform.
Microscaling-aware codecs
An order-1 arithmetic coder fitted to MXFP4 E8M0 scale distributions compresses the scale plane to ≈ 0.16 of original. NVFP4 FP8-E4M3 scales route through an FP8-split chain.
Random-access container
The .ptwm format bundles tensors with a name-indexed manifest, per-plane codec dispatch records, and hash-verified payloads. A reader fetches a single tensor without scanning the rest.
Native Rust core
PyO3 extension with rayon-parallel encode and decode, zero-copy buffer protocol, and pure-Rust Huffman and rANS codecs. No C dependencies.
safetensors and HuggingFace integration
The patch_safetensors() and patch_transformers() helpers decompress sibling .ptwm payloads inside the standard load_state_dict path; calling code requires no changes.
Command-line interface
The ptwm compress and ptwm decompress commands accept single files, directories, and delta compression against a reference checkpoint.
Expected ratios
Compressed bytes ÷ raw bytes — lower is better. Theoretical per-DType ranges; measured numbers across production checkpoints (Llama 3, Mixtral, GPT-OSS, Qwen, DiT) are reported on the benchmarks page.
bfloat16, float16, float32
≈ 0.55 – 0.75. Exponent-plane separation.
float8_e4m3fn, float8_e5m2
≈ 0.70 – 0.85. Nibble-split + plane-aware Huffman.
MXFP4 (FP4 + E8M0)
≈ 0.86 – 0.90. FP4 nibble plane near-uniform; the random-access container and scale-codec carry the gain.
NVFP4 (FP4 + FP8-E4M3)
≈ 0.90. As MXFP4, with an FP8-aware scale codec; FP4 nibbles dominate the residual.