Intrepid/Prometeu/Runtime/pipeline/pr-master There was a failure building this commit
143 lines
8.0 KiB
Markdown
143 lines
8.0 KiB
Markdown
# Software numeric qualification
|
|
|
|
Date: 2026-10-09. Scope: local macOS/aarch64 qualification.
|
|
The normative contract is [Gameplay Math and Numeric Semantics](../specs/runtime/02d-gameplay-math-and-numeric-semantics.md).
|
|
The exact configuration, dependency checksums, source/catalog fingerprints,
|
|
oracle results and measured timings are in [NUMERIC_QUALIFICATION.json](NUMERIC_QUALIFICATION.json).
|
|
|
|
## Configuration and source audit
|
|
|
|
The runtime uses fpmath 0.1.1, feature soft-float, with rustc_apfloat
|
|
0.2.3+llvm-462a31f5a5ab resolved in Cargo.lock. Both dev and release probes
|
|
ran as aarch64-apple-darwin executables under rustc 1.98.1,
|
|
commit 48a229ceaefd4985c50990b14116b6d856af0985, LLVM 22.1.8.
|
|
No native numeric acceleration is enabled. Source fingerprints identify
|
|
the implementation independently of the pre-change repository commit.
|
|
|
|
The reviewed paths in the published fpmath source are:
|
|
|
|
| Path | Finding relevant to the runtime |
|
|
| --- | --- |
|
|
| src/soft_f64.rs | SoftF64 stores an APFloat Double. Bit import/export does not calculate with native f64. Basic operators delegate to APFloat; comparisons also use that representation. |
|
|
| rustc_apfloat src/lib.rs | The default ADD/SUB/MUL/DIV operator implementations select NearestTiesToEven explicitly. |
|
|
| src/generic/sqrt.rs | Normalizes subnormals, computes the integer root with an extra bit and constructs the rounded result bits. Zero signs are preserved. The documented upstream error bound is below half an ULP. |
|
|
| src/generic/sin_cos.rs; src/generic/reduce_pi_2.rs | Selects small, medium and large argument reduction. Medium reduction uses split constants and additional cancellation correction. |
|
|
| src/generic/reduce_pi_2_large.rs | Uses integer/fixed-point chunks and a stored 2/pi expansion derived from the musl/FreeBSD reduction algorithm, rather than a remainder against binary64 tau. |
|
|
| src/generic/atan.rs | Generic atan/atan2 calculations use the software scalar implementation. The runtime handles the zero vector and signed axes explicitly before delegation. |
|
|
|
|
The published [fpmath documentation](https://docs.rs/fpmath/0.1.1/fpmath/)
|
|
describes portable soft-float results and error bounds for these functions.
|
|
The [versioned source](https://docs.rs/crate/fpmath/0.1.1/source/)
|
|
is the audit reference. Upstream claims, source review and independent
|
|
testing support the selected reference; this record is not a formal proof
|
|
over every binary64 input.
|
|
|
|
The VM adapter supplies semantics that cannot be taken directly from every
|
|
upstream convenience function. In particular, upstream round uses ties away
|
|
from zero; runtime mathf.round implements ties to even from bits.
|
|
Integer conversions also use bits, avoiding saturation and the rounded
|
|
Float representation of Int64 MAX as a range bound. Every public numeric
|
|
path validates inputs and maps domains/range to the runtime fault contract.
|
|
Float arithmetic, mixed-carrier promotion and comparisons in guest opcodes
|
|
use this adapter. Host inspection utilities are outside guest arithmetic.
|
|
|
|
## Independent oracle and results
|
|
|
|
The tooling uses gmpy2 2.3.0 and MPFR 4.2.2. Binary64 inputs are imported
|
|
through exact rational representations, with explicit preservation of -0.
|
|
Directed MPFR bounds start at 160 bits and adapt up to 10,240 bits when
|
|
needed. Basic operations, sqrt and integer-to-Float conversions must match
|
|
the independently rounded binary64 result, including exponent limits and
|
|
gradual underflow. Rounding and Float-to-integer conversions are also checked
|
|
against exact integer/rational rules. Vector results match the prescribed
|
|
sequence with a binary64 MPFR context at each step.
|
|
|
|
For sin/cos/atan2 the gate certifies a strict upper error bound below 1 ULP
|
|
of the ideal result. Positive endpoint distances are rounded upward before
|
|
comparison; taking the absolute value of a negative subtraction rounded
|
|
upward would underestimate that bound.
|
|
|
|
Both profiles passed 380,946 cases with seed 560053 and count 10000.
|
|
The corpus combines critical constants, neighboring binades, subnormal
|
|
transitions, finite extremes and random finite bit patterns. Arithmetic
|
|
opcode rows execute validated bytecode. Scalar/vector rows call the same
|
|
runtime implementations directly; their reported cycles come from metadata.
|
|
Interpreter accounting is independently exercised by the contract tests
|
|
for every scalar/vector identity, refusals, zero budget and overshoot.
|
|
|
|
| Function | Largest certified error upper bound in the sampled corpus |
|
|
| --- | ---: |
|
|
| sin | 0.7327914722897216 ULP |
|
|
| cos | 0.698851370176746 ULP |
|
|
| atan2 | 0.5139939747008185 ULP |
|
|
|
|
Fundamentals, sqrt, conversions, rounding and vector sequences had no
|
|
disagreement with their corresponding exact oracle.
|
|
Debug and release corpus bytes were identical, including results/faults
|
|
and cycles. SHA-256:
|
|
|
|
51f9361e79b2e648d557d38dad775250ed3c5d57f8ff5f187dc3ee7aab7ddfdb
|
|
|
|
The checked-in portable fixture contains 4,747 independently verified rows
|
|
(count 100, same seed). It replays without installing MPFR.
|
|
Workspace validation passed 907 tests with 9 existing ignored tests,
|
|
cargo fmt and workspace Clippy. All 14 numeric contract tests passed in
|
|
release as well as debug.
|
|
|
|
The oracle process runs as x86_64 on the available Mac, while both runtime
|
|
executables are aarch64. This is independent oracle execution, not an
|
|
x86_64 runtime qualification.
|
|
|
|
## Indicative local cost
|
|
|
|
One release microbenchmark called each intrinsic implementation 20,000 times,
|
|
after 100 warmup calls, with the inputs in numeric_benchmark.rs.
|
|
These timings exclude interpreter dispatch, argument production and frame
|
|
scheduling; they are neither worst-case bounds nor virtual cycle calibration.
|
|
|
|
| Function | Observed ns/call | Fixed virtual call cycles |
|
|
| --- | ---: | ---: |
|
|
| sqrt | 113.21 | 16 |
|
|
| sin, large argument | 853.40 | 32 |
|
|
| cos, MAX_FINITE | 922.79 | 32 |
|
|
| atan2 | 2274.13 | 48 |
|
|
| dot | 51.81 | 10 |
|
|
| length | 248.53 | 40 |
|
|
|
|
## Reproduction and remaining host evidence
|
|
|
|
Install the independent oracle in an isolated environment:
|
|
|
|
python3 -m venv /tmp/prometeu-numeric-oracle
|
|
/tmp/prometeu-numeric-oracle/bin/python -m pip install -r scripts/numeric-oracle-requirements.txt
|
|
|
|
Build with the locked dependency resolution and run both profiles:
|
|
|
|
cargo build --locked -p prometeu-vm --examples
|
|
cargo build --locked -p prometeu-vm --examples --release
|
|
mkdir -p target/numeric
|
|
/tmp/prometeu-numeric-oracle/bin/python scripts/qualify-numeric.py --probe target/debug/examples/numeric_probe --output target/numeric/debug-corpus.tsv --count 10000 > target/numeric/debug-report.json
|
|
/tmp/prometeu-numeric-oracle/bin/python scripts/qualify-numeric.py --probe target/release/examples/numeric_probe --output target/numeric/release-corpus.tsv --count 10000 > target/numeric/release-report.json
|
|
cmp target/numeric/debug-corpus.tsv target/numeric/release-corpus.tsv
|
|
cargo test --locked -p prometeu-vm --test numeric_contract
|
|
cargo test --locked -p prometeu-vm --test numeric_contract --release
|
|
target/release/examples/numeric_benchmark
|
|
|
|
Regenerate/check catalog artifacts with export_numeric_catalog. The parity
|
|
test compares generated output to both checked-in CSV files. Record
|
|
rustc -Vv, target, features, lockfile, source/catalog fingerprints and oracle
|
|
versions on every new qualification run.
|
|
|
|
Runtime execution on macOS/x86_64 and Linux/x86_64 headless remains pending.
|
|
When those hosts are available, reproduce this same seed/count in debug and
|
|
release, pass the oracle and contract tests, and compare the complete corpus
|
|
to the SHA-256 above. Any difference in bits, faults or cycles requires
|
|
investigation; meeting the ULP bound alone does not qualify a different result.
|
|
Cross-compilation only provides build evidence. A future intentional backend
|
|
revision requires a new qualification baseline.
|
|
|
|
Frontend integration remains pending independently: consume runtime metadata,
|
|
project math/mathf namespaces, resolve exact overloads, retain ordered
|
|
arguments and preserve calls with literal inputs. The spec supplies examples;
|
|
this delivery contains no frontend implementation or frontend integration tests.
|