geoit

Exact geometric algebra in Rust. No floats. No dependencies.

geoit is a Clifford algebra engine where every number is mathematically exact — rational arithmetic backed by i128, with automatic promotion to arbitrary precision or radical extensions when needed. There is no f32 or f64 anywhere in the computation pipeline.

On top of the algebra sits a governance layer: a constraint system that certifies multivectors as belonging to named geometric classes (points, lines, circles, spheres) by checking grade structure, polynomial equations, and inequality conditions at construction time. A Geoit is a multivector that carries proof of its own validity.

What's new in v0.0.2

Algebra families. standard_registry() ships VGA, CGA, and PGA as parameterized families. One call produces a complete governance at any spatial dimension — no manual construction needed.

Governance composition. Declare transform rules ("sandwich of rotor and vector produces a vector") and apply them to produce new Geoits with derived proofs instead of re-verification.

Integer polynomial compilation. Compile field evaluations into flat i64 multiply-accumulate plans. The render hot path has zero allocation, zero dispatch, zero floating-point.

Generator profiles. Every Geoit carries i/d/h bitmasks tracking generator participation. Profiles can be prescriptive: a class can reject Mvs with unexpected generators.

Governed morphisms. Connect algebras with class-preserving morphisms. Embed a VGA vector into CGA and get a governed Geoit in the target algebra.

Pencil hierarchy. Automatically discover what new objects can be constructed from existing classes via joins and meets. Classify pencil families. Check compass-ruler constructibility.

Quick start

use geoit::*;
use geoit::scalar::Rat;
use geoit::algebra::ops;

// VGA(3): three generators, all squaring to +1
let sig = Signature::new(0, 0, 3).unwrap();

// Build a vector: 3e₁ + 4e₂
let v = Mv::from_rat_terms(&[
    (0b001, Rat::from(3)),
    (0b010, Rat::from(4)),
]);

// Norm squared: 3² + 4² = 25
let n2 = ops::norm_squared(&v, &sig);
assert_eq!(n2.coefficient(0), Scalar::from(25i64));

// Outer product: v ∧ w
let w = Mv::from_rat_terms(&[(0b100, Rat::from(1))]);
let bv = ops::outer(&v, &w, &sig);
// Result is a bivector in the e₁e₃ and e₂e₃ planes

One-call CGA

Skip manual governance construction entirely:

use geoit::*;
use geoit::governance;

let gov = standard_registry().instantiate_family("CGA", 2).unwrap();
let point = gov.construct(0, &[Scalar::from(3), Scalar::from(4)]).unwrap();
let geoit = governance::govern(&point, &gov, 0).unwrap();
assert!(geoit.is_satisfied());
// Read back the construction parameters
let params = geoit.read_all().unwrap();
assert_eq!(params, vec![Scalar::from(3), Scalar::from(4)]);

Works at any dimension: "CGA" at 2, 3, 5, 10. Also "VGA" and "PGA".

Transform rules

Declare algebraic operations as governed rules:

use geoit::*;
use geoit::governance::rule::TransformOp;

let alg = Algebra::new(Signature::new(0, 0, 3).unwrap());
let class = GeomClassBuilder::new(&alg).grades(&[1]).build();
let body = Expr::Add(
    Expr::add(Expr::mul(Expr::param(0), Expr::gen(0)),
              Expr::mul(Expr::param(1), Expr::gen(1))),
    Expr::mul(Expr::param(2), Expr::gen(2)),
);
let gov = GovernanceBuilder::new(alg)
    .class("Vector", class)
    .construction("Vector", "Vector", 3, body)
    .rule("Reverse", &["Vector"], "Vector", TransformOp::Reverse)
    .build();

let params = vec![Scalar::from(3), Scalar::from(4), Scalar::from(5)];
let mv = gov.construct("Vector", &params).unwrap();
let geoit = gov.govern(&mv, "Vector").unwrap();
let reversed = gov.transform("Reverse", &[&geoit]).unwrap();
assert_eq!(reversed.mv(), geoit.mv()); // grade-1 reversal is identity

