[M0-CORE-03] SimMath interface + fp32_pinned backend - #3
Merged
Merged
Conversation
Implements roadmap step M0-CORE-03 (ADR 0002, PRD §10.3, S-7/G-R8): the single deterministic-math interface with the fp32_pinned backend. - include/laige/sim_math.h: laige::sim::SimMath<Backend> op surface (add/sub/mul/div, ordered IEEE comparisons + NaN/Inf predicates, clamp, lerp, normalize, length over scalar/Vec2/Vec3) and the Fp32Pinned backend (IEEE binary32, add/sub/mul/div/sqrt primitives). The pinned flag set and the full NaN/Inf policy are documented in the header (defined, not "whatever the CPU does"). - sim_math.cpp: pinned explicit instantiation of the fp32_pinned backend (linkable symbol in both static and shared variants). - CMake: laige_apply_simmath_policy() pins the ADR 0002 flag set (-ffp-contract=off -fno-associative-math GCC/Clang/AppleClang, /fp:precise MSVC) on every sim target; applied to laige-core and the test targets. - tests/laige-core/math_float_tests.cpp: ctest -R math_float (22 tests, 4 suites) — bit-exact known values, the full NaN/Inf policy, property tests (clamp idempotence, normalize round-trip within a documented 4-ulp tolerance, sign invariance), and runtime FMA canaries (DotProductCanary, LerpIsNotFmaFused) that fail if the pinned flags are ever missing — sensitivity verified with a negative build (-ffp-contract=fast -mfma). - Fix a latent CTest defect found while wiring math_float: quoted --gtest_filter arguments are passed through with literal quotes, and gtest's colon-split then silently under-ran the result_status and logging Verify suites (only one pattern of each matched). All three entries now pass one unquoted filter argument; result_status runs 17 tests/3 suites and logging 27/8 again. - Docs: docs/api/sim_math.md (API contract, backend table, pinned set, NaN/Inf policy, performance, misuse warnings), laige-core README entry, building.md pinned-policy section + math_float CTest entry. Verified: ctest -R math_float green; full ctest green in the default, shared (LAIGE_BUILD_SHARED), ASan, and TSan trees, plus the Clang 22 tree; pinned flags confirmed on the compile lines of laige-core and laige-core_tests; include-lint green.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Step
Roadmap M0-CORE-03 (M0-foundations.md): SimMath interface +
fp32_pinnedbackend. Refs: ADR 0002, PRD §10.3, S-7/G-R8.What
src/laige-core/include/laige/sim_math.h—laige::sim::SimMath<Backend>op surface (add/sub/mul/div; ordered IEEE comparisons +isNaN/isInf/isFinite/isOrdered;clamp,lerp,normalize,lengthover scalar/Vec2/Vec3) and theFp32Pinnedbackend (IEEE binary32 primitives). The pinned flag set and the full NaN/Inf policy are documented in the header — defined, not "whatever the CPU does".src/laige-core/sim_math.cpp— pinned explicit instantiation (linkable symbol in both static and shared variants).CMakeLists.txt—laige_apply_simmath_policy(): the ADR 0002 pinned set (-ffp-contract=off -fno-associative-mathGCC/Clang/AppleClang;/fp:preciseMSVC) on every sim target; applied tolaige-coreand the test targets.tests/laige-core/math_float_tests.cpp—ctest -R math_float: 22 tests / 4 suites (bit-exact known values incl. ±0; full NaN/Inf policy; property tests incl. documented 4-ulp normalize round-trip tolerance; runtime FMA canaries that fail if the pinned flags are ever missing).docs/api/sim_math.md(API contract + performance + misuse warnings),src/laige-core/README.md,docs/getting-started/building.md.Bug found and fixed along the way
The existing
result_statusandloggingCTest entries passed their--gtest_filteras quoted arguments. CTest passes quoted args through with the literal quote characters, and gtest's colon-split of the filter then silently matched only one pattern of each — soctest -R result_statuswas running 4 tests / 1 suite instead of 17 / 3, andctest -R logging8 of 8 suites partially. All three entries now pass one unquoted filter argument (comment intests/laige-core/CMakeLists.txtexplains the hazard).Verification
ctest -R math_floatgreen (22 tests / 4 suites).ctestgreen in: default tree,build-shared(-DLAIGE_BUILD_SHARED=ON),build-asan,build-tsan, plus the Clang 22 tree (GCC 16.2.1 is the default).laige-coreandlaige-core_tests(-ffp-contract=off -fno-associative-math).-ffp-contract=fast -mfma:DotProductCanaryDetectsFmaContractionfails as designed.No dependencies added; no public API outside
laige-corechanged; roadmap step M0-CORE-03 marked done (its Verify commands pass). Next step per roadmap: M0-CORE-04 (fpx16_16default backend).