Skip to content

feat(magemath): configure min/max, recip and rsqrt - #153

Open
lilith wants to merge 80 commits into
perf/scalar-sqrtfrom
feat/primitive-contracts
Open

lilith wants to merge 80 commits into
perf/scalar-sqrtfrom
feat/primitive-contracts

Conversation

@lilith

@lilith lilith commented Nov 11, 2026 •

Copy link
Copy Markdown
Member

Adds const-configured f32/f64 min/max and f32 reciprocal/rsqrt families in Magemath. Stacked on PR152. Existing Magetypes primitives remain unchanged. Checked restricted profiles reject the whole vector and report invalid lanes; AssumeValid removes validation. Builders declare domain, NaN/zero behavior, precision, portability and execution, ending in a const integer .bits(). Matching-width lane entries retain native vector tail results.

Portable LOWP/MIDP use fixed seeds and canonically fused Newton graphs. Complete operations select native FMA, the shared cached relaxed-WASM fusion probe, or exact software FMA. Relaxed selection requires a compiled relaxed module and honors token suppression. Automatic entries dispatch at the operation boundary; std FMA3 support does not fabricate a V3 proof. HIGHP reciprocal is rounded division; HIGHP rsqrt is explicitly sqrt-then-division. Equivalent policy combinations canonicalize away.

The public API option overview, reciprocal preset/combination tables, and min/max policy tables now live in rustdoc, with a checked matching-tail example. They explain valid combinations, canonicalized equivalent flags and the distinction between portable bits and hardware execution. Rustdoc builds with warnings denied; examples pass with and without std.

The contract and ISA reference records bounds, selection, characteristics and measured costs. No blanket faster-than-native legacy replacement is qualified.

The complete permutation reference now compiles the actual builders/validators with and without std: min/max 72 raw combinations → 24 canonical flags, reciprocal/rsqrt 48 raw → 22 supported canonical flags (16 unsupported Full approximations). All five families have complete supported/redirected option tables in Rustdoc. Normal min/max excludes zero; a documented Finite builder supports ordinary zero clamps.

The canonical-cell matrix covers 66 groups / 1,566 arms per context: all supported new primitive configurations, types and logical widths, stream64/4096, chain64 and min/max zero-clamp64. Eight of nine contexts are measured and embedded in Rustdoc: Zen 5 Scalar/V3/V4/V4x, Intel V3, strict/fusing WASM and exploratory M6 NEON. Relaxed nonfusing WASM was stopped at the owner’s wrap-up request: one complete process packet and interrupted-process logs are preserved, with no complete five-process timing result. Pow/exp/log timing expansion is deferred per owner direction.

  • No complete strict suite passes admission. Fully clean groups: Intel V3 32/66, strict WASM 18/66, fusing WASM 3/66, each AMD context 0/66. All 3,300 M6 group-round observations are flagged. All observations remain in the analysis.
  • A clean Intel x8 reciprocal chain takes 290.8175 ns for portable MIDP AssumeValid Caller R33 versus existing 270.7577 ns: ratio 1.074088, process-family95 1.067217–1.081004. Backend MIDP R3b takes 188.5439 ns. The portable cell fails the unchanged 2% bound.
  • A clean strict-WASM x4 stream4096 takes 26,635.7708 ns for portable MIDP R33 versus existing division 1,115.7777 ns: process-family95 ratio 23.514024–24.235254. HIGHP already provides portable division; silently changing MIDP only on software would violate its bit contract.
  • Flagged Scalar x8 stream64: portable MIDP AssumeValid Automatic R13 199.3708 ns, Caller R33 109.8284 ns, HIGHP R00 7.1326 ns. The current typed scalar fusion provider is not a speed win in this data.
  • Flagged fusing-WASM x8 reciprocal chain: backend MIDP R3b 210.9469 ns and backend LOWP R3d 556.8797 ns, despite both using division. Frozen WAT retains feature/helper calls. Numerical graph aliases do not establish equal compiled costs; no causal machine-code speed attribution is claimed.

Nested tables distinguish equal-flag redirects, source graph aliases, numerical bounds, observed fixed-input errors and cell admission. Timings use std+w512+avx512; no_std timing, frontend dispatch, first use, error latency, tail speed, literal-zero specialization and NaN/Inf-heavy streams remain unmeasured. Zero-clamp64 reads an opaque zero-filled operand buffer. Strict Rustdoc and std/no_std doctests pass. The strict WASM module runs with relaxed SIMD disabled, and the relaxed module is rejected specifically for that feature (validation CLI50.0.1, distinct from timed host49.0.5).

The separate bounded-widening / canonical-rounding study adds benchmark-only designs; it does not change public arithmetic:

  • Specialized f64 evaluation preserves the existing portable LOWP/MIDP fused bits. The normalized C audit establishes the bounded-product exactness argument; an independent Fraction rounder cross-checks all four reference columns on 1,029 inputs.
  • Direct mathematical RN14/RN8 results agree across tested ISAs using native working-recip or division proposals with exact correction. Naïve division-then-quantization misses 3,980 RN14 and 54 RN8 normalized inputs. RN14's measured maximum relative error is 6.1027705669403076e-5, versus 1.1415493993638393e-5 for current fused MIDP; both meet MIDP1e-4. RN8 reaches 0.003891050349920988, inside LOWP6e-3. This is an explicit accuracy tradeoff.
  • Moving correction into a cold integer helper reduces speculative Scalar repair work, but worsens several native and boundary-heavy workloads. It remains a separate ablation, not an accepted default.

