Crate hyperlattice

Expand description

Real-centered linear algebra primitives backed by exact hyperreal arithmetic.

hyperlattice exposes complex numbers, 2D/3D/4D vectors, and 3x3/4x4 matrices whose coordinate and scalar type is Real. Primitive floating-point values are supported only at API edges: finite f32/f64 inputs are lifted through checked Real constructors, and Real::to_f64_lossy provides a named lossy export for rendering, IO, and other external libraries.

Most arithmetic that can fail returns BlasResult. Checked APIs use ZeroStatus and reject both definite zero and unknown-zero divisors, returning Problem::UnknownZero for the latter.

Exactness is carried as conservative structure, not by eagerly canonicalizing every coordinate after every vector or matrix operation. Following Yap’s exact geometric computation model, lattice-owned facts such as sparsity, shared scales, determinant schedules, and transform kinds are non-certifying scheduling metadata until an exact Real or predicate route consumes them. See Yap, “Towards Exact Geometric Computation,” Computational Geometry, 1997, pp. 3-23.

§Examples

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

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

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

let identity = Matrix3::identity();
assert_eq!(identity * v.clone(), v);

Structs§

Complex: Complex scalar with real and imaginary components.
Displacement2Facts: Cheap structural facts known about a 2D displacement.
Matrix3: Three-by-three row-major matrix.
Matrix4: Four-by-four row-major matrix.
Matrix3StructuralFacts: Public structural facts for a Matrix3.
Matrix4StructuralFacts: Public structural facts for a Matrix4.
MatrixPreparedCacheState: Public cache-state summary for prepared matrix handles.
Orient2Facts: Cheap structural facts for a 2D orientation determinant.
PreparedMatrix3: Prepared handle for repeated use of a borrowed Matrix3.
PreparedMatrix4: Prepared handle for repeated use of a borrowed Matrix4.
PreparedRightDivisor3: Cached structural and exact-structure metadata for repeated right-division by the same 3×3 divisor.
PreparedRightDivisor4: Cached structural and exact-structure metadata for repeated right-division by the same 4×4 divisor.
ProductSum2Facts: Cheap zero facts for a short sum of pairwise products.
ProductTerm2Facts: Cheap zero facts for one pairwise product left * right.
Rational: Ratio of two integers
Real: (More) Real numbers
RealDomainFacts: Domain facts for common unary functions.
RealFacts: Conservative public facts about a real value.
RealMagnitudeBits: A known most-significant binary digit for a nonzero value.
RealSymbolicDependencyMask: Opaque bit mask of symbolic dependencies visible in a Real.
SharedScaleVec: Owned vector coordinates certified to share one exact rational scale.
Vector2: Two-dimensional vector.
Vector3: Three-dimensional vector.
Vector4: Four-dimensional vector.
Vector2Facts: Cheap structural facts known for a Vector2.
Vector3Facts: Cheap structural facts known for a Vector3.
Vector4Facts: Cheap structural facts known for a Vector4.
VectorSharedScaleFacts: Conservative fact packet for a shared-scale vector object.
VectorSharedScaleView: Borrowed view of vector coordinates that share an exact rational scale.

Enums§

Axis2: Coordinate axis in a 2D vector.
Matrix3TransformKind: Conservative homogeneous 2D transform kind for a Matrix3.
Matrix4TransformKind: Conservative homogeneous 3D transform kind for a Matrix4.
MatrixDeterminantScheduleHint: Advisory determinant schedule selected from retained matrix facts.
Problem: Problems when either parsing or attempting Arithmetic with Real numbers or when trying to make or convert to a Rational.
RationalStorageClass: Coarse exact-rational storage cost bucket.
RealDomainStatus: Conservative domain status for common real-valued functions.
RealExactSetDenominatorKind: Coarse denominator class for an exact borrowed set with a shared scale.
RealExactSetDyadicExponentClass: Coarse class for the largest dyadic denominator exponent in a borrowed set.
RealExactSetSignPattern: Conservative sign pattern for a borrowed set of Real values.
RealExpressionDegree: Coarse bounded expression degree for structural dispatch.
RealSign: Exact sign knowledge exposed by structural inspection.
RealZeroOneMinusOneStatus: Cheap exact classification for signed unit and zero values.
SignedAxis2: Signed 2D basis axis certified by vector structural facts.
SignedAxis4: A signed 4D basis axis used by caller-certified signed-permutation matrices.
Vector4HomogeneousKind: Exact structural classification of a 4D homogeneous coordinate.
ZeroStatus: Whether structural inspection can prove zero or nonzero status.

