[{"data":1,"prerenderedAt":577},["ShallowReactive",2],{"navigation":3,"\u002Fguides\u002Ftuning":222,"\u002Fguides\u002Ftuning-surround":572},[4,8,168,206,210,214,218],{"title":5,"path":6,"stem":7},"Quickstart","\u002Fquickstart","01.quickstart",{"title":9,"path":10,"stem":11,"children":12},"Concepts","\u002Fconcepts","20.concepts",[13,15,19,23,84,88,92,96,100],{"title":9,"path":10,"stem":14},"20.concepts\u002Findex",{"title":16,"path":17,"stem":18},"Preprocessing Graph","\u002Fconcepts\u002Fppg","20.concepts\u002F2.ppg",{"title":20,"path":21,"stem":22},"Plane decomposition","\u002Fconcepts\u002Fplanes","20.concepts\u002F3.planes",{"title":24,"path":25,"stem":26,"children":27},"Codecs","\u002Fconcepts\u002Fcodecs","20.concepts\u002F4.codecs",[28,32,36,40,44,48,52,56,60,64,68,72,76,80],{"title":29,"path":30,"stem":31},"Arithmetic","\u002Fconcepts\u002Fcodecs\u002Farithmetic","20.concepts\u002Fcodecs\u002Farithmetic",{"title":33,"path":34,"stem":35},"Context Mixing Lite","\u002Fconcepts\u002Fcodecs\u002Fcontext-mixing-lite","20.concepts\u002Fcodecs\u002Fcontext-mixing-lite",{"title":37,"path":38,"stem":39},"FPC","\u002Fconcepts\u002Fcodecs\u002Ffpc","20.concepts\u002Fcodecs\u002Ffpc",{"title":41,"path":42,"stem":43},"Huffman LLM 5-Bit","\u002Fconcepts\u002Fcodecs\u002Fhuff-llm","20.concepts\u002Fcodecs\u002Fhuff-llm",{"title":45,"path":46,"stem":47},"Huffman","\u002Fconcepts\u002Fcodecs\u002Fhuffman","20.concepts\u002Fcodecs\u002Fhuffman",{"title":49,"path":50,"stem":51},"Identity","\u002Fconcepts\u002Fcodecs\u002Fidentity","20.concepts\u002Fcodecs\u002Fidentity",{"title":53,"path":54,"stem":55},"Neural Predictor","\u002Fconcepts\u002Fcodecs\u002Fneural-predictor","20.concepts\u002Fcodecs\u002Fneural-predictor",{"title":57,"path":58,"stem":59},"Order-1 Arithmetic","\u002Fconcepts\u002Fcodecs\u002Forder1-arithmetic","20.concepts\u002Fcodecs\u002Forder1-arithmetic",{"title":61,"path":62,"stem":63},"Order-1 Scale AC","\u002Fconcepts\u002Fcodecs\u002Forder1-scale-ac","20.concepts\u002Fcodecs\u002Forder1-scale-ac",{"title":65,"path":66,"stem":67},"Per-Group Codebook","\u002Fconcepts\u002Fcodecs\u002Fper-group-codebook","20.concepts\u002Fcodecs\u002Fper-group-codebook",{"title":69,"path":70,"stem":71},"rANS","\u002Fconcepts\u002Fcodecs\u002Frans","20.concepts\u002Fcodecs\u002Frans",{"title":73,"path":74,"stem":75},"tANS","\u002Fconcepts\u002Fcodecs\u002Ftans","20.concepts\u002Fcodecs\u002Ftans",{"title":77,"path":78,"stem":79},"Zstd","\u002Fconcepts\u002Fcodecs\u002Fzstd","20.concepts\u002Fcodecs\u002Fzstd",{"title":81,"path":82,"stem":83},"Zstd Dictionary","\u002Fconcepts\u002Fcodecs\u002Fzstd-dict","20.concepts\u002Fcodecs\u002Fzstd-dict",{"title":85,"path":86,"stem":87},"Container format","\u002Fconcepts\u002Fcontainer","20.concepts\u002F5.container",{"title":89,"path":90,"stem":91},"Delta compression","\u002Fconcepts\u002Fdelta","20.concepts\u002F6.delta",{"title":93,"path":94,"stem":95},"Extensibility","\u002Fconcepts\u002Fextensibility","20.concepts\u002F7.extensibility",{"title":24,"path":25,"stem":97,"children":98},"20.concepts\u002Fcodecs\u002Findex",[99],{"title":24,"path":25,"stem":97},{"title":101,"path":102,"stem":103,"children":104},"Transforms","\u002Fconcepts\u002Ftransforms","20.concepts\u002Ftransforms\u002Findex",[105,106,110,114,118,122,126,130,134,140,144,148,152,156,160,164],{"title":101,"path":102,"stem":103},{"title":107,"path":108,"stem":109},"Alpha-Stable Normalize","\u002Fconcepts\u002Ftransforms\u002Falpha-stable-normalize","20.concepts\u002Ftransforms\u002Falpha-stable-normalize",{"title":111,"path":112,"stem":113},"Bit Reorder","\u002Fconcepts\u002Ftransforms\u002Fbit-reorder","20.concepts\u002Ftransforms\u002Fbit-reorder",{"title":115,"path":116,"stem":117},"Block Microscaling Repack","\u002Fconcepts\u002Ftransforms\u002Fblock-microscaling-repack","20.concepts\u002Ftransforms\u002Fblock-microscaling-repack",{"title":119,"path":120,"stem":121},"Burrows-Wheeler","\u002Fconcepts\u002Ftransforms\u002Fburrows-wheeler","20.concepts\u002Ftransforms\u002Fburrows-wheeler",{"title":123,"path":124,"stem":125},"Byte Split & Nibble Split","\u002Fconcepts\u002Ftransforms\u002Fbyte-split","20.concepts\u002Ftransforms\u002Fbyte-split",{"title":127,"path":128,"stem":129},"Concat","\u002Fconcepts\u002Ftransforms\u002Fconcat","20.concepts\u002Ftransforms\u002Fconcat",{"title":131,"path":132,"stem":133},"Delta","\u002Fconcepts\u002Ftransforms\u002Fdelta","20.concepts\u002Ftransforms\u002Fdelta",{"title":135,"path":136,"stem":137,"children":138},"Index Bitwidth Pack","\u002Fconcepts\u002Ftransforms\u002Findex-bitwidth-pack","20.concepts\u002Ftransforms\u002Findex-bitwidth-pack",[139],{"title":135,"path":136,"stem":137},{"title":141,"path":142,"stem":143},"IntDelta","\u002Fconcepts\u002Ftransforms\u002Fint-delta","20.concepts\u002Ftransforms\u002Fint-delta",{"title":145,"path":146,"stem":147},"Mantissa Zero Strip","\u002Fconcepts\u002Ftransforms\u002Fmantissa-zero-strip","20.concepts\u002Ftransforms\u002Fmantissa-zero-strip",{"title":149,"path":150,"stem":151},"Move to Front","\u002Fconcepts\u002Ftransforms\u002Fmove-to-front","20.concepts\u002Ftransforms\u002Fmove-to-front",{"title":153,"path":154,"stem":155},"MxFp4 Deinterleave","\u002Fconcepts\u002Ftransforms\u002Fmxfp4-deinterleave","20.concepts\u002Ftransforms\u002Fmxfp4-deinterleave",{"title":157,"path":158,"stem":159},"Predictor XOR","\u002Fconcepts\u002Ftransforms\u002Fpredictor-xor","20.concepts\u002Ftransforms\u002Fpredictor-xor",{"title":161,"path":162,"stem":163},"Reshape","\u002Fconcepts\u002Ftransforms\u002Freshape","20.concepts\u002Ftransforms\u002Freshape",{"title":165,"path":166,"stem":167},"Spherical Normalize","\u002Fconcepts\u002Ftransforms\u002Fspherical-normalize","20.concepts\u002Ftransforms\u002Fspherical-normalize",{"title":169,"path":170,"stem":171,"children":172},"Guides","\u002Fguides","30.guides\u002F00.index",[173,174,178,182,186,190,194,198,202],{"title":169,"path":170,"stem":171},{"title":175,"path":176,"stem":177},"CLI usage","\u002Fguides\u002Fcli","30.guides\u002F01.cli",{"title":179,"path":180,"stem":181},"Python API","\u002Fguides\u002Fpython-api","30.guides\u002F02.python-api",{"title":183,"path":184,"stem":185},"Writing your first extension","\u002Fguides\u002Fextension-authoring","30.guides\u002F03.extension-authoring",{"title":187,"path":188,"stem":189},"Trust and security","\u002Fguides\u002Ftrust-and-security","30.guides\u002F04.trust-and-security",{"title":191,"path":192,"stem":193},"Random access","\u002Fguides\u002Frandom-access","30.guides\u002F10.random-access",{"title":195,"path":196,"stem":197},"Tuning","\u002Fguides\u002Ftuning","30.guides\u002F11.tuning",{"title":199,"path":200,"stem":201},"Safetensors","\u002Fguides\u002Fsafetensors","30.guides\u002F50.safetensors",{"title":203,"path":204,"stem":205},"Transformers","\u002Fguides\u002Ftransformers","30.guides\u002F51.transformers",{"title":207,"path":208,"stem":209},"API reference","\u002Fapi","40.api",{"title":211,"path":212,"stem":213},"Benchmarks","\u002Fbenchmarks","50.benchmarks",{"title":215,"path":216,"stem":217},"Extensions","\u002Fextensions","60.extensions",{"title":219,"path":220,"stem":221},"Contributing","\u002Fcontributing","90.contributing",{"id":223,"title":195,"body":224,"description":566,"extension":567,"kind":568,"language":568,"links":568,"meta":569,"navigation":568,"path":196,"seo":570,"stem":197,"summary":568,"__hash__":571},"docs\u002F30.guides\u002F11.tuning.md",{"type":225,"value":226,"toc":558},"minimark",[227,232,241,248,253,288,291,299,318,322,338,375,378,396,400,403,420,423,439,446,450,519,525,532,536,554],[228,229,231],"h1",{"id":230},"tuning-compression-for-a-model","Tuning compression for a model",[233,234,235,236,240],"p",{},"The static ",[237,238,239],"code",{},"PRODUCTION_CHAINS"," table covers the common dtype + role\ncombinations. For an unfamiliar checkpoint — a new microscaling format,\nan unusual weight distribution, an experimental quantisation — the\nexplorer enumerates more chain candidates and picks the smallest\ntrial-encoded result per tensor.",[233,242,243,244,247],{},"Discovered chains land inline in the resulting ",[237,245,246],{},".ptwm"," container. They\ndecode on any PTWM install without changes — no source edits, no shared\nconfiguration. Tuning is purely a compress-time concern.",[249,250,252],"h2",{"id":251},"run-the-explorer-on-one-model","Run the explorer on one model",[254,255,260],"pre",{"className":256,"code":257,"language":258,"meta":259,"style":259},"language-bash shiki shiki-themes material-theme-lighter github-light github-dark","ptwm compress model.safetensors --explore --out model.ptwm\u002F\n","bash","",[237,261,262],{"__ignoreMap":259},[263,264,267,271,275,278,282,285],"span",{"class":265,"line":266},"line",1,[263,268,270],{"class":269},"sbgvK","ptwm",[263,272,274],{"class":273},"s_sjI"," compress",[263,276,277],{"class":273}," model.safetensors",[263,279,281],{"class":280},"stzsN"," --explore",[263,283,284],{"class":280}," --out",[263,286,287],{"class":273}," model.ptwm\u002F\n",[233,289,290],{},"Sample output:",[254,292,297],{"className":293,"code":295,"language":296},[294],"language-text","Compressing model.safetensors → model.ptwm (--explore budget 5000ms per group)\n\nExplored 12 additional chain candidates across 2 (dtype, role) group(s) beyond the production defaults:\n  - dtype=0x001F role=packed_values: 8 candidate(s), first seen on model.weight\n  - dtype=0x0006 role=scale_block: 4 candidate(s), first seen on model.weight_scale\nOutput: 4.2 GB (input: 5.0 GB, ratio 0.8401)\nDiscovered chains are stored inline in the .ptwm container and decode on any PTWM install.\n","text",[237,298,295],{"__ignoreMap":259},[233,300,301,302,305,306,309,310,313,314,317],{},"The explorer runs at most ",[237,303,304],{},"--explore-budget-ms"," per ",[237,307,308],{},"(dtype, role)"," pair\nand yields at most ",[237,311,312],{},"--explore-max-candidates"," per pair. Defaults are\n5000 ms and 32, respectively. Total wall-clock cost is approximately\n",[237,315,316],{},"budget × number-of-distinct-(dtype, role)-pairs",".",[249,319,321],{"id":320},"re-use-discoveries-on-subsequent-runs","Re-use discoveries on subsequent runs",[233,323,324,325,328,329,332,333,337],{},"PTWM caches every discovered chain template under\n",[237,326,327],{},"$XDG_CACHE_HOME\u002Fptwm\u002Fchains\u002F",". Every ",[237,330,331],{},"--explore"," run consults the\ncache, so the ",[334,335,336],"em",{},"second"," time you compress a checkpoint of the same\nmodel class, the BFS skips groups it has already covered.",[254,339,341],{"className":256,"code":340,"language":258,"meta":259,"style":259},"ptwm chains cache info     # list cached entries\nptwm chains cache clear    # wipe the cache\n",[237,342,343,360],{"__ignoreMap":259},[263,344,345,347,350,353,356],{"class":265,"line":266},[263,346,270],{"class":269},[263,348,349],{"class":273}," chains",[263,351,352],{"class":273}," cache",[263,354,355],{"class":273}," info",[263,357,359],{"class":358},"sutJx","     # list cached entries\n",[263,361,363,365,367,369,372],{"class":265,"line":362},2,[263,364,270],{"class":269},[263,366,349],{"class":273},[263,368,352],{"class":273},[263,370,371],{"class":273}," clear",[263,373,374],{"class":358},"    # wipe the cache\n",[233,376,377],{},"To bypass the cache for one run:",[254,379,381],{"className":256,"code":380,"language":258,"meta":259,"style":259},"ptwm compress model.safetensors --explore --no-cache\n",[237,382,383],{"__ignoreMap":259},[263,384,385,387,389,391,393],{"class":265,"line":266},[263,386,270],{"class":269},[263,388,274],{"class":273},[263,390,277],{"class":273},[263,392,281],{"class":280},[263,394,395],{"class":280}," --no-cache\n",[249,397,399],{"id":398},"share-a-tuned-chain-set","Share a tuned chain set",[233,401,402],{},"To publish a tuned set for one model family without committing it to the\nlibrary:",[254,404,406],{"className":256,"code":405,"language":258,"meta":259,"style":259},"ptwm chains export .\u002Fllama-3-nvfp4.chains\n",[237,407,408],{"__ignoreMap":259},[263,409,410,412,414,417],{"class":265,"line":266},[263,411,270],{"class":269},[263,413,349],{"class":273},[263,415,416],{"class":273}," export",[263,418,419],{"class":273}," .\u002Fllama-3-nvfp4.chains\n",[233,421,422],{},"A peer can load the same set into their cache:",[254,424,426],{"className":256,"code":425,"language":258,"meta":259,"style":259},"ptwm chains import .\u002Fllama-3-nvfp4.chains\n",[237,427,428],{"__ignoreMap":259},[263,429,430,432,434,437],{"class":265,"line":266},[263,431,270],{"class":269},[263,433,349],{"class":273},[263,435,436],{"class":273}," import",[263,438,419],{"class":273},[233,440,441,442,445],{},"Import validates every chain through ",[237,443,444],{},"is_legal_chain"," before storing it,\nso a malformed bundle gets rejected without poisoning the cache.",[249,447,449],{"id":448},"when-tuning-pays-off","When tuning pays off",[451,452,453,471],"table",{},[454,455,456],"thead",{},[457,458,459,463,466],"tr",{},[460,461,462],"th",{},"Tensor class",[460,464,465],{},"Typical ratio with defaults",[460,467,468,469],{},"Typical extra gain from ",[237,470,331],{},[472,473,474,486,497,508],"tbody",{},[457,475,476,480,483],{},[477,478,479],"td",{},"bfloat16 \u002F float16 \u002F float32 weights",[477,481,482],{},"0.55 – 0.75",[477,484,485],{},"Negligible — production chains already cover the exponent-plane separation.",[457,487,488,491,494],{},[477,489,490],{},"FP8 weights",[477,492,493],{},"0.70 – 0.85",[477,495,496],{},"Small — the explorer rarely beats the nibble-split default.",[457,498,499,502,505],{},[477,500,501],{},"MXFP4 \u002F NVFP4 paired tensors",[477,503,504],{},"0.86 – 0.90",[477,506,507],{},"Marginal at the byte level; scale-codec dominates the savings.",[457,509,510,513,516],{},[477,511,512],{},"Unfamiliar dtype \u002F role with no production entry",[477,514,515],{},"n\u002Fa → 1.0 (passthrough)",[477,517,518],{},"Often substantial — the explorer can replace passthrough with a real chain.",[233,520,521,522,524],{},"The last row is where exploration earns its keep. For familiar dtypes,\nthe production table is already tuned and ",[237,523,331],{}," mostly confirms\nit.",[233,526,527,528,531],{},"Run ",[237,529,530],{},"tests\u002Fptwm\u002Fbenchmarks\u002Ftest_explore_savings.py -m slow"," for a\nsynthetic measurement of size and time deltas on your hardware.",[249,533,535],{"id":534},"promoting-a-discovered-chain-into-the-library","Promoting a discovered chain into the library",[233,537,538,539,542,543,546,547,550,551,553],{},"The user cache and the export\u002Fimport flow cover nearly all real use.\nIf a chain proves itself across many users and deserves to ship as a\ndefault, a library maintainer runs ",[237,540,541],{},"ptwm chains promote"," on a captured\naudit log to see a structural breakdown of the discovered chain — then\nhand-writes a named builder in ",[237,544,545],{},"python\u002Fptwm\u002Fpreprocessing\u002F_chains.py","\nfollowing the existing ",[237,548,549],{},"CHAIN_*"," pattern and registers it in the\n",[237,552,239],{}," table.",[555,556,557],"style",{},"html pre.shiki code .sbgvK, html code.shiki .sbgvK{--shiki-light:#E2931D;--shiki-default:#6F42C1;--shiki-dark:#B392F0}html pre.shiki code .s_sjI, html code.shiki .s_sjI{--shiki-light:#91B859;--shiki-default:#032F62;--shiki-dark:#9ECBFF}html pre.shiki code .stzsN, html code.shiki .stzsN{--shiki-light:#91B859;--shiki-default:#005CC5;--shiki-dark:#79B8FF}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .sutJx, html code.shiki .sutJx{--shiki-light:#90A4AE;--shiki-light-font-style:italic;--shiki-default:#6A737D;--shiki-default-font-style:inherit;--shiki-dark:#6A737D;--shiki-dark-font-style:inherit}",{"title":259,"searchDepth":559,"depth":559,"links":560},3,[561,562,563,564,565],{"id":251,"depth":362,"text":252},{"id":320,"depth":362,"text":321},{"id":398,"depth":362,"text":399},{"id":448,"depth":362,"text":449},{"id":534,"depth":362,"text":535},"Run the chain explorer to find dtype-aware compression chains beyond the defaults; cache, share, and import discovered chains.","md",null,{},{"title":195,"description":566},"h6uFN0htBLk-OVFzFYRuF0SpmLmnEykc5i_dm80KG7o",[573,575],{"title":191,"path":192,"stem":193,"description":574,"children":-1},"Open a `.ptwm` bundle and fetch individual tensors without decompressing the whole file.",{"title":199,"path":200,"stem":201,"description":576,"children":-1},"Patch the safetensors loader so existing code decompresses sibling `.ptwm` payloads transparently.",1784796354450]