[iamwavecut]

Follow-up to #22. An option becomes the default when it beats the paper recipe on quality, efficiency or speed without losing on the others. The paper method stays available as the baseline: recipe(name, paper=True) / PAPER_FIELDS.

Default changes

Field	Old default (paper)	New default	Evidence
rotation_rounds	1	"auto": adds an independent RPBH round where the block h < 512	Z-Image-Turbo W4A4, LPIPS against BF16: 0.438 → 0.348 (−0.090, 95% paired interval −0.124 to −0.060), better on 27 of 30 pairs
activation_quantizer	"lloyd_max"	"auto": absmax INT8 at A8, Lloyd-Max below	Z-Image W4A8: absmax 0.331 against 8-bit Lloyd-Max 0.330 (paired −0.007 to +0.007); 3.4–6.6× less GEMM time on an RTX 4090 at 4096 tokens
codebook_version	2	3 (Newton solver)	8-bit tables take about 0.1 s per width up to d = 30720; v2 failed to converge for d ≥ 7680

Artifacts without the new fields still load as one round with Lloyd-Max codes (from_dict setdefault).

Unchanged on purpose:

• output_gain_correction stays False. It lowers layer output error but raised image LPIPS at W2A4 (+0.016, +0.004 to +0.029, worse on 24 of 30 pairs) and lowered it at no tested width.
• adaln_scale="mse" stays off (see AdaLN detection by parent class; opt-in rotation, absmax A8, gain and outlier options (0.16.0) #22).
• outlier_channels is still not supported on the fused or streaming paths. Its image-level effect stayed within noise, so a side GEMM in the fused kernels is not worth adding.

Runtime work

• Pre-rotation runs as one Triton kernel on CUDA: +40–50 µs per call at 256 tokens, +70–75 µs at 4096 (the PyTorch path cost 0.5 ms and 3.4 ms). On MPS it is one Metal kernel. It also works on the fused block runtime and on Krea 2.
• ExecuTorch Vulkan W4A8 absmax path:
  • shaders rpbh_a8, absmax_a8, w4a8;
  • ExecuTorchVulkanW4A8Linear and register_executorch_vulkan_w4a8();
  • the pre-rotation is exported as a dense block-Hadamard matmul (blocks ≤ 1024).
  • Verified only on Mesa lavapipe: 12/12 cases pass, and the Python export matches within 1e-5. No RADV or .pte run yet.

Benchmark subsets (2026-10-29)

These are not full-benchmark reproductions.

• FLUX.1-dev, GenEval: 96 prompts × 2 seeds, official evaluator. Default W4A4 equals paper W4A4 here, because every block is ≥ 1024.

  Variant	GenEval	s/image	Peak memory
  BF16	0.615	21.5	25.1 GiB
  W4A4	0.641 (+0.026, −0.020 to +0.074)	14.1	8.7 GiB

• CogVideoX-2B, VBench W4A6: 12 prompts, 8 custom-input dimensions. Default (2 rounds at d = 1920) and paper settings differ by less than the pair spread on every dimension and on frame LPIPS. The default took 7% longer. The README now advises rotation_rounds=1 for such models when speed matters.

Checks

• ruff
• pytest (local)
• scripts/run_paper_methodology_checks.sh rc=0
• HF compat rc=0
• MPS gate
• CUDA tests on an RTX 4090: 77/77
• Vulkan W4A8 on lavapipe: 12/12

Version stays 0.16.0, which is not released yet. Not published to PyPI.