Functions§

acos: Returns the inverse cosine of value.
acos_with_abort: Returns the inverse cosine after attaching an abort signal.
acosh: Returns the inverse hyperbolic cosine of value.
acosh_with_abort: Returns the inverse hyperbolic cosine after attaching an abort signal.
asin: Returns the inverse sine of value.
asin_with_abort: Returns the inverse sine after attaching an abort signal.
asinh: Returns the inverse hyperbolic sine of value.
asinh_with_abort: Returns the inverse hyperbolic sine after attaching an abort signal.
atan: Returns the inverse tangent of value.
atan_with_abort: Returns the inverse tangent after attaching an abort signal.
atanh: Returns the inverse hyperbolic tangent of value.
atanh_with_abort: Returns the inverse hyperbolic tangent after attaching an abort signal.
cos: Returns the cosine of value.
cosh: Returns the hyperbolic cosine of value.
displacement2: Returns the 2D displacement vector to - from as [dx, dy].
displacement2_facts: Return structural facts about the 2D displacement to - from.
dot2: Returns the 2D dot product left.x * right.x + left.y * right.y.
e: Returns Euler’s number.
exp: Returns e raised to value.
i: Returns the imaginary unit as a complex scalar.
ln: Returns the natural logarithm of value.
log10: Returns the base-10 logarithm of value.
log10_with_abort: Returns the base-10 logarithm after attaching an abort signal.
one: Returns the multiplicative identity.
orient2_expr: Builds the exact scalar expression for the orientation determinant of points a, b, and c.
orient2_expr_facts: Return structural facts for the orientation determinant of a, b, c.
pi: Returns pi.
positive_product_sum2: Returns a short positive sum of pairwise products.
pow: Raises base to a scalar exponent.
powi: Raises base to an integer exponent using exponentiation by squaring.
product_sum2_facts: Return structural zero facts for a short sum of pairwise products.
product_term2_facts: Return structural zero facts for one pairwise product term.
reciprocal: Returns the multiplicative inverse of value.
reciprocal_checked: Returns the multiplicative inverse after rejecting zero and unknown-zero values.
reciprocal_checked_with_abort: Returns the checked multiplicative inverse after attaching an abort signal.
reciprocal_ref: Returns the multiplicative inverse of value without consuming it.
reciprocal_ref_checked: Returns the checked multiplicative inverse without consuming value.
signed_product_sum2: Returns a short signed sum of pairwise products.
sin: Returns the sine of value.
sinh: Returns the hyperbolic sine of value.
sqrt: Returns the principal square root of value.
squared_distance2: Returns the squared 2D distance between two points.
squared_norm2: Returns the squared 2D norm x * x + y * y.
tan: Returns the tangent of value.
tanh: Returns the hyperbolic tangent of value.
tau: Returns tau, equal to 2 * pi.
wedge2: Returns the 2D exterior product left.x * right.y - left.y * right.x.
zero: Returns the additive identity.
zero_status: Classifies a real value as zero, non-zero, or unknown.
zero_status_with_abort: Classifies a real value after attaching an abort signal.

Type Aliases§

AbortSignal: Shared cancellation signal used by abort-aware APIs.
BlasResult: Result type used by fallible operations in this crate.
CheckedBlasResult: Result type used by APIs that reject unknown-zero conditions.
ExactRealSetFacts: Exact-rational structure shared by a fixed set of Real values.