Update README.md

README.md

@@ -389,13 +389,67 @@ frozen — so the block-DC residual collapses to the `fp16` storage floor
 <10 ms per tensor).  It spends **no** SSE budget (the pin can only lower
 unweighted block SSE) and runs identically on the CPU and CUDA paths.
 
+**Zero-DC Pin for the format quantizers (Q4_0 / Q3_K):** those formats
+carry a single scale per block and no additive degree of freedom, so the
+exact closed-form re-solve is degenerate there.  Instead the pin performs a
+deterministic **code-flip exchange**: each round picks, per block, the
+flip (direction + position) with the best `ΔSSE / |ΔDC|` ratio and applies
+it until the block has spent at most `pin_budget` of its starting SSE or
+the residual reaches the floor of half a flip quantum.  Measured on real
+tensors (blk.0, CUDA path):
+
+| Format | Config | RMSE | Block-DC RMS |
+| :--- | :--- | :---: | :---: |
+| `Q3_K` (`blk.0.ffn_down`) | base | $1.554\times10^{-3}$ | $1.96\times10^{-2}$ |
+| `Q3_K` + pin 5% | `pin_budget=0.05` | $1.560\times10^{-3}$ (+0.4%) | $3.55\times10^{-3}$ (**−82%**) |
+| `Q4_0` (`blk.0.attn_qkv`) | base | $1.223\times10^{-3}$ | $5.82\times10^{-3}$ |
+| `Q4_0` + pin 5% | `pin_budget=0.05` | $1.231\times10^{-3}$ (+0.7%) | $3.36\times10^{-3}$ (−42%) |
+| `Q4_0` + pin 10% | `pin_budget=0.10` | $1.239\times10^{-3}$ (+1.3%) | $2.18\times10^{-3}$ (−63%) |
+
+`pin_budget` (default 0.05, `0` disables the spend) bounds the per-block
+SSE the exchange may spend; the Q2_K closed-form pin never consults it.
+The pin is bit-deterministic, applies after thermal refinement, runs
+fully on-GPU on the CUDA paths (`pin_dc_codes_uniform_cuda` in
+`spectral.py`) and on NumPy on the CPU paths — Q3_K's residual lands near
+the DC floor because its signed `sc` unit grid has DC slack on both sides,
+while Q4_0's unsigned `[0, 15]` nibble grid is bounded by the code-16
+edge and settles higher.
+
+The same single invocation covers Q2_K and the format quantizers —
+`--device cuda` (or `--device auto`, which picks CUDA when available)
+routes the format pipelines to the CUDA path and the pin runs on-GPU
+automatically, no extra flags needed:
+
+```bash
+# Pure Q3_K, full CUDA pipeline (thermal + on-GPU zero-DC pin):
+python3 -m hpc_quantize_v2 \
+  --gguf model.gguf \
+  --format q3_k \
+  --device cuda \
+  --imatrix-gguf imatrix.gguf \
+  --thermal 4 \
+  --pin-dc \
+  --output model-Q3K.gguf \
+  --verbose
+
+# Pure Q4_0 (pin included via --pin-dc):
+python3 -m hpc_quantize_v2 --gguf model.gguf --format q4_0 --device cuda --pin-dc --output model-Q4_0.gguf
+```
+
+In the GUI, tick **Pin DC residual to 0** and pick the CUDA device from the
+device selector — the checkbox enables the pin for whichever format each
+tensor is quantized to (closed-form re-solve for Q2_K superblocks,
+code-flip exchange for Q4_0/Q3_K blocks).  `pin_budget` itself is an
+`HPCConfig` field (0.05 default) for API users, GUI/CLI defaults keep the
+sensible order of magnitude.
+
 **DC/vesica drain knob map (and where they act):**
 
 | Knob | Config field | Stage | Cost model |
 | :--- | :--- | :--- | :--- |
 | Spectral shaping | `dc_lambda`, `vw_lambda` (λ_dc=λ_vw=1.0 default) | Phases 1–4 (in-objective) | arises inside the weighted objective itself |
 | Thermal λ-tilt drain | `therm_passes`, `therm_lambda_tilt` | Phase 4.5 (opt-in) | spends SSE under `sse_budget`, seeded & deterministic |
-| Zero-DC Pin | `pin_dc` | Phase 4.7 (opt-in) | **exact & free** — SSE non-increasing, DC → fp16 floor |
+| Zero-DC Pin | `pin_dc`, `pin_budget` | Phase 4.7 (opt-in) | Q2_K: **exact & free** (closed-form, SSE non-increasing) · Q4_0/Q3_K: code-flip exchange bounded by `pin_budget` of block SSE |
 | Row-aware carry nudge | `apply_dc_carry`, `dc_decay`, `sse_budget`, `carry_cumulative` | Phase 4.8 (on by default) | exactly bounded per-block budget, residual funneled downstream |
 
 For maximal coherent-residual drainage enable thermal (with tilt) + the
@@ -445,5 +499,3 @@ stats = write_quantized_gguf(
 )
 print(stats)
 ```
-
----