FORMATS.md

metadata

license: apache-2.0
tags:
  - cortiq
  - cmf
  - quantization

Which file to take — the CMF quantization ladder

Every .cmf on this account is the same model twice over: the same weights, written at a different number of bits per weight. This page says what those names mean, what each one costs you, and how to pick without downloading two.

Short version:

suffix	bits/weight	take it when
f16	16	you are checking a port against the reference
q8	8.1	quality is the whole point and the file still fits
q4tp	4.17	the default. Everything published here uses it
q4t	4.50	same values as q4tp, older scale layout
q2tp	2.17	the model is a MoE and you are trading experts for size
q1t	~2.25 + overlay	a normal checkpoint pushed below q4, with calibration
q1	1.5	the model was trained at 1 bit (BitNet/Bonsai class)
vbit	3–8, per row	one file has to fit an awkward memory budget exactly

Normalization weights, biases and anything one-dimensional are always f16, in every file. Compression buys nothing there and precision costs nothing.

q4tp, and why the scale is the interesting part

A four-bit quantizer stores a nibble per weight and a scale per group of 32. At f16 that scale is 16 bits per 32 weights — 11% of the file, spent on a number that varies smoothly along a row.

q4tp keeps the nibbles byte-identical to q4t and replaces the scale with a 5-bit rung on a per-row geometric ladder: scale = 2^(lo + code·step), with lo and step taken from the row's own min and max log-scale. A reader expands one row's 32 rungs once and then reads scales by table lookup. The file drops from 4.50 to 4.17 bits/weight — 7.3% — for 1.14% RMS perturbation of the weights, against the ~10% that four-bit quantization itself already costs. It is, in short, free.

q2tp is the same ladder with a two-bit weight plane (8 bytes a group instead of 16). One detail matters more than it sounds: a symmetric 4-level grid cannot spell zero, so rung 0 is reserved to mean "this group is exactly zero" and the geometric rungs start at 1. Without that a pruned or masked group comes back as noise.

q1t — below four bits without training

q1t is ternary {−s, 0, +s}, packed base-3 at five values per byte (3⁵ = 243 ≤ 256) for 2.25 bits/weight, plus a per-row overlay that keeps the salient weights at f16. Two things make it work where plain 1-bit does not: capturing the many near-zero weights exactly (the zero level is the win over binary — measured ×7 better at matched budget), and choosing what to keep in the overlay by |W|·RMS(x) — amplitude times activation, not amplitude alone.

It is calibration-driven, not a flag on convert: see docs/Q1T_PTQ.md.

q1 — only for models trained at one bit

For a BitNet-class checkpoint (Bonsai, and the 1-bit trained families) the weights already sit on two levels per group, so 1.5 bits/weight is nearly lossless. As post-training quantization of a normal checkpoint the same encoding destroys the model. The converter therefore exposes it as an explicit opt-in and never as a default.

What the packer decides for you in a video model

Text models are uniform: one dtype for every matrix. Generative containers are not, and the choices are worth knowing because they are where the size goes.

The modulation weight is a curve, not a matrix. MiniMax-H3's adaln_proj.linear is [96768, 2688] per block — 13 B parameters, 40% of the released model — for a map whose input is one number, the timestep. cortiq animate-pack collapses it onto a rank-24 basis of that curve plus a [1025, 24] table to interpolate: rms 8.7e-5 on a signal of rms 0.46. This is most of the difference between a 60 GB checkout and a 14 GB file, and it is lossless in the way that matters — the map is genuinely one-dimensional.

Some tensors are kept exact because nothing downstream blurs them. In the LTX-2.5 pack, three policies were found by the parity gate rather than by taste: the adaLN-single projections stay high precision (q4tp put 3.6e-2 into the first normalization of block 0), and the token table goes to q8 (q4tp put 11% into every hidden state). A quantizer that is right for a 4096×4096 projection is wrong for a lookup table.

A published dead end. mmh3-turbo-fl2va-q2tp.cmf exists so that the result is reproducible, not because you should render with it: two bits across a dense video DiT changes the subject of the clip. The size class it was aiming at is better served by the ClipProj build, which keeps four bits everywhere and shrinks the prompt encoder instead.

Checking what you got

cortiq verify model.cmf   # per-tensor hashes — the file, not the download
cortiq info   model.cmf   # arch, parameter count, dtype per tensor family

verify is the reason a truncated or mis-mirrored download cannot quietly become a "bad model": every tensor carries its own hash, and the file says so before the first kernel runs.

Where the ladder is honest

• q4tp numbers above are measured on the published containers, not estimated: 4.17 vs 4.50 bits/weight is arithmetic, and the 1.14% RMS figure is against the same weights encoded as q4t.
• Quality claims per model live in that model's card, with the corpus named. Where a number was not measured, the card says so.
• The full dtype × execution-path matrix — which format is fast on which backend, and where the honest gaps are — is docs/QUANT_COVERAGE.ru.md.
• The normative layout of every dtype is §3.2 of CMF_V2_SPEC.md.