Crate arris_math 

Numeric foundation of the Arris kernel: points, vectors and unit vectors over nalgebra, frames, axes and rigid motions, intervals, exact orientation predicates over robust, polynomial and interval-guarded root finding, and Precision, the model-wide tolerance configuration.

Guarantees: f64 throughout, no allocation in evaluation, no panic on any finite input, and no numeric literal standing in for a tolerance — every tolerance is a Precision field, a Tolerance derived from it, or a named constant with a comment (.agents/rules/kernel.md). Depends on nothing in the workspace.

The point and vector types are nalgebra’s by alias and nalgebra is re-exported (docs/adr/0001-nalgebra-types-by-alias.md), so a caller reaches every operator and solver nalgebra has and a nalgebra major bump is an Arris API change.

Re-exports

pub use nalgebra;

Modules

predicates

Exact 2D orientation and in-circle predicates over robust.

roots

Real roots of polynomials of degree at most four, with multiplicity, and a Newton iteration that never leaves its bracket.

Structs

Aabb

The axis-aligned box around a set of points: min ≤ max on every axis, both finite. A box is never empty; an empty point set has no box.

Axis

A point and a unit direction. A plain value, never a handle: a cylinder is built from an Axis and numbers, and only the result lives in the model. The direction is unit by construction — Axis::new normalises — and that is the only invariant it carries.

Control

How a caller stops an operation: a poll, a budget of steps, both or neither. Every operation on a model, and every long query beside one, takes one last; Control::NONE is what a caller that does not care passes.

Frame

A right-handed orthonormal frame: an origin and axes x, y, z with x × y = z, each unit to within rounding, whatever the constructor was given. Every analytic surface and curve is placed by one, so a transform is a frame change and nothing else (docs/DATA-MODEL.md §Conventions).

Frame2

An orthonormal frame in a surface’s (u, v) plane, of either handedness. A pcurve placed by a left-handed Frame2 is traversed clockwise in (u, v) — the case of a circle shared by a cap and a wall whose normal opposes the circle’s Z (docs/DATA-MODEL.md §Pcurves).

Interrupted

An operation that was stopped, by the caller and not by its input. The model is as it was before the call.

Interval

A closed interval [lo, hi] with lo ≤ hi, neither end NaN. Either end may be infinite: a line’s domain is Interval::REAL. An interval may be longer than a curve’s period — an edge range on a periodic curve may cross the period (docs/DATA-MODEL.md §Topology).

Isometry

A rigid motion: a rotation followed by a translation, p ↦ R p + t. Lengths and angles are preserved, so a Frame moved by one is still a frame and geometry moved by one is the same geometry in another place (docs/DATA-MODEL.md §Conventions: a transform is a frame change).

Meter

The counter an algorithm ticks: a Control and the steps taken.

Precision

The tolerance configuration of one model, set when the model is created (docs/DATA-MODEL.md §Tolerances).

Reflection

Reflection in the plane through origin with unit normal: p ↦ p − 2((p − o)·n) n. Lengths and angles are preserved and handedness is reversed, which is why it is a type of its own and not an crate::Isometry, whose every value is proper (ADR-0031).

Tolerance

What a geometric algorithm needs to decide “the same” and “parallel”: a length and an angle. Derived from the model’s Precision by Precision::tolerance or from an entity’s own tolerance by the operation that owns it — never a literal in an algorithm (docs/DATA-MODEL.md §Tolerances).

Enums

FrameError

Why an origin and some directions are not a frame.

Handedness

Which way a Frame2’s y turns from its x.

IntervalError

Why two numbers are not an Interval.

ReflectionError

Why a point and a direction are not a mirror plane.

Stop

What stopped an operation.

Constants

HEAL_GAP_FRACTION

The healing ceiling: the largest gap, as a fraction of the part’s size (the same ball READ_GAP_FRACTION is of), that a STEP read heals by growing the tolerance of the entity it lies at (ADR-0058). A gap past it is still a refusal.

READ_GAP_FRACTION

The widest gap a file’s entities may leave that a read closes by a tolerance, as a fraction of the part’s size — the diameter of the ball holding its vertices and edges (ADR-0025 §4). A vertex or an edge whose measured gap is above it, or above Precision::max_tolerance, is refused as a gap: closing it would be sewing, which is healing, and a solid grown to cover it would be a wrong one.

