geoit 0.0.2

Exact geometric algebra with governed multivectors
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
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178

# 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

```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
```

## One-call CGA

Skip manual governance construction entirely:

```rust
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:

```rust
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:

```rust
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

| Algebra | Signature | What it's for |
|---------|-----------|---------------|
| 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.

## 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