stillwater-sc / universal / 24947307128

84%

master: 84%

push

github

feat(math): add constexpr exp2 to sw::math::constexpr_math (#769)

* feat(math): add constexpr exp2 to sw::math::constexpr_math

Adds constexpr<float|double> exp2 to the constexpr_math facility (#763
Epic, #423 / PR #762 substrate). Tier-1 sub-issue: paired inverse of
log2, blocks lns/takum decode at compile time.

Algorithm:
  Decompose x = N + F with N = floor(x), F in [0, 1).
    2^N : direct IEEE-754 bit construction via detail::pow2 (set
          exponent field, mantissa zero) -- exact and O(1).
    2^F : range-reduce to F in [0, 1/2) by factoring out sqrt(2) when
          F >= 1/2, then 2^F = e^(F * ln(2)) with z = F * ln(2) in
          [0, ln(2)/2] ~ [0, 0.347]. Horner Taylor series of e^z with
          factorial-reciprocal coefficients (1, 1, 1/2!, ..., 1/k!) --
          first-principles derivable, no external tooling.
    Result: 2^N * (sqrt(2)-or-1) * Taylor(z).

Polynomial degree:
  - double: 14 terms -> ~5e-19 truncation error (sub-ulp)
  - float : 8 terms -> ~5e-9 truncation error (well below float eps)

Special-value handling per IEEE-754:
  exp2(NaN)  -> NaN
  exp2(+inf) -> +inf
  exp2(-inf) -> 0
  overflow (x >= 1024 / 128) -> +inf
  underflow (x < -1075 / -150) -> 0

Refactor: extracted shared detail (IEEE-754 layout guards, LOG2E,
SQRT2, plus new LN2 constant and pow2/pow2f/floor_to_int helpers) into
a new detail.hpp header. log2.hpp now includes detail.hpp instead of
duplicating the constants. This avoids drift as more functions
(pow, log, exp, sqrt) join the facility.

Verification:
  - 18 static_assert checks: exact powers, special values, NaN
    propagation, overflow/underflow, fractional argument (sqrt(2)),
    round-trip exp2(log2(x)) for pi/e/1024 (the lns acceptance form)
  - Runtime sweep over 17 hand-picked points + round-trip stress over
    21 points spanning 1e-100 to 1e100
  - Out-of-band accuracy stress (100K random samples in [-700, 700]):
    max relative error 3.14e-16 = 1.41 x double epsilon (~1.4 ulp)

cm_lo... (continued)

105 of 114 new or added lines in 3 files covered. (92.11%)

45213 of 53599 relevant lines covered (84.35%)

6328793.43 hits per line