Struct BoundedDrift 

pub struct BoundedDrift<F> {
    pub a: i64,
    pub b: i64,
    /* private fields */
}

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

Each step moves along a lattice direction, then applies an imperfect snap that introduces error bounded by ε (epsilon). The cumulative drift (holonomy) after n steps is bounded by n · ε.

Type Parameters

• F: The floating-point type used for tracking. Either f32 or f64.

Example

use holonomy_bounded::BoundedDrift;

let mut tracker = BoundedDrift::<f64>::new(0.1);
tracker.step(3); // a -= 1
tracker.step(0); // a += 1 (back to origin ideally)
println!("Holonomy: {}", tracker.holonomy());

Safety Proof

For each step, the error e_i satisfies 0 ≤ e_i < ε. After n steps, by the triangle inequality:

holonomy = ||P_n - P_0|| = ||Σ_i e_i · v_i|| ≤ Σ_i ||e_i · v_i|| = Σ_i e_i < n · ε

where v_i are unit vectors. The Eisenstein lattice ensures that adjacent lattice points are unit distance apart, so the maximum drift from a single mis-snap is at most ε.

Fields

a: i64

Current position (Eisenstein coordinates)

b: i64

Current position (Eisenstein coordinates)

Implementations

impl<F: Float> BoundedDrift<F>

pub fn new(epsilon: F) -> Self

Create a new bounded drift tracker with a given per-step error bound.

The tracker starts at the origin (0, 0).

pub fn step(&mut self, index: usize)

Take a step in direction index, applying the cumulative drift model.

The direction index corresponds to LATTICE_STEPS:

• 0: +1 (a += 1)
• 1: -1 + ω (a -= 1, b += 1)
• 2: -ω (b -= 1)
• 3: -1 (a -= 1)
• 4: 1 - ω (a += 1, b -= 1)
• 5: +ω (b += 1)

After each step, the drift from origin is bounded by step_count * epsilon.

Panics

Panics if index >= 6.

pub fn step_with_error(&mut self, index: usize, actual_error: F)

Record a step with a known actual error.

This is useful for simulations that compute the actual snap error and want to track both the empirical drift and the theoretical bound.

The actual_error must be < epsilon for the bound to apply.

pub fn holonomy(&self) -> F

Current holonomy (drift from origin) as Euclidean distance.

This is the actual distance from the current position to the origin, in the complex plane (Cartesian metric).

pub fn bound(&self) -> F

The theoretical bound on holonomy after n steps: n · ε.

pub fn check_bound(&self) -> bool

Check whether the current holonomy satisfies the bound.

pub fn steps(&self) -> usize

Number of steps taken so far.

pub fn total_error(&self) -> F

Total accumulated error (Σ e_i, bounded by n·ε).

pub fn max_step_error(&self) -> F

Maximum single-step error observed.

pub fn reset(&mut self)

Reset the tracker to the origin.

Trait Implementations

impl<F: Clone> Clone for BoundedDrift<F>

fn clone(&self) -> BoundedDrift<F>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<F: Debug> Debug for BoundedDrift<F>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.