# 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 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.
**Constructibility.** Compass-ruler constructibility checking via the pencil hierarchy. An angle is constructible iff its radical tower has power-of-two total degree.
**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.
## Quick start
```rust
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
```
## Rotors
```rust
use geoit::governance::rotor::*;
use geoit::governance::expr::Expr;
// 90° rotation in the e₁e₂ plane
let rotor = coordinate_rotor_expr(0, 1, 1, 2).unwrap(); // angle = π/2
// Apply to e₁: should give e₂
let rotated = apply_rotor(rotor, Expr::Generator(0));
```
The angle is specified as a rational multiple of π. `(1, 2)` means π/2 = 90°. `(1, 3)` means π/3 = 60°. `(1, 6)` means π/6 = 30°. Every trig value is an exact radical element.
## Supported algebras
| VGA(2), VGA(3) | Cl(0,0,n) | Euclidean geometry |
| PGA(2), PGA(3) | Cl(0,1,n) | Projective geometry |
| CGA(2), CGA(3) | Cl(1,0,n+1) | Conformal geometry (circles, spheres) |
| STA | Cl(1,0,3) or Cl(3,0,1) | Spacetime algebra |
| QGA(3), QCGA | Cl(3,0,3), Cl(4,0,4) | Quadric geometry |
Any signature up to 64 generators is supported. These are just the ones with dedicated test coverage.
## Governance
The governance system is what makes geoit different from other GA libraries. Instead of treating multivectors as raw coefficient bags, governance attaches mathematical meaning:
```rust
// A CGA point must:
// - Live in grade 1
// - Satisfy the null condition: x² = 0
// - Have nonzero e∞ component (normalization)
//
// The governance checks all three when you call govern().
// The result is a Geoit: an Mv that proved it's a valid point.
```
Governance also tracks **phase** — whether a multivector's participating generators are Euclidean (Commitment), degenerate (Evaluation), or hyperbolic (Deliberation). This tells you what kind of geometric object you're holding before you inspect its coefficients.
## 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
- 16,800 lines of Rust
- 608 tests
- 49 source files
- 0 dependencies
- 0 `f32` or `f64` anywhere
## License
MIT OR Apache-2.0