Compiled field evaluation

Compile governance expressions into integer polynomials for the rendering pipeline:

use geoit::*;
use geoit::governance::compile::compile_field_eval;

let sig = Signature::new(0, 0, 3).unwrap();
let object = Mv::from_rat_terms(&[
    (0b001, Rat::from(3)),
    (0b010, Rat::from(4)),
    (0b100, Rat::from(5)),
]);
let compiled = compile_field_eval(&object, &FieldOp::ScalarProduct, &sig, 3, 0);

// Per-pixel: pure i64 arithmetic, zero allocation
assert_eq!(compiled.eval_scalar(&[1, 0, 0]), 3);
assert_eq!(compiled.eval_scalar(&[1, 1, 1]), 12);

What's in the box

Algebra engine. Sparse multivectors over any Clifford algebra Cl(i,d,h) with up to 64 generators. Full product suite: geometric, outer, inner, left contraction, scalar product, regressive, sandwich, dual, reverse, grade involution, inverse.

Exact scalar tower. Rat (i128/u128) → BigRat (arbitrary precision) → RadicalElement (tower extensions like ℚ(√2, √3)). Overflow promotes automatically; rational results demote back. √2 + √3 works. ∛2 works. Reciprocals in multi-layer towers work.

Governance. Define geometric classes with grade masks and polynomial constraints. Attach construction formulas (Expr AST). The engine validates multivectors against classes and extracts construction parameters via Gröbner basis computation. Transform rules compose governance through proof-carrying derivation chains.

Algebra families. standard_registry() ships VGA, CGA, and PGA as parameterized families with inter-family morphisms and step embeddings. instantiate(n) produces a complete GovernanceCategory with all three families at dimension n.

Constructibility. Compass-ruler constructibility checking via the pencil hierarchy. Recursive build_full_hierarchy iterates join/meet levels to closure. Pencil classification by discriminant structure. Transform rule emission from pencil levels.

Compilation. PartialMv (Mv with polynomial coefficients), Expr partial evaluator, and compiled field evaluation for all six FieldOp variants. The render pipeline is integer polynomial evaluation with no allocation.

Exact rotors. Build rotors from constructible angles via the Euler identity: cos(θ/2) + sin(θ/2)·B̂. Exact cos and sin for rational multiples of π with denominators 1, 2, 3, 4, 6, 12. The sandwich product R·x·R̃ gives exact rotations with no floating-point drift.

Native codec. Zero-dependency binary serialization for GeoitSnapshot, Governance, and Mv. LEB128 lengths, little-endian fixed-width. Lossless roundtrip.

Where to start

1. [Signature] — define your algebra: Signature::new(1, 0, 3)? for CGA(2)
2. [Mv] — build multivectors with exact rational coefficients
3. [algebra::ops] — compute products, norms, duals, sandwiches
4. [GovernanceBuilder] — define geometric classes with polynomial constraints
5. [govern()] / [Geoit] — verify and certify a multivector
6. [standard_registry()] — skip steps 1–4, get a working CGA/PGA/VGA in one call

If you just want to get started: use standard_registry().instantiate_family("CGA", 2) and go.

Supported algebras

Any signature up to 64 generators is supported. These are just the ones with dedicated test coverage.

Design choices

Zero floats. Not "mostly exact" or "exact where possible." There is no floating-point code path. The renderer (separate crate, not included here) converts to pixels at the very last step.

Zero dependencies. The BigInt, BigRat, radical tower, Gröbner basis, codec, and everything else are implemented from scratch. The only use is std.

Sparse representation. Multivectors store only nonzero terms as sorted Vec<(BladeKey, Scalar)>. A CGA point with 5 nonzero components doesn't allocate for the other 27 zero components of a 32-dimensional algebra.

Arc<Governance>. Multiple geoits verified against the same governance share one heap allocation. Cloning a Geoit is cheap.

Numbers

• 17,795 lines of Rust (source)
• 665 tests
• 45 source files
• 0 dependencies
• 0 f32 or f64 anywhere

License

MIT OR Apache-2.0