mixle.engines.affine module

Affine arithmetic – tighter error tracing than intervals, and the precision-allocation dial.

An AffineForm represents a quantity as a center plus a linear combination of shared noise symbols x0 + sum_i x_i * eps_i with eps_i in [-1, 1]. Unlike interval arithmetic, correlated error cancels: (a + b) - a recovers b exactly because a’s symbols subtract out, where an interval would double the width. That tightness is what lets a precision-allocation pass avoid over-spending bits.

The dial: evaluating an operation at dtype d injects a fresh roundoff symbol of radius u(d) * |result| (u = unit roundoff). The affine radius at the root is the certified error bound; a subtraction at a cancellation point makes it grow – the escalation signal. Walk leaves->root choosing the lowest-cost dtype whose injected radius keeps the root bound under target.

This is the tighter estimate; the fully IEEE-sound enclosure is mixle.engines.error_tracing (interval, outward-rounded). The radius here is reported with one outward ULP of slop.

unit_roundoff(dtype)[source]

Unit roundoff for a dtype name / numpy dtype ('dd'/'qd' for extended precision).

Parameters:

dtype (Any)

Return type:

float

class AffineForm(center, terms=None)[source]

Bases: object

center + sum_i coeff_i * eps_i over shared noise symbols eps_i in [-1, 1].

Parameters:

  • center (Any)

  • terms (dict[int, np.ndarray] | None)

classmethod constant(x)[source]

Create an affine form with no uncertainty terms.

Parameters:

x (Any)

Return type:

AffineForm

classmethod uncertain(x, radius=0.0)[source]

An input known only to within +/- radius – one fresh noise symbol of that radius.

Parameters:
Return type:

AffineForm

radius()[source]

Half-width = sum_i |coeff_i| (one outward ULP of slop for the f64 summation).

Return type:

ndarray

max_radius()[source]

Return the largest interval half-width across entries.

Return type:

float

to_interval()[source]

Convert the affine form to an interval enclosure.

Return type:

Any

contains(value)[source]

Return a boolean mask for values contained in the affine enclosure.

Parameters:

value (Any)

Return type:

ndarray

inject_roundoff(dtype)[source]

Add the roundoff a dtype-dtype evaluation introduces: a fresh symbol of u*|center|.

Parameters:

dtype (Any)

Return type:

AffineForm

class PrecisionResult(dtype, estimated_abs_error, target_abs_error, status='heuristic_fit')[source]

Bases: object

Result of allocate_precision(): a dtype recommendation from an endpoint-magnitude heuristic. This is not an IEEE error certificate.

status is one of:

  • "heuristic_fit": the endpoint estimate is no larger than the target.

  • "heuristic_insufficient": even the modeled qd estimate exceeds the target.

Neither status certifies intermediate magnitude, conditioning, reduction order, underflow, or overflow. Use an operation graph with propagated intervals for a sound certificate.

Parameters:
dtype

the selected dtype name (best-effort, uncertified, when status == "insufficient").

Type:

str

estimated_abs_error

op_count * unit_roundoff(dtype) * center_magnitude – the estimated absolute roundoff dtype accumulates (an analytic estimate, not a measurement).

Type:

float

target_abs_error

the caller’s requested target, echoed back for convenience.

Type:

float

status

see above; always explicitly heuristic.

Type:

str

property heuristic_met_target: bool

Whether the explicitly non-certifying endpoint estimate fits the requested target.

property met_target: bool

this result does not carry enough evidence to certify the target.

Type:

Always false

allocate_precision(center_magnitude, op_count, target_abs_error)[source]

Suggest the lowest-cost dtype whose endpoint-magnitude error heuristic is under target.

The estimate op_count*u*center_magnitude does not observe intermediate values or an operation graph and is therefore only a planning heuristic. It must never be used as an accuracy certificate.

Raises ValueError unless center_magnitude and op_count are both finite and nonnegative and target_abs_error is finite and strictly positive. Before this validation existed, a negative op_count flipped the estimated error negative, which spuriously satisfies every dtype’s budget comparison and misselects float16 – the least precise dtype – regardless of how large the magnitude or how tight the target; a negative target_abs_error made every dtype’s comparison fail and fell through to silently returning qd even though no dtype can certify a negative bound (impossible by definition); and a NaN/Inf value anywhere in the formula rode comparison-with-NaN-is-always-False (or Inf’s unpredictable propagation) into whatever the fallthrough dtype happened to be, not a principled decision.

Parameters:
Return type:

PrecisionResult