hyperlattice

hyperlattice provides small fixed-size linear algebra over hyperreal::Real: complex numbers, 2D/3D/4D vectors, points, 3×3 and 4×4 matrices, affine and projective transforms, and reusable structural facts.

It is the carrier layer between Hyperreal scalars and geometry predicates. It does not try to replace a general BLAS package, classify geometry, or own mesh topology.

Why exact-aware linear algebra?

Small matrices and vectors appear at nearly every geometry branch point. Floating-point linear algebra can hide a singular pivot or turn a zero determinant into a small nonzero value. Fully expanding exact expressions, on the other hand, can do expensive work before a caller knows whether a zero mask, transform kind, or shared scale already answers the scheduling question.

Hyperlattice retains that object-level structure:

hyperreal::Real coordinates
           │
           ▼
 point / vector / matrix carriers
           │
   sparse support, zero masks,
   shared scales, transform kinds
           │
           ├──────────► exact algebra result
           └──────────► facts for Hyperlimit predicates

Facts are conservative scheduling evidence. A topology-changing decision still belongs to an exact or explicitly uncertain predicate.

Primary types

Rational, Real, and their principal structural types are re-exported from Hyperreal for convenience.

Quick start

Create a project and add the crate:

cargo new exact-linear-algebra
cd exact-linear-algebra
cargo add hyperlattice

Equivalent manifest entry:

[dependencies]
hyperlattice = "0.6.1"

Replace src/main.rs with:

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

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

fn main() -> hyperlattice::BlasResult<()> {
    let vector = Vector3::new([r(3), r(4), r(0)]);
    assert_eq!(vector.dot(&vector), r(25));
    assert_eq!(Real::sqrt(vector.dot(&vector))?, r(5));

    let identity = Matrix3::identity();
    assert_eq!(identity.clone() * vector.clone(), vector);
    assert_eq!(identity.inverse()?, Matrix3::identity());
    Ok(())
}

Run it with cargo run. The same source is checked in as examples/readme_quickstart.rs, compiled by the test suite, and compared with the README block.

API guide

Scalar and complex operations

Hyperreal owns scalar arithmetic, domain checks, and structural type names; Hyperlattice does not wrap or rename those APIs. Attach cancellation directly with Real::abort before invoking a scalar operation. The two structural checked reciprocal functions reject unknown-zero divisors without refinement, unlike Real::inverse, which may refine to establish a nonzero denominator.

Vectors

Vector4HomogeneousKind, Axis2, SignedAxis2, and SignedAxis4 describe common exact shapes without asking users to decode coordinate patterns.

Points and bounds

Point/vector arithmetic follows affine semantics: subtracting points yields a vector, while translating a point by a vector yields a point.

Exact 2D algebra

These functions construct exact expressions and facts. Hyperlimit owns the policy that turns an orientation expression into a certified classification.

Projective construction

Homogeneous results intentionally postpone division. to_affine_point is the checked boundary at which a nonzero homogeneous scale is required.

Matrices and transforms

Both matrix types provide new, zero, identity, transpose, determinant, inverse, inverse_checked, powi, checked scalar/matrix division, and structural_facts.

Specialized division and inverse methods have checked variants that reject unresolved divisors or pivots. General matrix operations provide inverse_checked_with_abort and div_matrix_checked_with_abort for cancellable refinement; structural zero queries do not need an abort-specific API.

Facts and cancellation

Point, vector, matrix, displacement, product, and orientation fact objects expose known-zero/nonzero/unknown masks and counts, sparse-support tests, shared-denominator and dyadic schedule tests, transform kinds, and determinant schedule hints. They are reusable metadata, not proof that an unresolved coordinate is zero.

Create an AbortSignal with Arc<AtomicBool> and pass it to *_with_abort methods when long exact refinement must be cancellable.

Features

Hyperlattice has no default features.

Guarantees and boundaries

