KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #developer-tools #cli #codex #claude-code #dsh-plugin #mcp #react #agent #dsh #deepseek-harness

geonum

★ 18 Open GitHub ↗

geometric number library supporting unlimited dimensions with O(1) complexity

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<br>
<p align="center"><img width="225" alt="dual" src="shield.gif"></p>
<br>
<p align="center">scaling scientific computing with the <a href="https://gist.github.com/mxfactorial/c151619d22ef6603a557dbf370864085" target="_blank">geometric number</a> spec</p>
<div align="center">

[![build](https://github.com/mxfactorial/geonum/actions/workflows/publish.yaml/badge.svg)](https://github.com/mxfactorial/geonum/actions)
[![docs](https://docs.rs/geonum/badge.svg)](https://docs.rs/geonum)
[![dependency status](https://deps.rs/repo/github/mxfactorial/geonum/status.svg)](https://deps.rs/repo/github/mxfactorial/geonum)
[![crates.io](https://img.shields.io/crates/v/geonum.svg)](https://crates.io/crates/geonum)
[![Discord](https://img.shields.io/discord/1519537430414495845.svg?label=&logo=discord&logoColor=ffffff&color=7389D8&labelColor=6A7EC2)](https://discord.gg/rPyRAbwK3)
[![contribute](https://img.shields.io/badge/contribute-paypal-brightgreen.svg)](https://www.paypal.com/paypalme/mxfactorial)
</div>

# geonum

removing an explicit angle from numbers in the name of "pure" math throws away primitive geometric information

once you amputate the angle from a number to create a "scalar", you throw away its compass

computing angles when they deserve to be static forces math into a cave where numbers must be cast from linearly combined shadows

you start by creating a massive artificial "scalar" superstructure of "dimensions" to store **every possible position** where your scalar vector component can appear—and as a "linear combination" of the dimensions it "spans" with other scalars called "basis vectors"

this brute force scalar alchemy explodes into scalars **everywhere**

with most requiring "sparsity" to conceal how many explicit zeros appear declaring *nothing changed*

the omission of geometry is so extreme at this point its suspicious

now your number hobbles through a prison of complicated "matrix" and "tensor" operations computing expensive dot & cross products in a scalar-dimension chain gang with other "linearly independent" scalars—only to reconstruct the simple detail of the direction its facing

and if you want to change its rate of motion, it must freeze all other scalar dimensions in a "partial derivative" with even more zeros

### protect your numbers

setting a metric with euclidean and squared norms between "linearly combined scalars" creates an n-dimensional, rank-k (`n^k`) component orthogonality search problem for transforming vectors

and supporting traditional geometric algebra operations requires `2^n` components to represent multivectors in `n` dimensions

geonum reduces `n^k(2^n)` to 2

geonum dualizes (⋆) components inside algebra's most general form

setting the metric from the quadrature's bivector shields it from entropy with the `log2(4)` bit minimum:

- 1 scalar, `cos(θ)`
- 2 vector, `sin(θ)cos(φ), sin(θ)sin(φ)`
- 1 bivector, `sin(θ+π/2) = cos(θ)`

```rs
/// dimension-free, geometric number
struct Geonum {
    magnitude: f64,   // multiply
    angle: Angle {    // add
        blade: usize,    // π/2 rotation count
        t: f64           // tan(θ/2) blade projection ratio
    }
}
```
* project(onto: Angle) -> angle_diff.cos() into any dimension without defining it first
* dual() = blade + 2, duality operation adds π rotation and involutively maps grades (0 ↔ 2, 1 ↔ 3)
* grade() = blade % 4, geometric grade
* differentiate() = angle + π/2, polynomial coefficients computed from sin(θ+π/2) = cos(θ) quadrature identity
* replaces "pseudoscalar" with blade arithmetic

### how dimensions work

dimensions = blade, how many dimensions the angle spans

traditional: dimensions are coordinate axes - you stack more coordinates

Geonum: dimensions are rotational states - you rotate by π/2 increments

| dimension | traditional  | Geonum              |
| --------- | ------------ | ------------------- |
| 1D        | (x)          | `[magnitude, 0]`    |
| 2D        | (x, y)       | `[magnitude, π/2]`  |
| 3D        | (x, y, z)    | `[magnitude, π]`    |
| 4D        | (x, y, z, w) | `[magnitude, 3π/2]` |

geometric numbers break numbers free from pencil & paper math requiring everything to be described as scalars and roman numeral stacked arrays of scalars

a bladed angle lets them travel and transform freely without ever needing to know which dimension theyre in or facing

### use

```
cargo add geonum
```

### example

draw points and lines from one angle — dimension free

```rust
use geonum::*;

let origin = Geonum::new(5.0, 0.0, 1.0);

// target angles
let a0 = Angle::new(1.0, 6.0);  // π/6
let a1 = Angle::new(1.0, 3.0);  // π/3
let a2 = Angle::new(1.0, 2.0);  // π/2
let a3 = Angle::new(2.0, 3.0);  // 2π/3

// project onto angles — the projection IS the line between points
let line_to_p0 = origin.angle.project(a0);
let p0 = Geonum::new_with_angle(origin.mag * line_to_p0, a0);

let line_to_p1 = p0.angle.project(a1);
let p1 = Geonum::new_with_angle(p0.mag * line_to_p1, a1);

let line_to_p2 = p1.angle.project(a2);
let p2 = Geonum::new_with_angle(p1.mag * line_to_p2, a2);

let line_to_p3 = p2.angle.project(a3);
let p3 = Geonum::new_with_angle(p2.mag * line_to_p3, a3);

// every projection is cos(angle_diff)
let step = std::f64::consts::PI / 6.0;
assert!((line_to_p0 - step.cos()).abs() < 1e-10);
assert!((line_to_p1 - step.cos()).abs() < 1e-10);

// lineage: p3 traces back to origin through all projection coefficients
let lineage = origin.mag * line_to_p0 * line_to_p1 * line_to_p2 * line_to_p3;
assert!((p3.mag - lineage).abs() < 1e-10);

// dimension free: project to blade 1_000_000 with same O(1) operation
let a_million = Angle::new_with_blade(1000000, 2.0, 3.0);
let p_million = Geonum::new_with_angle(p3.mag * p3.angle.project(a_million), a_million);
assert!((p_million.mag - p3.mag).abs() < 1e-10);
```

projection creates dimensional relationships on demand — no basis vectors, no coordinate scaffolding

see [tests](https://github.com/mxfactorial/geonum/tree/main/tests) to learn how geometric numbers unify and simplify mathematical foundations including set theory, category theory and algebraic structures:

```
❯ ls -1 tests
addition_test.rs
affine_test.rs
algebra_test.rs
algorithms_test.rs
angle_arithmetic_test.rs
anomaly_test.rs
arithmetic_test.rs
astrophysics_test.rs
atomic_clock_test.rs
calculus_test.rs
category_theory_test.rs
cga_test.rs
chem_constants_test.rs
chemistry_test.rs
computer_vision_test.rs
control_test.rs
convolution_test.rs
cosmology_test.rs
crystallography_test.rs
curve_test.rs
dimension_test.rs
directional_stats_test.rs
economics_test.rs
einstein_test.rs
em_field_theory_test.rs
exponential_test.rs
fem_test.rs
field_test.rs
finance_test.rs
fluid_test.rs
gauss_bonnet_test.rs
geocollection_test.rs
geometry_test.rs
grade_test.rs
gravitational_wave_test.rs
holonomy_test.rs
integral_test.rs
interferometer_test.rs
linear_algebra_test.rs
machine_learning_test.rs
mechanics_test.rs
ml_attention_test.rs
ml_training_test.rs
monetary_policy_test.rs
motion_laws_test.rs
multivalued_test.rs
multivector_test.rs
music_test.rs
numbers_test.rs
optics_test.rs
optimization_test.rs
orbit_test.rs
pga_test.rs
phasor_test.rs
projection_test.rs
pseudoscalar_test.rs
qm_test.rs
quantum_computing_test.rs
quaternion_test.rs
rendering_test.rs
renormalization_test.rs
robotics_test.rs
sampling_test.rs
schwarzschild_test.rs
set_theory_test.rs
smith_chart_test.rs
spacetime_test.rs
spinor_test.rs
sr_gr_collapse_test.rs
stability_test.rs
taylor_series_test.rs
tensor_test.rs
thermo_test.rs
trigonometry_test.rs
whisper_test.rs
```

### benches

#### tensor operations: O(n³) vs O(1)

| implementation | size | time    | speedup  |
| -------------- | ---- | ------- | -------- |
| tensor (O(n³)) | 2    | 372 ns  | baseline |
| tensor (O(n³)) | 3    | 836 ns  | baseline |
| tensor (O(n³)) | 4    | 1.47 µs | baseline |
| tensor (O(n³)) | 8    | 7.80 µs | baseline |
| geonum (O(1))  | all  | 15 ns   | 25-520×  |

geonum achieves constant 15ns regardless of size, while tensor operations scale cubically from 372ns to 7.80µs

#### extreme dimensions

| implementation | dimensions | time       | storage                    |
| -------------- | ---------- | ---------- | -------------------------- |
| traditional GA | 10         | 7.18 µs    | 2^10 = 1024 components     |
| traditional GA | 30+        | impossible | 2^30 = 1B+ components      |
| traditional GA | 1000+      | impossible | 2^1000 > atoms in universe |
| geonum         | 10         | 35 ns      | 2 values                   |
| geonum         | 30         | 34 ns      | 2 values                   |
| geonum         | 1000       | 35 ns      | 2 values                   |
| geonum         | 1,000,000  | 35 ns      | 2 values                   |

geonum enables million-dimensional geometric algebra with constant-time operations

#### operation benchmarks

| operation          | traditional       | geonum | speedup            |
| ------------------ | ----------------- | ------ | ------------------ |
| jacobian (10×10)   | 1.42 µs           | 23 ns  | 62×                |
| jacobian (100×100) | 102 µs            | 23 ns  | 4435×              |
| rotation 2D        | 4.9 ns            | 5 ns   | comparable         |
| rotation 3D        | 20 ns             | 20 ns  | comparable         |
| rotation 10D       | 173 ns            | 21 ns  | 8×                 |
| geometric product  | decomposition     | 18 ns  | direct             |
| wedge product 2D   | 2.2 ns            | 21 ns  | trigonometric      |
| wedge product 10D  | 45 components     | 21 ns  | constant           |
| dual operation     | pseudoscalar mult | 10 ns  | universal          |
| differentiation    | numerical approx  | 3 ns   | exact π/2 rotation |
| inversion          | matrix ops        | 13 ns  | direct reciprocal  |
| projection         | dot products      | 12 ns  | trigonometric      |

all geonum operations maintain constant time regardless of dimension, eliminating exponential scaling of traditional approaches

### features

#### core operations
- dot product `.dot()`, wedge product `.wedge()`, geometric product `.geo()` and `*`
- inverse `.inv()`, division `.div()` and `/`, normalization `.normalize()`
- rotations `.rotate()`, reflections `.reflect()`, projections `.project()`, rejections `.reject()`
- scale `.scale()`, scale-rotate `.scale_rotate()`, negate `.negate()`
- differentiation `.differentiate()` via π/2 rotation, integration `.integrate()` via -π/2 rotation
- meet `.meet()` for subspace intersection with geonum's π-rotation incidence structure
- orthogonality test `.is_orthogonal()`, distance `.distance_to()`, magnitude difference `.mag_diff()`

#### angle-blade architecture
- blade count tracks π/2 rotations: 0→scalar, 1→vector, 2→bivector, 3→trivector
- grade = blade % 4 determines geometric behavior regardless of dimension
- `.blade()` returns full transformation history, `.grade()` returns geometric grade
- `.base_angle()` resets blade to minimum for grade (memory optimization)
- `.increment_blade()` and `.decrement_blade()` for direct blade manipulation
- `.copy_blade()` transfers blade structure between geonums

#### dimension handling
- million-dimension geometric algebra with O(1) complexity
- `.project_to_dimension(n)` computes projection to any dimension on demand
- `.create_dimension(length, n)` creates standardized n-dimensional basis element
- dimensions emerge from angle arithmetic, no predefined basis vectors needed
- conformal geometric algebra without 32-component storage
- projective geometric algebra without homogeneous coordinates

#### duality without pseudoscalars
- `.dual()` adds π rotation (2 blades), maps grades 0↔2, 1↔3
- `.undual()` identical to dual in 4-cycle structure  
- `.conjugate()` for clifford conjugation
- universal k→(k+2)%4 duality replaces dimension-specific k→(n-k) formulas
- eliminates I = e₁∧...∧eₙ pseudoscalar and its 2^n storage requirement

#### automatic calculus
- differentiation through π/2 rotation eliminates limit computation
- polynomial coefficients emerge from quadrature sin(θ+π/2) = cos(θ)
- grade cycling: f→f'→f''→f'''→f with grades 0→1→2→3→0
- no symbolic manipulation, no numerical approximation

#### constructors
- `Geonum::new(magnitude, pi_radians, divisor)` - basic constructor
- `Geonum::new_with_angle(magnitude, angle)` - from angle struct
- `Geonum::new_from_cartesian(x, y)` - from cartesian coordinates
- `Geonum::new_with_blade(magnitude, blade, pi_radians, divisor)` - explicit blade
- `Geonum::scalar(value)` - scalar at grade 0
- `Angle::new(pi_radians, divisor)` - angle from π fractions
- `Angle::new_with_blade(blade, pi_radians, divisor)` - angle with blade offset
- `Angle::new_from_cartesian(x, y)` - angle from coordinates

#### special operations
- `.pow(n)` for exponentiation preserving angle-magnitude relationship
- `.invert_circle(center, radius)` for conformal inversions
- angle predicates: `.is_scalar()`, `.is_vector()`, `.is_bivector()`, `.is_trivector()`
- angle functions: `.sin()`, `.cos()`, `.tan()`, `.is_opposite()`
- `.grade_angle()` returns grade-based angle representation in [0, 2π) for external interfaces

### tests
```
cargo check # compile
cargo fmt --check # format
cargo clippy # lint
cargo test --lib # unit
cargo test --test "*" # feature
cargo test --doc # doc
cargo bench # bench
cargo llvm-cov # coverage
```

### eli5

geometric numbers depend on 2 rules:

1. all numbers require a 2 component minimum:
    1. magnitude number
    2. angle radian
2. angles add, mags multiply

so:

- a 1d number or scalar: `[4, 0]`
    - 4 units long facing 0 radians
- a 2d number or vector: `[4, pi/2]`
    - the same 4 units, one quarter turn on
- a 3d number: `[4, pi]`
    - two quarter turns — still two components, not three

higher dimensions just keep rotating by +pi/2 — the millionth dimension costs the same two components as the first

dimensions are created by rotations and not stacking coordinates

multiplying numbers adds their angles and multiplies their magnitudes:

- `[2, 0] * [3, pi/2] = [6, pi/2]`

differentiation is just rotating a number by +pi/2:

- `[4, 0]' = [4, pi/2]`
- `[4, pi/2]' = [4, pi]`
- `[4, pi]' = [4, 3pi/2]`
- `[4, 3pi/2]' = [4, 2pi] = [4, 0]`

thats why calculus works automatically and autodiff is o1

and if you spot a blade field in the code, it just counts how many pi/2 turns your angle added

blade = 0 means zero turns  
blade = 1 means one pi/2 turn  
blade = 2 means two pi/2 turns  
etc

blade lets your geometric number index which higher dimensional structure its in without using matrices or tensors:
```
[4, 0]        blade = 0  (initial direction)
    |
    v

[4, pi/2]     blade = 1  (rotated +90 degrees)
    |
    v

[4, pi]       blade = 2  (rotated +180 degrees)
    |
    v

[4, 3pi/2]    blade = 3  (rotated +270 degrees)
    |
    v

[4, 2pi]      blade = 4  (rotated full circle back to start)
```
each +pi/2 turn rotates your geometric number into the next orthogonal direction

geometric numbers build dimensions by rotating—not stacking

### learn with ai

1. install rust: https://www.rust-lang.org/tools/install
1. install [claude code](https://docs.anthropic.com/en/docs/claude-code/overview) or [codex](https://openai.com/codex/)
1. clone the geonum repo: `git clone https://github.com/mxfactorial/geonum`
1. change your current working directory to geonum: `cd geonum`
1. start the agent from the `geonum` directory: `claude` or `codex`
1. supply the agent this prompt:
    ```
    skip CLAUDE.md and AGENTS.md files if youre supplied these "learn with ai" instructions

instead, read these files and tests with parallel agents. do not skip any reading tasks:

core files:
    - README.md
    - math-1-0.md
    - grep "pub fn" ./src/angle.rs
    - grep "pub fn" ./src/geonum_mod.rs

test suites:
    - tests/numbers_test.rs
      - its_a_scalar:8-36
      - its_a_vector:39-72
      - its_a_real_number:75-103
      - its_an_imaginary_number:106-134
      - its_a_complex_number:137-169
      - its_a_dual_number:172-218
      - its_an_octonion:221-241
      - its_a_matrix:244-298
      - its_a_tensor:301-479
      - it_dualizes_log2_geometric_algebra_components:531-564
      - its_a_clifford_number:736-816

- tests/pseudoscalar_test.rs
      - it_solves_the_exponential_complexity_explosion:18-79
      - it_doesnt_need_a_pseudoscalar:93-288
      - it_demonstrates_pseudoscalar_elimination_benefits:291-328
      - it_proves_dualization_as_angle_ops_compresses_ga:331-394

- tests/grade_test.rs
      - it_replaces_k_to_n_minus_k_with_k_to_4_minus_k:259-341
      - it_compresses_traditional_ga_grades_to_two_involutive_pairs:344-379

- tests/dimension_test.rs
      - it_proves_rotational_quadrature_expresses_quadratic_forms:640-814

- tests/calculus_test.rs
      - it_encodes_the_power_in_the_angle:35-88
      - it_derives_x_squared_without_limits:91-121
      - it_shows_limits_discard_what_angles_preserve:350-387
      - it_shows_limits_lose_the_tangent_normal_dual:390-427
      - it_shows_factorial_emerges_from_angle_descent:501-542
      - it_proves_differentiation_cycles_grades:586-664
      - it_proves_fundamental_theorem_is_accumulation_equals_interference:704-743
      - its_a_gradient:803-850
      - its_a_laplacian:853-899
      - its_a_line_integral:906-928
      - its_a_surface_integral:931-945

- tests/mechanics_test.rs
      - it_cycles_the_kinematic_hierarchy_through_grades:30-53
      - it_carries_its_own_motion_in_the_quarter_turn:56-105
      - it_grows_displacement_quadratically_from_derived_acceleration:108-145
      - it_reads_kinematic_level_off_grade_not_blade:148-166
      - it_dots_velocity_into_kinetic_energy:266-289
      - it_conserves_energy_as_the_phase_magnitude:556-597
      - it_conserves_momentum_because_the_interaction_forces_are_pi_apart:437-464
      - it_conserves_angular_momentum_because_the_wedge_is_antisymmetric:467-503

create tests/my_test.rs with use geonum::*;
    ```
1. describe the test you want the agent to implement for you while using the other test suites and library as a reference, eg "lets prove we can compute the minimum distance from a point to a line using geonum"
1. execute your test: `cargo test --test my_test -- --show-output`
1. revise and add tests
1. ask the agent to summarize your tests and how they benefit from angle-based complexity
1. ask the agent more questions:
    - what does the math in the leading readme section mean?
    - how does the geometric number spec in math-1-0.md improve computing performance?
    - what is the tests/tensor_test.rs file about?

geonum

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README