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. It owns the fixed-size vector, matrix, point, shared-scale, and homogeneous projective carriers that predicate and geometry crates reuse.

• hyperreal: exact rational, symbolic, and computable scalar arithmetic.
• hyperlimit: exact predicates, escalation policy, and predicate provenance over lattice-owned objects.
• hypercurve: planar curves, contours, regions, offsets, and boolean-boundary work.
• hypertri: polygon triangulation, Delaunay, constrained Delaunay, and D-dimensional topology.
• hypermesh: 3D mesh validation, topology, and exact-aware boolean preflight.
• hyperbrep: retained BREP topology, planar surfaces, trim evidence, tessellation manifests, and mesh handoff reports.
• hypersdf: signed-distance and implicit-field carriers with exact-aware sampling, classification, mesh, and voxel handoffs.
• hypersolve: symbolic residuals, solver preparation, interval/root certification, and candidate replay.
• hyperpath: routing, CAM, PCB path, provenance, and path-domain residual builders.
• hypervoxel: exact-aware voxel frames, sparse-grid facts, and storage/adapter manifests.
• hyperphysics: exact-aware materials, shapes, mass properties, contact, fields, and simulation handoff reports.
• hypercircuit: circuit MNA carriers, exact residual replay, nonlinear-device reports, and electrothermal coupling.
• hyperparts: source-attributed part, interface, process, and compatibility facts.
• hyperpack: exact-aware packing models, proposal reports, and feasibility replay.
• hyperevolution: exact-aware search, fitness, archive, and replay-policy carriers.
• hyperdrc: PCB design-readiness checks and manufacturing package evidence.

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.
• Point2, Point3, Point2Facts, Point3Facts, PointSharedScaleView, and PointSharedScaleFacts keep point coordinates separate from vectors while preserving sparse support, shared-denominator schedules, known-zero masks, and one-hot facts.
• ProjectivePlane3, Plane3Coefficients, HomogeneousPoint3, HomogeneousLine3, intersect_two_planes, intersect_three_planes, and intersect_homogeneous_line_plane keep exact 3D plane intersections in homogeneous form so affine division is delayed until a caller proves the point is finite.
• 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. Point and projective carriers live here rather than in hyperlimit so predicate policy can classify them without becoming the storage owner.

Numerical Explosion

hyperlattice combats numerical explosion by keeping object-level facts beside exact scalars. Zero masks, one-hot coordinates, determinant schedules, shared scales, homogeneous facts, and prepared matrix caches let callers avoid expanding matrix, projective, and transform expressions until an exact predicate or solve actually needs the scalar terms.

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;
• Point2, Point3, point fact packets, shared-scale point views, sparse point facts, and point/vector conversions;
• homogeneous 3D points, Pluecker lines, projective plane coefficients, exact two-plane and three-plane intersections, and line/plane homogeneous intersections;
• 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::{intersect_three_planes, Matrix3, Point3, ProjectivePlane3, 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());

let x = ProjectivePlane3::new(Point3::new(r(1), r(0), r(0)), r(-2));
let y = ProjectivePlane3::new(Point3::new(r(0), r(1), r(0)), r(-3));
let z = ProjectivePlane3::new(Point3::new(r(0), r(0), r(1)), r(-4));
let p = intersect_three_planes(&x, &y, &z);
assert_eq!(p.to_affine_point().unwrap(), Point3::new(r(2), r(3), r(4)));

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/point.rs: Point2, Point3, point facts, and shared-scale point views
• src/projective.rs: homogeneous points, Pluecker lines, and plane intersections
• src/matrix: Matrix3, Matrix4, and transform handles
• src/kernels.rs: crate-private Real product-sum and structural helpers