RELATIVE_ROUNDING

Relative rounding slack: a magnitude at or below this fraction of its natural scale is rounding noise, not a value. Eight ulps — what a handful of multiplications and one trigonometric evaluation leave behind, and orders of magnitude below any model tolerance. It is not a geometric tolerance and never decides whether two things are the same; it decides whether a computed quantity is zero in floating point: the radius of a sphere’s parallel at the pole, cos(π/2) evaluated in f64, is 6e-17, not 0.

SECTION_GROWTH_LIMIT

The most a read edge’s gap is raised for the angle its two faces cross at (ADR-0059): an edge lying d off one face and on the other is d / sin θ from where faces crossing at θ meet, and its tolerance is raised to that where 1 / sin θ is at most this — faces crossing at 30° or more. Under it the faces are near tangent, where they meet is ill-conditioned (a G1 blend’s faces meet anywhere along a band), and the edge keeps its gap from each surface.

Functions

is_negligible

|x| ≤ RELATIVE_ROUNDING · |scale|: x is zero to rounding at scale. A zero scale makes only an exact zero negligible.

period_end

The end of one whole period from lo: lo + period, stepped down to the representable value below when that sum rounds up, so that end - lo <= period holds exactly. A closed edge spans one period and no more (docs/DATA-MODEL.md §Invariants, E1), and for a lo that is not a small multiple of the period the sum can round to one unit in the last place too far; this is the range’s construction, not a tolerance. A non-finite argument, or a period that is not positive, comes back as lo + period.

shift_into_range

t moved by whole periods into range when it can be; a parameter of a non-periodic entity (period of None) only if it already lies in range. The shift is the smallest one that brings t to or above range.lo(), so the answer is the first translate at or after the start, and None when that overshoots range.hi().

shift_nearest

The whole-period shift that moves x nearest to target: k·period with k the integer nearest (target − x) / period (halves away from zero). Adding it to x is the translate of x that lies closest to target; it is 0.0 when x already is.

shift_nearest_uv

d rounded to whole periods in each periodic parameter of a surface (Surface::period), zero in the others: the translate in (u, v) that carries a point by d back to the nearest copy of itself.

wrap_angle

An angle moved into [0, 2π): what a periodic curve’s or surface’s parameter is reported in (docs/DATA-MODEL.md §Conventions). A negative angle whose sum with 2π rounds up to 2π becomes 0 — the same point on the circle, and inside the domain. A non-finite angle comes back unchanged.

wrap_into

t moved by whole periods into [lo, lo + period). A value already in that range comes back unchanged, bit for bit (no add-and-subtract of lo), and a result that rounds up to lo + period becomes lo — the same point on the circle, and inside the range. A non-finite t comes back unchanged.

wrap_offset

A difference moved into [−period / 2, period / 2), by wrapping x + period / 2 into [0, period) and moving back. Unlike wrap_signed it can return a value one rounding from x when x is already in range, because of the add and subtract of the half period; callers that were written against it keep that rounding.

wrap_signed

A difference moved into [−period / 2, period / 2]: d less the whole periods nearest it. A half period goes to whichever end the rounding of shift_nearest sends it, so the ends are not a promise.

Type Aliases

Matrix3

A 3x3 matrix, column-major: a rotation, or a tensor such as the inertia of a body. nalgebra::Matrix3<f64> (ADR-0001).

Point2

A position in a surface’s (u, v) plane. nalgebra::Point2<f64> (ADR-0001).

Point3

A position in 3D. nalgebra::Point3<f64> (ADR-0001).

Poll

The poll a caller supplies: true asks the running operation to stop. Sync because the parallel passes poll from several threads.

UnitVec2

A direction in the (u, v) plane: a Vec2 of unit length. nalgebra::Unit<Vector2<f64>> (ADR-0001).

UnitVec3

A direction in 3D: a Vec3 of unit length, guaranteed by construction. nalgebra::Unit<Vector3<f64>> (ADR-0001).

Vec2

A displacement in the (u, v) plane. nalgebra::Vector2<f64> (ADR-0001).

Vec3

A displacement or direction in 3D, of any length. nalgebra::Vector3<f64> (ADR-0001).