Skip to content

elreal Phase 7: transcendental functions and numbers #931

@Ravenwater

Description

@Ravenwater

Parent epic: #923
Depends on: Phase 6 (multiplication / division)

Goal

Provide the math suite: `exp`, `log`, `sin`, `cos`, `tan`, `sqrt`, `atan`, `asin`, `acos`, `sinh`, `cosh`, `tanh`, `pow`, `hypot`. Plus the named constants: `pi`, `e`, `ln(2)`, `log2(10)`, `euler_gamma`, `phi`, `sqrt(2)`, `sqrt(3)`, `sqrt(5)`.

Algorithm choices (per dissertation 4.2.7)

  • Square root: Newton-Raphson on `ZBCL`
  • exp: Taylor series, with argument reduction `exp(x) = exp(x/2^k)^(2^k)`
  • log: Taylor series of `ln(1+u)` with argument reduction `log(2^k * m) = k*ln(2) + log(m)`
  • sin / cos: Taylor series with Payne-Hanek-style range reduction modulo 2*pi (using `pi` itself as a ZBCL)
  • atan: Machin formula or its extensions for fast pi convergence
  • pi: BBP digit extraction, Machin, or AGM (the dissertation discusses options)
  • e: Taylor series of `exp(1)` -- direct
  • ln(2): Mercator series or related

Where exp_offset earns its keep

Transcendentals at extreme arguments (`exp(1000)`, `log(1e-300)`) have combined exponents far beyond any single host FP type's range. The `exp_offset` field on `block` lets a single block carry that exponent. Phase 7 will be the first phase where this matters in practice.

Acceptance criteria

  • All listed functions implemented, each its own `.hpp` under `include/sw/universal/number/elreal/math/`
  • All listed constants are lazy `ZBCL` factories (not eagerly materialised double constants)
  • Tests check first 100 decimal digits of each constant against the 320-digit reference strings in `include/sw/math/constants/reference_constants.hpp` (PR feat(constants): high-precision (~320-digit) reference string constants #915)
  • Function tests: roundtrip identities -- `log(exp(x)) == x`, `exp(log(x)) == x` for x > 0, `sin(asin(x)) == x` on `[-1,1]`, etc., stream-wise to depth N
  • Pythagorean identity: `sin(x)^2 + cos(x)^2 == 1` stream-wise
  • Tests parameterised over FpType in `{double, float, bfloat16}`
  • Tests live in `elastic/elreal/math/`

Out of scope

  • Gamma function, error function, special functions -- can be a follow-up
  • BBP-style direct digit extraction for hex pi -- explicit non-goal (mentioned in epic non-goals)

Reference

McCleeary 2019 dissertation, Section 4.2.7 (transcendentals).

Metadata

Metadata

Assignees

No fields configured for Feature.

Projects

Status

No status

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions