README: one 'Making it smaller' section, a Which-file table keyed on VRAM, three-way sample comparison

README.md

@@ -14,7 +14,7 @@ tags:
 - 4-bit
 ---
 
-# MiniMax-H3 Turbo — one 23.5 GB file, no Python
+# MiniMax-H3 Turbo — one file, no Python
 
 [MiniMax-H3](https://huggingface.co/Comfy-Org/MiniMax-H3) renders video and
 synchronized stereo audio from one prompt, in one transformer, on two flow
@@ -31,9 +31,11 @@ underneath.
 | prompt encoder | 51.5 GB (bf16) | — |
 | video + audio VAE | 5.8 GB | — |
 | Turbo LoRA | 0.8 GB | — |
-| **total** | **124.4 GB, four files + a ComfyUI checkout** | **23.5 GB, one file** |
+| **total** | **124.4 GB, four files + a ComfyUI checkout** | **13.2–23.9 GB, one file** |
 
-47.83 B parameters, 2 361 tensors, `cortiq verify` clean.
+47.83 B parameters, 2 361 tensors, `cortiq verify` clean. The 13.2 GB end of
+that range swaps the prompt encoder for a 4B stand-in and fits a 20 GB card
+whole — [see below](#making-it-smaller).
 
 ## What comes out
 
@@ -59,12 +61,19 @@ give it a first and/or last frame and it continues from there. The release's
 third path — `ref2va`, conditioning on reference images, clips and audio — is
 not ported.
 
-| file | size | |
-|---|---|---|
-| `mmh3-turbo-fl2va-q4tp.cmf` | 23.94 GB | **use this one** — text-to-video AND keyframe-to-video |
-| `mmh3-turbo-q4tp.cmf` | 23.47 GB | the same without the vision tower: text-to-video only |
-| `mmh3-turbo-clipproj4b-q4tp.cmf` | **13.16 GB** | text-to-video with a 4B stand-in prompt encoder. Peaks at 15.1 GB of VRAM, so a 20 GB card holds the whole run instead of paging it; still four bits everywhere. Costs some set dressing — see below |
-| `mmh3-turbo-fl2va-q2tp.cmf` | 18.74 GB | two bits on the gate/up planes. Smaller, faster, and it stops following the prompt — kept for anyone who wants to push on it, not for rendering. See below |
+### Which file
+
+Start from how much VRAM you have; that decides more than anything else here.
+
+| file | size | keyframes | take it when |
+|---|---|---|---|
+| `mmh3-turbo-fl2va-q4tp.cmf` | 23.94 GB | yes | **the default.** 24 GB of VRAM or more, or you are happy to page |
+| `mmh3-turbo-q4tp.cmf` | 23.47 GB | no | same weights without the vision tower, if you only ever type prompts |
+| **`mmh3-turbo-clipproj4b-q4tp.cmf`** | **13.16 GB** | no | **16–20 GB of VRAM.** A 4B stand-in prompt encoder; peaks at 15.1 GB, so the run stays resident instead of paging. Still four bits everywhere |
+| `mmh3-turbo-fl2va-q2tp.cmf` | 18.74 GB | yes | **don't render with this.** Two bits stopped it following the prompt; kept as a starting point for anyone pushing on it |
+
+Both smaller files are explained under [Making it smaller](#making-it-smaller),
+with the same prompt rendered through each.
 
 ## Keyframe to video
 
@@ -112,7 +121,9 @@ cortiq --version
 
 ### 2. Get the weights
 
-One file, 23.5 GB.
+One file. Pick it from [Which file](#which-file) above — this is the
+text-to-video default; swap the name for `mmh3-turbo-clipproj4b-q4tp.cmf` if
+you are on a 20 GB card.
 
 ```bash
 pip install -U "huggingface_hub[cli]"      # only to fetch the file
@@ -201,7 +212,22 @@ peaks at 15.1 GB of VRAM — a whole-run maximum, polled, not a snapshot. That i
 what makes it the one to reach for on a 20 GB card: below that the prompt
 encoder pages, and on this workload paging costs more than any kernel.
 
-## Two bits: smaller, faster, and answering a different question
+## Making it smaller
+
+Half this file is the PROMPT ENCODER — 12.2 GB of Qwen3-VL against the DiT that
+actually draws. Two ways to act on that were tried. **Squeezing it does not
+work; replacing it does.** Same prompt, same seed, same four steps through all
+three:
+
+| four bits, 32B encoder | four bits, 4B + ClipProj | two bits, 32B encoder |
+|---|---|---|
+| ![32B](https://huggingface.co/infosave/MiniMax-H3-Turbo-cmf/resolve/main/samples/ab_q4tp.gif) | ![ClipProj](https://huggingface.co/infosave/MiniMax-H3-Turbo-cmf/resolve/main/samples/ab_clipproj.gif) | ![two bits](https://huggingface.co/infosave/MiniMax-H3-Turbo-cmf/resolve/main/samples/ab_q2tp.gif) |
+| 23.94 GB — the reference | **13.16 GB — still the right clip** | 18.74 GB — a different clip |
+
+Left and centre are the same scene with different furniture. Right is a
+different animal with no pan and no pancake. The two sections below are why.
+
+### Two bits: smaller, faster, and answering a different question
 
 The obvious next cut is the DeepSeek-V4 policy: gate/up at two bits,
 everything else at four. It builds — 23.94 GB down to **18.74**, and
@@ -237,7 +263,7 @@ measuring next — the packer's policy is one predicate,
 that experiment starts from something rather than nothing; four bits is
 what to render with.
 
-## A smaller encoder instead of fewer bits
+### A smaller encoder: replace it, don't squeeze it
 
 The two-bit section above ends on a diagnosis: half this file is the PROMPT
 ENCODER, and squeezing it is what broke the prompt. There is a second way to act
@@ -259,7 +285,7 @@ both VAE decoders, still `q4tp`. Nothing anywhere is two bits.
 
 **23.47 GB → 13.16 GB.** The encoder went from 552 tensors to 277.
 
-### Does it still mean the same thing?
+#### Does it still mean the same thing?
 
 That is measurable without rendering a frame: dump what the DiT actually
 receives (`CMF_TE_DUMP=<path>`) from both files on one prompt, and take the
@@ -278,7 +304,7 @@ attention sink is an outlier no regression fits — and it lands at cosine
 **0.9999** against the teacher's, which is the sharpest single confirmation
 that the mechanism is wired right.
 
-### What it costs
+#### What it buys
 
 The one number that transfers between machines is the **encode stage**, because
 that is the only stage ClipProj replaced. Same prompt, seed and four steps,
@@ -305,15 +331,10 @@ there is nothing left to page.
 The parity probe takes the device arm on both files at the same `rel rms
 4.65e-3`, which is its own small proof that the DiT came through untouched.
 
-### What it costs in quality
+#### What it costs in quality
 
-Judge it on the clip, not on a frame: a still catches the pancake at rest and
-reads as a loss that is not there.
-
-| four bits, 32B encoder | four bits, 4B + ClipProj | two bits, 32B encoder |
-|---|---|---|
-| ![32B](https://huggingface.co/infosave/MiniMax-H3-Turbo-cmf/resolve/main/samples/ab_q4tp.gif) | ![ClipProj](https://huggingface.co/infosave/MiniMax-H3-Turbo-cmf/resolve/main/samples/ab_clipproj.gif) | ![two bits](https://huggingface.co/infosave/MiniMax-H3-Turbo-cmf/resolve/main/samples/ab_q2tp.gif) |
-| 23.94 GB | **13.16 GB** | 18.74 GB |
+Judge it on the clip at the top of this section, not on a frame: a still
+catches the pancake at rest and reads as a loss that is not there.
 
 Across the 39 frames the 4B does the whole job: corgi, chef hat, flat clean
 style, and the pancake **leaves the surface and comes back**, the dish empty
@@ -334,7 +355,7 @@ the two-bit build it is a trade rather than a loss.
 Sound is untouched either way: the audio branch never sees the prompt encoder.
 [The clip with its audio.](https://huggingface.co/infosave/MiniMax-H3-Turbo-cmf/resolve/main/samples/ab_clipproj.mp4)
 
-### Building one
+#### Building one
 
 ```bash
 cortiq animate-pack \
@@ -399,8 +420,9 @@ dequantizes to f32, so the two renders differ by a few per cent in latent rms
 and visibly in fine texture. Set `CMF_SDOT=0` on both sides to compare
 arithmetic instead of that approximation.
 
-**Why the device is opt-in.** Getting it right took three fixes, and one
-thing is still held back.
+**Why the device took a while to trust.** It is no longer opt-in — the parity
+probe decides per file — but getting there took three fixes, and one thing is
+still held back.
 
 The engine's blocked f32 GEMM cached its weight-side device buffer **by
 pointer address**. Every batched attention allocates one k/v scratch pair per