| name | verify-accuracy |
| description | Primus-Turbo accuracy verification — compare an operator against a higher-precision reference for forward and backward, with the right gate (allclose for bf16/fp16/fp32, SNR for fp8/fp4) and FP8 encoding awareness. Use when validating numerical correctness of a Primus-Turbo operator. |
Verifying Accuracy
Prove an operator is numerically correct against a higher-precision PyTorch reference, for both forward and backward. Read the hub ../SKILL.md first.
The pattern
Copy the structure of an existing test rather than writing one from scratch:
| Your case | Copy from |
|---|
| Dense fwd+bwd, parametrized shapes/dtypes/layouts | tests/pytorch/ops/test_gemm.py |
| Low-precision (SNR gate, backend parametrize) | tests/pytorch/ops/test_gemm_fp8.py |
| Determinism (bitwise) | test_gemm.py::test_gemm_deterministic |
| Attention / MoE / grouped | tests/pytorch/ops/test_attention.py, test_moe_permute.py, test_grouped_gemm.py |
Rules those tests follow: seed with torch.manual_seed(42); clone a _ref input with its own requires_grad_() so grads stay independent; normalize sensitive inputs (a = a / a.abs().max()); reset a.grad = None between reuses; pytest.skip unsupported combos instead of failing.
Reference implementations (tests/pytorch/ref/)
Put ground-truth math here, computed in float()/fp32, then compare the lower-precision Turbo output against it. Existing references to reuse or mirror: gemm_ref.py (incl. grouped_gemm_ref), attention_ref.py (uses torch.nn.functional.scaled_dot_product_attention under sdpa_kernel), moe_ref.py, permuatation_ref.py, quantization_ref.py, deep_ep_ref.py.
Tolerances and metrics
get_tolerances(dtype) in tests/pytorch/test_utils.py returns allclose tolerances only: fp32 1e-4, fp16/bf16 1e-2, and intentionally-loose fp8 1e-1 / fp4 0.5. Use it with torch.testing.assert_close for fp32/fp16/bf16. The fp8/fp4 tolerances are too loose to be a real gate — low precision gates on SNR instead (element-wise tolerance is meaningless after quantization).
| Type | Real gate | Threshold | Defined in |
|---|
| FP32 | assert_close(**get_tolerances) | rtol=atol=1e-4 | test_utils.py |
| FP16 / BF16 | assert_close(**get_tolerances) | rtol=atol=1e-2 | test_utils.py |
| FP8 E4M3 | SNR (dB) | ≥ 25 | test/bench constant (e.g. check_gemm_correctness_by_snr, SNR_THRESHOLD) |
| FP8 E5M2 | SNR (dB) | ≥ 20 | same |
| FP4 (E2M1) | SNR (dB) | ≥ 10 | same |
| Determinism | bitwise over N runs | rtol=atol=0 | test body |
The SNR thresholds (25 / 20 / 10) are not returned by get_tolerances; they are hardcoded in the test/bench files. compute_snr(ref, actual) is the primary low-precision gate (arg order is reference-first); relative_error, mean_squared_error, max_abs_error, cosine_similarity, symmetric_similarity_diff are for diagnosis.
FP8 / FP4: state the encoding
Encoding is arch-dependent and chosen in core/low_precision.py: gfx942 → FNUZ, gfx950 → OCP (MXFP8/MXFP4 require gfx950). Build the config with Float8QuantConfig / Float4QuantConfig; gate with check_fp8_support() / check_mxfp8_support() / check_mxfp4_support() before running. Separate conversion errors from scale errors from kernel-math errors — never label a failure only as "fp8".
Running tests
pytest tests/pytorch/ops/test_gemm_fp8.py -v -k "blockwise and CK"
pytest tests/pytorch/ -n 8
pytest tests/pytorch/ -n 8 --deterministic-only
pytest tests/pytorch/ --dist-only
tests/conftest.py pins each xdist worker to one GPU and defines the deterministic / multigpu markers (those suites are skipped in the normal run). Backends are parametrized inside test files, so -k "TRITON" / -k "CK" selects one; force a backend in-test with GlobalBackendManager.set_gemm_backend(...) and reset() in teardown.
Cross-platform numerical accuracy
For "does AMD match CPU / NVIDIA on this math?" (not pass/fail): benchmark/accuracy/eval_gemm_accuracy.py, eval_sf_accuracy.py (GPU-vs-CPU, write .xlsx). GPU-vs-GPU is a 3-step dump/transfer/compare flow — see benchmark/accuracy/README.md.
Checklist
- [ ] Reference impl in tests/pytorch/ref/ (fp32 / PyTorch-native)
- [ ] Forward AND backward compared
- [ ] Parametrized over representative shapes, dtypes, layouts, backends
- [ ] Correct gate (allclose for bf16/fp16/fp32, SNR for fp8/fp4)
- [ ] FP8/FP4 encoding (FNUZ vs OCP) and arch support asserted
- [ ] Determinism test if bit-reproducibility is required
- [ ] Focused test green, then `pytest tests/pytorch/ -n 8` green
