g_math

Pure-Rust, zero-float, deterministic multi-domain fixed-point arithmetic.

Built by Niels Erik Toren · published as g_math on crates.io

Upgrading from 0.4.x? 0.5.0 is more accurate, and as a side effect some results end in a different final digit. It matters only if you store, hash, or compare results across versions. The four-line summary is at the top of CHANGELOG.md.

0.6.0 adds certified arithmetic (Interval, DecimalInterval), a proven positive-definiteness verdict (pd_verdict) and exact geometric predicates, all additive. 0.5.1 carries only the three defect fixes that work found in 0.5.0 (two on the scientific profile, one in the wide decimal integers); every ^0.5 user receives them without adopting any new API.

What it is

g_math computes with scaled integers only. No f32/f64 appears anywhere in the arithmetic, validation, or comparison paths (float conversions exist solely as caller-convenience from_f64/to_f64 wrappers). Because every operation is integer arithmetic, results are bit-identical on every architecture - which makes the crate suitable for blockchain consensus, financial auditing, and reproducible scientific computation.

It is a library, not a service: pure computation, no I/O, no ambient state. Values route across four numeric domains (binary, decimal, balanced ternary, symbolic rational), and 18 transcendental functions plus linear algebra, geometry, and ternary-quantized inference are built on top. It is one component of the Geodineum ecosystem and is consumed by its geometric and inference projects.

Public build surface

The build-with surface is five layers; everything beneath them is internal.

• Canonical / router - g_math::canonical: gmath("…") builds a lazy expression, evaluate(…) runs it with cross-domain routing and chain persistence.
• Imperative - g_math::fixed_point::{FixedPoint, FixedVector, FixedMatrix} and DecimalFixed<DECIMALS>: direct Copy types, one call is one engine invocation.
• Fused - g_math::fixed_point::imperative::fused: whole accumulation patterns at the wide compute tier.
• Geometric - imperative::{decompose, derived, matrix_functions, manifold, lie_group, curvature, projective, fiber_bundle, ode, tensor, tensor_decompose, serialization}.
• TQ1.9 - g_math::tq19 (feature inference): standalone ternary inference.
• Internal - the universal/fasc evaluator, the domain implementations beneath DecimalFixed and the ternary types, the wide-integer types, and the shadow/router internals are not part of the surface and may change between releases.

The complete per-symbol index - every public item and a one-line summary - is generated from source into PUBLIC_API.md (rustc -O scripts/gen-public-api.rs -o /tmp/gen-public-api && /tmp/gen-public-api). Live signatures are on docs.rs. This README never re-hosts either.

Guides

Each layer and cross-cutting concept has a focused guide under docs/.

Capabilities

• Four numeric domains - each value is held in the representation that is exact for it (binary, decimal, balanced ternary, or symbolic rational), routed automatically.
• 18 transcendentals - computed one tier wider than storage and rounded once, reachable lazily (gmath), directly (FixedPoint), or natively in decimal (DecimalFixed).
• Two computation paths - a routed canonical layer for mixed or chained work and a direct imperative layer for known-domain hot loops. Results are path-independent: one rounding rule per domain on every path (unified 0.5.0, permanently test-gated: see CONTRACT.md §3).
• Certified arithmetic and exact predicates (0.6.0) - Interval and DecimalInterval return a bracket that provably contains the exact result for + - * /, square root, dot products and quadratic forms (0.6.1: the quadratic form's bracket is at most 1 ulp wide, and fused::quadratic_form is its correctly rounded scalar); pd_verdict proves a matrix positive definite (or not, or says it cannot decide and hands back the straddling bracket); orient2d, orient3d, incircle, insphere return an exact three-way sign. Transcendentals are deliberately excluded from the certified set until their bounds are proven. Design and measured widths: docs/design/CERTIFIED_INTERVALS.md.
• Numerics on top - fused ML ops, dense linear algebra, differential geometry and Lie groups, and standalone TQ1.9 ternary inference.
• Five precision profiles - Q16.16 through Q256.256, chosen at compile time; results are bit-identical across platforms within a profile.
• Zero float internally, zero runtime dependencies by default.

Contract

The precise contract - the supported surface and its stability boundary, the determinism guarantee, the per-domain rounding rules, cross-profile semantics, and what the crate requires - is in CONTRACT.md. Agents should prime from CONTRACT.scn.md.

Quick start

cargo add g_math

use g_math::canonical::{gmath, evaluate};

// "100" and "50" route to binary, "3" keeps the result exact via symbolic routing.
let value = evaluate(&((gmath("100") + gmath("50")) / gmath("3"))).unwrap();
println!("{value}");

From here, follow the guides: the routing guide for mixed-domain and chained work, or the imperative guide for direct hot-loop arithmetic.

Limits worth knowing

• The binary domain can't hold every literal exactly. 0.3 and 1/3 repeat in binary, so the direct FixedPoint path approximates them. The canonical gmath(...) router avoids this for you: it classifies each literal and routes it to a domain where it is exact (0.3→decimal, 1/3→symbolic), carrying the exact value in a CompactShadow - the limit only applies when you pin the binary domain.
• Ill-conditioned systems amplify input error. Solver error scales with the matrix condition number; this is a property of finite precision, not of the implementation.
• Precision differs by profile. A Q16.16 result cannot hold Q64.64 digits; choose the profile for your accuracy and range needs.
• Certified means the arithmetic, not your model. A certified bracket encloses the exact result of the computation on the values you passed in; it cannot see rounding that happened while those values were produced. On the realtime profile the brackets of a 50-dimensional interval Cholesky are a few percent of the pivot; from the compact profile upward they are negligible.
• Switching profiles needs a clean incremental cache (rm -rf target/*/incremental/), or stale cfg artifacts can crash the build.

Collaborate

Contributions are welcome. Open issues and pick up work on the ecosystem board at geodineum.com; issues tagged good-first-issue are a good place to start.

• Fork, branch, and open a pull request against main.
• Any change to a wire contract must update both CONTRACT.md and CONTRACT.scn.md in the same commit.
• A change to a signed extension must be re-signed in the same commit.

Author & support

Built by Niels Erik Toren.

If you want to support the work:

Disclaimer

This software is provided "as is", without warranty of any kind, express or implied. Use of this software is entirely at your own risk. In no event shall the author or contributors be held liable for any damages arising from the use or inability to use this software.

"Certified" is a technical term, not a warranty. Where this documentation says certified, proven or enclosure, it means exactly what CONTRACT.md §3 and docs/design/CERTIFIED_INTERVALS.md define: a statement about the exact integer computation performed on the values passed in, established by construction and gated by tests. It is not a warranty of fitness for any purpose, and the paragraph above applies to it in full.

License

Licensed under either of

• Apache License, Version 2.0
• MIT License

at your option.