hyperlattice

hyperlattice provides small fixed-size linear algebra over hyperreal::Real: complex numbers, 2D/3D/4D vectors, 3x3/4x4 matrices, transforms, and object-level structural facts.

The crate is not a general BLAS replacement. It focuses on the small exact vector and matrix objects that geometry, predicates, solvers, and domain crates repeatedly need.

Hyper Ecosystem

hyperlattice is the object-algebra layer between scalar facts and topology/domain crates.

• hyperreal: exact scalar values and structural facts.
• hyperlimit: predicate layer that consumes point, vector, determinant, and shared-scale facts.
• hypercurve, hypertri, and hypermesh: geometry crates that reuse exact small-vector and transform structure.
• hypersolve: residual and linear-algebra preparation over exact scalars.
• hyperphysics and hypervoxel: domain crates that need exact vectors, transforms, and object-level facts.

Typical Linear-Algebra Problems

Small linear algebra sits on the fault line between performance and exactness. Floating matrices are fast but can hide singular pivots, near-zero determinants, and transform-kind assumptions. Full symbolic expansion preserves meaning but can grow before a caller knows whether a cheap structural fact was enough.

hyperlattice keeps objects small and facts local. Zero masks, homogeneous point/direction tags, determinant schedule hints, sparse support, shared-scale views, and prepared matrix cache summaries let callers skip known-zero work, choose exact reducers, and delay scalar canonicalization until a result is needed.

Main Types

• Complex provides exact complex arithmetic and integer powers.
• Vector2, Vector3, Vector4, homogeneous vector facts, shared-scale views, and signed-axis helpers describe small exact vectors.
• Matrix3, Matrix4, transform handles, transformed-vector/matrix views, prepared matrix handles, and prepared right-divisor handles describe small exact matrices.
• Matrix3StructuralFacts, Matrix4StructuralFacts, transform-kind enums, determinant schedule hints, and cache summaries preserve matrix structure.
• Displacement2Facts, ProductTerm2Facts, ProductSum2Facts, and Orient2Facts expose exact 2D algebra facts for predicate and curve callers.
• AbortSignal, BlasResult, checked result types, zero-status helpers, and scalar function wrappers provide fallible exact operations.

Precision Model

All native scalar, vector, complex, and matrix operations use Real. Primitive floats should appear only at named import/export, rendering, diagnostics, or interop edges. Checked operations reject definite-zero and unknown-zero divisors or pivots instead of rounding through a singular path.

hyperlattice preserves object facts that hyperreal cannot know by itself: coordinate zero masks, homogeneous shape, shared scale, affine/translation/diagonal/projective transform kind, determinant schedule, and prepared cache availability.

Performance Model

The crate reduces exact cost by exploiting fixed sizes and retained structure. Matrix multiplication is unrolled, small powers are specialized before exponentiation by squaring, borrowed arithmetic avoids unnecessary cloning, and product-sum reducers preserve rational structure. Prepared matrix and right-divisor handles let callers reuse determinant, adjugate, reciprocal, minor, and inverse work without exposing internal cache storage.

Benchmarks track scalar, vector, matrix, prepared-cache, and dispatch-trace behavior so shortcuts can be accepted only when they help the target surface without destabilizing nearby Hyper predicate paths.

Current Status

Implemented today:

• Real constants, zero-status helpers, and elementary-function wrappers;
• Complex arithmetic and integer powers;
• Vector2, Vector3, Vector4, shared-scale views, homogeneous facts, dot products, normalization, and checked/abort-aware operations;
• exact 2D algebra helpers and facts for displacement, wedge/dot, product sums, and orientation expressions;
• Matrix3, Matrix4, determinant, inverse, transpose, multiplication, powers, checked paths, transform handles, prepared matrix/right-divisor handles, and structural facts;
• RealFacts, sign/magnitude facts, abort signals, arbitrary support, regression sentinels, and benchmark hooks.

Fallible operations return BlasResult<T> or checked variants. Checked operations reject definite zero and unknown-zero divisors or pivots.

Installation

[dependencies]
hyperlattice = "0.5.0"

For sibling checkouts:

[dependencies]
hyperlattice = { path = "../hyperlattice" }

Feature summary:

• arbitrary: implements arbitrary::Arbitrary for lattice-owned types.
• hyperreal-dispatch-trace: enables scalar dispatch tracing during benchmarks.

Usage

use hyperlattice::{Matrix3, Real, Vector3};

fn r(value: i32) -> Real { value.into() }

let v = Vector3::new([r(3), r(4), r(0)]);
assert_eq!(v.dot(&v), r(25));

let m = Matrix3::identity();
assert_eq!(m.clone() * m.inverse().unwrap(), Matrix3::identity());

Development

Useful local checks:

cargo test
cargo bench --bench mathbench
cargo bench --bench regression_sentinels

References

Bareiss, Erwin H. "Sylvester's Identity and Multistep Integer-Preserving Gaussian Elimination." Mathematics of Computation, vol. 22, no. 103, 1968, pp. 565-578.

Yap, Chee K. "Towards Exact Geometric Computation." Computational Geometry, vol. 7, nos. 1-2, 1997, pp. 3-23.

Source Layout

• src/scalar.rs: Real constants, functions, facts, and zero status
• src/complex.rs: Complex
• src/algebra2.rs: exact 2D expressions and displacement facts
• src/vector.rs: Vector2, Vector2Facts, Vector3, and Vector4
• src/matrix: Matrix3, Matrix4, and transform handles
• src/kernels.rs: crate-private Real product-sum and structural helpers