Crate holonomy_bounded 

Holonomy-Bounded

A production-quality Rust implementation of the Bounded Drift Theorem for Eisenstein lattice snap operations.

Theorem

For a closed cycle of n Eisenstein snap operations, each with error bounded by ε, the total holonomy (drift) satisfies:

holonomy ≤ n · ε

This bound is tight for worst-case adversarial errors (tightness ~ 1.0 for small n), but for random errors the typical drift scales as O(√n · ε).

Eisenstein Lattice

The Eisenstein lattice ℤ[ω] consists of points a + bω where ω = e^(2πi/3) = (-1 + i√3)/2. The lattice has 6-fold rotational symmetry and forms a regular hexagonal tiling of the complex plane.

The Voronoi cell of each lattice point is a regular hexagon with:

• Inradius: 0.5 (distance from center to edge midpoint)
• Circumradius: 1/√3 ≈ 0.57735 (distance from center to vertex)

Usage

use holonomy_bounded::BoundedDrift;

// Create a float-64 bounded drift tracker with epsilon=0.5
let mut bd = BoundedDrift::<f64>::new(0.5);

// Walk a closed hexagon (6 steps that sum to zero on the lattice)
let cycle = [0, 1, 2, 3, 4, 5];
for &idx in &cycle { bd.step(idx); }

// After a closed cycle, holonomy is bounded by n*epsilon = 6*0.5 = 3.0
let holonomy = bd.holonomy();
assert!(holonomy <= bd.bound(), "hol={} > bound={}", holonomy, bd.bound());

Structs

BoundedDrift

Tracks the drift of a sequence of snap operations on the Eisenstein lattice.

Cycle

A fixed-size cycle on the Eisenstein lattice.

Eisenstein

An Eisenstein integer a + bω.

Constants

LATTICE_STEPS

The six primitive Eisenstein lattice vectors in (a, b) coordinates.

VORONOI_CIRCUMRADIUS

The circumradius of the Eisenstein lattice Voronoi cell: 1/√(3).

VORONOI_INRADIUS

The inradius of the Eisenstein lattice Voronoi cell: 0.5.

Traits

Float

Minimal floating-point trait for generic drift tracking.

Functions

snap_to_lattice

Find the nearest lattice point to a given Cartesian position (x, y).

step_vector

Convert a lattice step index to a directional vector in (a, b) Eisenstein coordinates.

walk_cycle_worst_case

Walk a cycle with worst-case (maximal) error at each step.