g_math 0.4.25

Multi-domain fixed-point arithmetic with geometric extension: Lie groups, manifolds, ODE solvers, tensors, fiber bundles — pure Rust, zero-float, deterministic
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80

# CONTRACT.scn — g_math agent primer

Condensed prime for an agent building against `g_math`. Authoritative prose:
[CONTRACT.md](CONTRACT.md). Per-symbol index: [PUBLIC_API.md](PUBLIC_API.md).
Code wins over docs.

```yaml
@CRATE: g_math (Rust, edition-2021, license MIT-OR-Apache-2.0)
  role: multi-domain fixed-point arithmetic, zero-float, deterministic
  default-runtime-deps: NONE (pure compute lib; no I/O, no network)

@SURFACE (supported; everything else internal, may-change):
  canonical:   g_math::canonical{gmath, gmath_parse, evaluate, evaluate_sincos,
               evaluate_sinhcosh, evaluate_matrix, set_gmath_mode, reset_gmath_mode,
               LazyExpr, LazyMatrixExpr, DomainMatrix}
  imperative:  g_math::fixed_point{FixedPoint, FixedVector, FixedMatrix}
               + DecimalFixed<DECIMALS>
  fused:       g_math::fixed_point::imperative::fused{sqrt_sum_sq, euclidean_distance,
               softmax, softmax_mix, rms_norm_factor, silu}
  geometric:   imperative::{decompose, derived, matrix_functions, manifold, lie_group,
               curvature, projective, fiber_bundle, ode, tensor, tensor_decompose,
               serialization}
  tq19:        g_math::tq19 (feature=inference){TQ19Matrix, PlanarTQ19, HybridTQ19,
               tq19_dot, ...}
  internal:    universal/fasc, domain impls, I256/I512/I1024/I2048, shadow/router

@DETERMINISM (core guarantee):
  fixed-profile + identical-input → bit-identical-output ∀ platform/arch
  mechanism: FLOAT_BAN — no f32/f64 in arithmetic|validation|comparison
  exception: from_f64/to_f64 = caller-convenience ONLY, never internal
  use-cases: consensus, financial-audit, reproducible-science

@ROUNDING (deterministic, integer-only):
  binary:  mul=half-even | div=half-away | downscale=nearest-ties-+∞
  decimal: mul=half-away | div=half-away | downscale=half-away
  ternary: mul=trunc-0  | div=trunc-0  | transcendentals→route-via-binary
  KEY: per-op binary tie-rules observable ONLY on exact half-ULP ties in direct
       storage-tier arith. Compound paths (transcendentals, dots, decomp, matrix
       chains, fused) compute at tier-N+1, round ONCE at downscale → tie-rules
       never fire. Divergence = documented artifact, not intent.

@TIER-N+1: all transcendentals + accumulations compute one width above storage,
  single downscale at end. Chains (canonical layer) keep intermediates wide until
  materialization → chain rounds once, not per-step.

@PROFILES (compile-time, GMATH_PROFILE or cargo feature):
  realtime Q16.16/i32(compute i64, ~4dp; GMATH_FRAC_BITS 2..30 custom split)
  compact  Q32.32/i64(i128, ~9dp)
  embedded Q64.64/i128(I256, ~19dp) [DEFAULT]
  balanced Q128.128/I256(I512, ~38dp)
  scientific Q256.256/I512(I1024, ~77dp)
  SWITCH: rm -rf target/*/incremental BETWEEN profiles (stale cfg → crash)

@CROSS-PROFILE:
  guaranteed: determinism WITHIN a profile
  NOT-yet-contracted: widening-exact / single-rounding-narrowing / foreign-profile
    serialization semantics — planned (ROADMAP U2). Do NOT rely on cross-profile
    bit relationships yet.

@FEATURES: infinite-precision(num-bigint symbolic tier) | serde | inference(rayon
  + tq19) | rebuild-tables | {realtime|compact|embedded|balanced|scientific} |
  legacy-tests. Core (all domains, transcendentals, wide ints, UGOD) always compiled.

@PATH-CHOICE:
  canonical → mixed/chained/user-input work (routing + chain persistence, overhead)
  imperative → known-domain hot loops (direct, Copy, no routing)
  fused → ML accumulation shapes (softmax/silu/rms/distance, compute-tier)
  tq19 → ternary-quantized inference (feature=inference)
  correctness is PATH-INDEPENDENT (same engines, same rounding)

@VALIDATION: mpmath refs 50-250 digits as exact strings (no floats). Decimal paths
  CI-graded vs mootable/decimal-scaled adversarial corpus.

@LIMITS: input-representation error (0.3, 1/3 inexact in binary → pick exact domain)
  | conditioning amplifies input error O(κ) | error is deterministic everywhere.
```

---

Built by **Niels Erik Toren** — [support & donations](README.md#author--support).