mixle.engines.error_tracing module

Sound error tracing via interval arithmetic – the “logic” that lets mixle preserve accuracy with minimal compute.

An Interval carries [lo, hi] enclosing a true value. Every operation rounds the bounds outward (one ULP via numpy.nextafter()), so the enclosure provably contains the exact result despite float64 round-off – the interval certifies the numerical error rather than hoping it is small. The width is a guaranteed error bound; a precision-allocation pass reads it to pick the cheapest format that keeps the width under a target (pair with mixle.engines.formats.min_float_mantissa_bits()).

Interval arithmetic is sound but pessimistic (it ignores correlations between operands); affine arithmetic tightens it and is the natural follow-up. This is the vectorized, dependency-free core.

class Interval(lo, hi)[source]

Bases: object

A guaranteed enclosure [lo, hi] of a value (scalar or numpy array), outward-rounded.

Parameters:

  • lo (Any)

  • hi (Any)

hi
lo
classmethod exact(x)[source]

A degenerate interval [x, x] for an exactly-represented value.

Parameters:

x (Any)

Return type:

Interval

classmethod from_quantized(original, fmt)[source]

Enclose original given only its round-trip through fmt – i.e. bound the value a consumer of the quantized data is uncertain about, using the format’s relative-error bound.

Parameters:
Return type:

Interval

width()[source]

The guaranteed error bound: hi - lo (outward-rounded).

Return type:

ndarray

max_width()[source]
Return type:

float

midpoint()[source]
Return type:

ndarray

contains(value)[source]
Parameters:

value (Any)

Return type:

ndarray

sum_error_bound(x)[source]

Certified bound on the float64 error of sum(x) – vectorized, no per-element loop.

The standard a-priori bound |fl(sum) - sum| <= gamma_{n-1} * sum|x_i| with gamma_k = k*u / (1 - k*u) and u = 2**-53. It is sound for any summation order. A bound that is large relative to |sum x| means the sum is ill-conditioned (cancellation) and warrants the double-double mixle.engines.extended.dd_sum(); a tight one means float64 already suffices and no extra compute is justified – the logic that spends precision only where it is needed.

Parameters:

x (Any)

Return type:

float

sum_enclosure(x)[source]

Sound interval enclosing the true sum(x): [fl_sum - bound, fl_sum + bound], outward-rounded.

Parameters:

x (Any)

Return type:

Interval

float64_sum_is_accurate(x, target_rel_error=1e-12)[source]

Whether a float64 sum of x is already accurate to target_rel_error (else use dd_sum).

Reads the certified bound relative to the magnitude of the result – precision allocation in one call.

Parameters:
Return type:

bool