mixle.engines.spectrum module

The precision spectrum’s front door: route a computation to the lowest-cost accurate backend.

Ties the spectrum together – native float64, double-double (mixle.engines.extended), and the MPFR tail (mixle.engines.highprec) – behind one call that reads the certified error bound (mixle.engines.error_tracing) and escalates only as far as the accuracy budget demands. This is ‘use logic to preserve numerical accuracy with minimal compute’ as an actual API: a well-conditioned sum stays in fast float64, a cancelling one steps up to vectorized double-double, and only a catastrophically ill-conditioned one pays for arbitrary precision.

class SumResult(value, backend, rel_error_bound, target_rel_error, status='ok')[source]

Bases: object

Result of accurate_sum(): the summed value plus a certificate of the accuracy actually achieved – so a caller can verify the target was met rather than trust the call implicitly.

status is one of:

  • "ok": rel_error_bound is a certified bound <= target_rel_error – backend actually met the caller’s target.

  • "insufficient": no backend available in this process could certify the target – double-double was proven insufficient and either arbitrary precision is unavailable at all, or even _MAX_MPFR_BITS is not enough. value/backend still carry the best effort found (the highest-precision backend actually tried), for diagnostics only – callers that require the accuracy guarantee must treat this as a failure and not use value.

  • "overflow": the exact/high-precision result cannot be represented by this API’s float64 value field. No relative-error claim is issued.

Parameters:
value

the computed sum (best-effort, not certified, when status == "insufficient").

Type:

float

backend

which representation computed value – "float64", "dd", or "mpfr<bits>".

Type:

str

rel_error_bound

certified upper bound on value’s relative error (an analytic bound – the same quantity sum_certificate() reports for the plain float64 sum, not a measurement).

Type:

float

target_rel_error

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

Type:

float

status

see above.

Type:

str

property met_target: bool

True only when rel_error_bound is certified to meet target_rel_error.

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

Sum x to target_rel_error relative accuracy using the lowest-cost sufficient backend.

Returns a SumResult certifying the accuracy actually achieved. Escalates from float64 to double-double to arbitrary precision only when the certified error bound says the lower-cost backend cannot meet the budget – so the common well-conditioned case never leaves vectorized float64 – and fails closed (status="insufficient") rather than silently returning a value that does not meet target_rel_error when no backend available in this process can certify it.

Raises ValueError if target_rel_error is not a positive, finite number.

Parameters:
Return type:

SumResult

sum_certificate(x)[source]

Report the certified float64 summation error and the condition number, without choosing a backend.

Parameters:

x (Any)

Return type:

dict[str, float | str | bool]

cast(x, precision)[source]

Cast x onto the spectrum: a native dtype name, "dd"/"fp<bits>", or an integer bit width.

"dd", "fp128", and the integer 128 are the same request (DoubleDouble); "fp96" and the integer 96 are likewise the same request (both resolve to 96 total bits via _precision_bits()) and route to the identical representation via _cast_by_bits(), regardless of which spelling the caller used. A nonpositive bit width (e.g. "fp0", -5) raises ValueError rather than reaching format construction. Anything else (e.g. "float64", np.float32) is handed straight to numpy.dtype().

Returns a numpy array (native / simulated low-bit), a DoubleDouble, or an MPFR object array – see _cast_by_bits() for the exact tiering.

Parameters:
Return type:

Any