• Native coordinates and matrix entries are Real; no primitive float is used as an internal algebra fallback.
• Finite f32/f64 imports preserve the exact represented binary value.
• Lossy exports are named and return None if a coordinate cannot produce a finite primitive value.
• Checked division, normalization, and inversion reject definite-zero and unresolved-zero divisors or pivots.
• Structural facts are conservative and remain attached to their owning point, vector, matrix, or projective object.
• Hyperlattice constructs expressions and carriers. Hyperlimit owns predicate escalation and classifications; geometry crates own curves and topology.

Validation and performance tooling

The deterministic representation suite constructs all 22 optimized finite Real certificate classes, verifies all 8 public structural kinds, crosses all ordered class pairs, and runs every class through scalar, complex, vector, point, matrix, and projective carriers. It is repeated under Hyperreal's four primitive-cache layouts with:

scripts/representation_coverage.sh

The matching fuzz target retains that complete finite corpus on every execution, rotates cross-representation pairs from input bytes, and grows additional bounded opaque expression DAGs:

cargo check --manifest-path fuzz/Cargo.toml --bins
cargo +nightly fuzz run hyperreal_representations --fuzz-dir fuzz -- -max_total_time=30

scripts/coverage.sh builds isolated no-feature and all-feature coverage, executes benchmark fixtures without rewriting checked-in reports, and writes an annotated text report plus HTML under target/coverage. The allocation profile reports calls, bytes, reallocations, and peak live memory for four carrier workloads across every certificate:

scripts/coverage.sh
scripts/allocation_profile.sh

The Criterion real_representations group measures the same 22-class carrier sweep. The broader mathbench compares equivalent scalar, complex, vector, and matrix workloads against Numerica 128, GMP/MPFR 128 through Rug, and Symbolica; methodology and retained results live in PERFORMANCE.md.

Ecosystem and further documentation

• Hyperreal supplies exact-aware scalars and scalar certificates.
• Hyperlimit supplies certified geometric predicates over these carriers.
• Hypercurve, Hypertri, and Hypermesh own higher geometry.

PERFORMANCE.md records benchmark methodology and retained optimization evidence. benchmarks.md is refreshed after either Criterion timing binary runs and includes every stored row, including competitive and regression-sentinel results. Regenerate it without measuring with cargo run --example write_benchmarks_md. Generate the complete signatures and trait implementations with cargo doc --open.

References

• Bareiss, Erwin H. “Sylvester's Identity and Multistep Integer-Preserving Gaussian Elimination.” Mathematics of Computation, vol. 22, no. 103, 1968, pp. 565–578. doi:10.1090/S0025-5718-1968-0226829-0.
• Berkowitz, Stuart J. “On Computing the Determinant in Small Parallel Time Using a Small Number of Processors.” Information Processing Letters, vol. 18, no. 3, 1984, pp. 147–150. doi:10.1016/0020-0190(84)90018-8.
• Gustavson, Fred G. “Two Fast Algorithms for Sparse Matrices: Multiplication and Permuted Transposition.” ACM Transactions on Mathematical Software, vol. 4, no. 3, 1978, pp. 250–269. doi:10.1145/355791.355796.
• Hou, Shui-Hung. “A Simple Proof of the Leverrier-Faddeev Characteristic Polynomial Algorithm.” SIAM Review, vol. 40, no. 3, 1998, pp. 706–709. doi:10.1137/S003614459732076X.
• Yap, Chee K. “Towards Exact Geometric Computation.” Computational Geometry, vol. 7, 1997, pp. 3–23. doi:10.1016/0925-7721(95)00040-2.

Bareiss and Berkowitz motivate exact determinant schedules; Gustavson motivates sparse-support dispatch; Hou covers a small-matrix characteristic-polynomial route; Yap establishes the exact-computation boundary used by downstream geometry.

Acknowledgements

Hyperlattice is developed by Timothy Schmidt as part of the Hyper ecosystem. The repository history also records contributions from TimTheBig. Its scalar model and many exact reducers are built on Hyperreal.

License and contributing

Hyperlattice is distributed under the MIT License; see LICENSE. Changes should preserve point/vector distinctions, explicit lossy boundaries, and conservative structural facts. Before submitting a change, run:

cargo fmt --all -- --check
cargo test --all-targets --all-features
cargo clippy --all-targets --all-features -- -D warnings
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features