Dense x4/x8/x16 checks cover every signed normalized mantissa, directed accepted exponents, and MIDP/RN14 matching-width tail spots. Scalar, V3/V4/V4x, physical Intel V3, M6 NEON std/no_std, strict/relaxed/forced-non-FMA WASM std/no_std and i686 Scalar pass their independent targets. Exact scaling arguments support exponent reduction; this is not a literal sweep of every exponent/mantissa pair.

Timing uses zenbench pinned to 73302a1c115836b2646f6a9adc32058c20d1a66f, including observer-affinity and macOS CPU-counter fixes. Both fixed matrices have 13 groups per context: x4/x8/x16 short/long streams and chains, plus x8 bit-distributed and rounding-boundary stress. Strict contexts use five independent processes and 50 paired rounds each. M6 is one unconfined exploratory process. No flagged rounds or outliers are removed. Hosted WASM uses Wasmtime49.0.5 with verified fusion probes 0/1/0; the forced-nonfusing baseline target is not an FMA-only codegen ablation.

All values below are ns per 64-element x8 ordinary stream. These suites failed admission, so the numbers are descriptive, not confirmed promotion claims:

Context Current portable serial MIDP Bounded f64, same bits HIGHP division
Zen 5 Scalar Caller 109.341 27.608 7.097
WASM strict 231.842 70.194 7.309
WASM relaxed nonfusing 268.096 87.311 7.299
Zen 5 V3 2.823 19.876 3.495

Widening reduces software-path costs but must not replace native FMA. In the separate Scalar repair comparison, RN14 division inline → cold is 107.428 → 13.284 ns; plain HIGHP division is 7.067 ns. Canonical rounding is portable but adds cost here.

The first complete matrix and cold-repair matrix retain all 208 measured groups. Every strict suite fails admission; 10/91 first-study groups and 1/91 corrective groups are individually all-clean. M6 has 0/50 clean rounds in every group. The unchanged promotion rule requires clean mandatory cells and upper95 ratio ≤1.02; no new design passes. The report includes all-retained paired bootstrap diagnostics, independent-process 91-comparison family intervals, raw zenbench bars, codegen, resource peaks and verified NAS manifests for all 204 payload files.

Validation: strict benchmark-package Clippy for std/defaults, no-default w512, optional WASM host and i686; MSRV1.89 default targets; native/hosted-WASM correctness and exact oracle replays; fmt and source-integrity checks. Production arithmetic, existing tests, generators, workspace manifests and workflows are unchanged from complete green CI67dead91. A duplicate worker full-suite run passed its first 14 stages and was stopped in unchanged powf Miri; its partial log is retained and no fresh complete local-suite pass is claimed. The complete research head6ecdfde4 passed all 55 CI jobs. Documentation head edc35cb also passed all 55 CI jobs; the next documentation update runs CI separately.

Earlier patched-harness qualification, fusion evidence, and linear-sRGB inventory remain revision-scoped. Parallel correction and canonical RCP14 emulation also remain benchmark-only. No linear-sRGB source changes; its existing vector/tail discrepancy is tracked separately.

@lilith lilith self-assigned this Nov 11, 2026
@codecov-commenter

codecov-commenter commented Nov 11, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 81.02%. Comparing base (bd83f03) to head (c105148).
⚠️ Report is 17 commits behind head on perf/scalar-sqrt.

Additional details and impacted files
@@                 Coverage Diff                  @@
##           perf/scalar-sqrt     #153      +/-   ##
====================================================
- Coverage             84.22%   81.02%   -3.21%     
====================================================
  Files                     6        6              
  Lines                  1249     1249              
====================================================
- Hits                   1052     1012      -40     
- Misses                  197      237      +40     
Flag Coverage Δ
aarch64 80.64% <ø> (+0.96%) ⬆️
x86_64 80.86% <ø> (-3.58%) ⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

…rToken Automatic, and add mca/dedup tooling

- magemath/primitive_neon & primitive_wasm: replace per-lane #[arcane]
  helper calls, core::array::from_fn closures, and outlined powf_f32_fuses()
  with inline #[rite] / single-boundary #[arcane] primitives (WASM policy
  guest hot-loop outlined calls: 1,030 -> 0 across all 219 select_* arms).
- magemath/minmax & recip: upgrade ScalarToken ExecutionContext::Automatic to
  dispatch once per whole SIMD operation via incant! and remove the scalar
  STD_FMA fmaf@PLT trap.
- magetypes backend_gen & backend_gen_w512: replace core::array::from_fn
  polyfill closures with direct array construction (eliminating 166 WASM
  try_from_fn calls and 30 instructions / 4 v128 loads + 4 v128 stores per
  WASM W512 plain wrapper, while shrinking generated arm_neon.rs and
  wasm128.rs by >1,000 lines).
- xtask/mca.py & just mca: static codegen equivalence-class deduplicator
  (5,256 policy arms -> 1,980 unique machine-code bodies), zero-hot-call
  auditor, and llvm-mca throughput/latency analyzer across x86-64 and ARM64.
- benchmarks/primitive_variants_2026-11-10: bump zenbench to 952dd1f0
  (macOS IOHID scan fix + QoS), fix hybrid CPU --cpu-set P-core ordering,
  and add --filter / --dedup / --iterate fast iteration flags.
…_std and run magemath primitive_contracts under SDE
@lilith
lilith added this pull request to stack #166 November 12, 2026 22:31

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants