stillwater-sc / universal / 24944226215

84%

master: 84%

Build Type

push

github

Committed by web-flow

Commit Message

feat(math): add sw::math::constexpr_math facility with constexpr log2 (#762)

* feat(math): add sw::math::constexpr_math facility with constexpr log2

Introduces a new self-contained library of constexpr math functions for
IEEE-754 float and double, parallel to the existing sw::math::function
facility but specifically for compile-time evaluation. Per the issue
brief: "constexpr is a slightly different use case than templated math
functions ... it would be nice to have this as a separate and
specialized include set ... independently useful outside of Universal's
number systems".

Layout:
  include/sw/math/constexpr_math.hpp       -- aggregator
  include/sw/math/constexpr_math/log2.hpp  -- base-2 logarithm
  internal/constexpr_math/api/log2.cpp     -- regression test (cm_log2)

Namespace: sw::math::constexpr_math

Algorithm (log2):
  1. Decompose x = 2^E * M with M in [1, 2) via std::bit_cast<uint64_t>.
  2. Range-reduce to M in [1/sqrt(2), sqrt(2)] by halving M and
     incrementing E when M > sqrt(2).
  3. With u = (M-1)/(M+1), |u| <= 0.1716, evaluate
       ln(M) = 2 * artanh(u) = 2 * (u + u^3/3 + u^5/5 + ...)
     via Horner. Coefficients are odd reciprocals (1/3, 1/5, ...) --
     derivable from first principles, no external tooling
     (no Sollya, no Remez).
  4. log2(x) = E + ln(M) / ln(2)

Polynomial degree:
  - double: degree 21 (terms up to u^21/21) -> ~5e-17 truncation error
  - float : degree 11 (terms up to u^11/11) -> ~1e-9 truncation error

Special-value handling follows IEEE-754:
  log2(NaN)  -> NaN
  log2(x<0)  -> NaN
  log2(0)    -> -infinity
  log2(+inf) -> +infinity

Subnormals are normalized via a software shift loop (constexpr-safe).

Verification:
  - 22 static_assert checks for exact powers of 2, special values,
    log2(3.14) and log2(0.75) acceptance forms
  - Runtime sweep over 23 hand-picked points + subnormal sample
  - Out-of-band stress sweep (100K random samples in [1e-100, 1e100]):
    max relative error 1.74e-16 = 0.78... (continued)

Coverage Stats

90 of 104 new or added lines in 2 files covered. (86.54%)

4 existing lines in 3 files now uncovered.

45103 of 53485 relevant lines covered (84.33%)

6403422.69 hits per line