Arbitrary-precision numerical polynomials¶

These APIs provide rounded arithmetic, rigorous evaluation, and validated real and complex root covers. The examples show evaluation, enclosures, and root refinement; array users start with numerical coefficients. Numerical values use their own precision and enclosure rules; they do not extend the exact kernel codec.

Domains and operations¶

NumericDensePoly[D] stores ascending univariate coefficients. NumericSparsePoly[D] uses the existing monomials and orders. Both implement addition, subtraction, negation, multiplication, nonnegative powers, scalar multiplication/division, differentiation and evaluation. Dense evaluation also provides a simultaneous value/derivative operation. Sparse evaluation caches variable powers within the call. Scalar division requires a divisor that certainly excludes zero. numeric_divmod provides polynomial division with residual or family-enclosure certificates; see the toolkit reference.

Only finite coefficients and bounded enclosures are accepted. Constructors remove point zeros or singleton-zero balls, never coefficients that merely contain zero. degree_bound and certified_degree distinguish possible degree from a degree shared by the entire coefficient family. Public fields support certificate transport and inspection; callers must preserve container invariants.

Precision is never ambient. Scalar operations follow the supplied apn_mojo contexts, including rounding and traps. Operands retain their stored values. Dense convolution visits increasing left then right indices; Horner descends through coefficients; powers use binary powering. Sparse duplicate coefficients are accumulated stably in input order after monomial sorting and removal of certain-zero input terms. An intermediate zero is retained until its duplicate group ends, so subsequent additions still receive the prescribed rounding. A coefficient that needs no sparse arithmetic retains its original format. Integer derivative multipliers are converted under the context before multiplication. These are sequences of rounded operations, not a promise of one correctly rounded result for the entire polynomial calculation. No algebraic reassociation is applied.

Explicit conversion functions support all four domains. Exact ZZ/QQ/QQi conversion constructs balls directly from rational bounds. Modular polynomials, including zero polynomials, have no implicit numerical embedding. Conversion to a point uses apn_mojo’s public certainty predicate, preserving its signed-zero and rounding-status distinctions; otherwise it raises DOMAIN. Exact singleton rationals are rounded directly. This never silently substitutes a midpoint. Numerical domains do not implement the exact coefficient traits.

Enclosure certificates and accuracy¶

enclose_dense and enclose_sparse evaluate existing ZZ/QQ/QQi polynomials. enclose_numeric and enclose_numeric_sparse evaluate numerical families. The output domain is Ball or ComplexBall. Each result carries a deterministic trace of exact rational rectangles. Its value(budget) method returns an owned scalar. The checker reconstructs the evaluation graph from the original polynomial and assignments, checks every local rational bound, and checks the reported value. It performs no floating-point arithmetic or adaptive search.

Adaptive evaluation starts at initial_precision, doubles it, and caps the last attempt at max_precision. It rebuilds coefficient enclosures from the original exact coefficients and preserves argument uncertainty. SUCCESS means both coordinate widths are at most

2^-absolute_bits + 2^-relative_bits * lower_norm(region).

A zero exponent disables that term. lower_norm is a lower bound on the infinity norm throughout the rectangle, so relative accuracy is uniform over its values. Relative tolerance alone cannot establish a positive width at zero. A precision ceiling returns the last valid enclosure with an inconclusive outcome. check_numeric_accuracy checks its accuracy claim; the corresponding evaluation checker must also be called.

Real and complex roots¶

Real root entry points accept exact ZZ/QQ and real numerical coefficients. Counts are distinct real roots; repeated roots do not defeat either path.

Exact ZZ/QQ inputs (real_roots_exact) are isolated by Descartes' rule of signs on the squarefree part g = f / gcd(f, f'), and the result is a DescartesRootResult with a Descartes certificate: leaves partitioning (-2^k, 2^k) with recomputable Descartes bounds, the rational roots met at shared leaf ends, and a bracket for every other root, tightened by quadratic interval refinement until the requested widths hold. Brackets are open intervals with a sign change of g, so each root lies strictly inside; an exact rational root is reported as itself. max_subdivisions bounds isolation splits and refinement steps together; a result that runs out leaves unresolved leaves or wide brackets and reports SUBDIVISION_LIMIT. check_real_roots_exact recomputes gcd(f, f') and checks the certificate without searching.

Numerical inputs (real_roots_numeric) keep the cell cover. Finite Float coefficients and exact point balls denote exact stored rationals; such point inputs use one shared Sturm certificate and a bounded subdivision worklist. Real ball families use uniform image exclusion, endpoint signs, derivative bounds and interval Newton predicates. Their output includes excluded cells, forming an ordered cover of a checked global Cauchy interval. If two explicit endpoint coefficient choices have different exact global Sturm counts, the request returns INPUT_UNCERTAINTY immediately; equal counts do not establish a uniform claim. All counted roots are strictly inside their cells. There is no inferred multiplicity for a ball family; exact inputs attach multiplicities with real_root_multiplicities.

Complex entry points accept exact ZZ/QQ/QQi and every numerical domain. Each output rectangle has a zero-free boundary trace and an exact rational winding count, including multiplicity. The implementation translates coefficients around each boundary segment’s midpoint using rational interval arithmetic before evaluating its boundary. This reduces cancellation around repeated roots while enclosing the original family. Boundary segments are oriented counterclockwise and cover all four sides. The checker computes the winding of an exact representative's image polygon, validates every enclosure, and checks disjoint interiors and a count sum equal to the uniform degree. Shared rectangle edges are permitted because both boundaries are certified root-free.

Search is deterministic and bounded. Complex search bisects boundary segments and tries asymmetric spatial cuts at fractions 2/7, 3/7 and 4/7 along the longer axis. Each trial receives at most 32 + 8*degree boundary subdivisions, within the shared max_subdivisions allowance, leaving room for another contour. The initial global contour can use the remaining allowance. Precision retries occur when exact interval bounds show that additional bits may help. Failed contours never discard a previously counted region.

complete, accurate and isolated are separate claims. A complete cover can remain too wide or contain a multiple-root cluster. require_isolation=False permits counted clusters. Otherwise an inseparable repeated complex root returns an inconclusive result, retaining its checked cluster cover when available. The refine_real_roots_* and refine_complex_roots_* entry points check a previous cover against its original options, retain satisfactory regions, and continue with the new options. The refinement example shows how to keep the result and options together.

A nonzero constant has a successful empty root set. The zero polynomial raises DOMAIN. An uncertain leading coefficient returns UNCERTAIN_DEGREE, never a successful empty set. Exhausted subdivisions or unresolved contours return explicit outcomes. complete_only=True raises unless all requested claims succeed, including accuracy and isolation. It maps inherent unsupported input to UNSUPPORTED and search ceilings to LIMIT. Work-budget exhaustion always raises LIMIT; no partial result is returned for work exhaustion.

Root checkers verify complete covers, including valid complete cluster covers with an inconclusive accuracy/isolation outcome. They return false for incomplete analyses. Checkers validate counts and coverage independently of search; they do not certify that a resource ceiling was reached at precisely the reported step. All numerical checkers share the caller's work budget and preserve borrowed inputs on failure. Unrepresentable sizes raise CAPACITY.

The theory page states the proof obligations.

Example¶

"""Rounded arithmetic, rigorous evaluation, and validated real/complex roots."""
from apn_mojo import Rational, Float, FloatFormat, ArithmeticContext, Ball, BallContext
from polynomials import Budget, QQ, NoContext, DensePoly, FloatDomain, BallDomain, NumericDensePoly, NumericOptions, EnclosureStream, EnclosureStreamChecker, enclose_dense, check_enclose_dense, real_roots_exact, check_real_roots_exact, complex_roots_exact, check_complex_roots_exact


def main() raises:
    var budget = Budget()
    var context = ArithmeticContext(format=FloatFormat(128))
    var numerical = NumericDensePoly[FloatDomain].from_coefficients(0, [Float(1), Float(2), Float(1)], budget)
    print("Rounded value at 3:", numerical.evaluate(Float(3), context, budget))
    var exact = DensePoly[QQ].from_coefficients(0, NoContext(), [QQ(Rational(-2)), QQ(Rational(0)), QQ(Rational(1))], budget)
    var argument = Ball(Rational(3, 2), Rational(1, 16))
    var enclosure = enclose_dense[BallDomain](exact, argument, BallContext(128), budget)
    print("Enclosure checked:", check_enclose_dense[BallDomain](exact, argument, enclosure, budget))
    var stream = EnclosureStream[BallDomain].from_dense(exact, argument, BallContext(128), budget)
    var checker = EnclosureStreamChecker[BallDomain].from_dense(exact, argument, budget)
    while True:
        var bounds = stream.next(budget)
        if not bounds:
            break
        if not checker.accept(bounds.take(), budget):
            raise Error("streamed bound rejected")
    if not checker.finish(stream.finish(budget), budget):
        raise Error("streamed evaluation is incomplete or invalid")
    var options = NumericOptions(absolute_bits=4)
    var real = real_roots_exact(exact, options, budget, complete_only=True)
    print("Real root cover checked:", check_real_roots_exact(exact, real, options, budget))
    var complex = complex_roots_exact(exact, options, budget, complete_only=True)
    print("Complex roots:", len(complex.regions))
    print("Complex root cover checked:", check_complex_roots_exact(exact, complex, options, budget))

Rounded value at 3: 16.0
Enclosure checked: True
Real root cover checked: True
Complex roots: 2
Complex root cover checked: True

The next program evaluates \(x^2-2\) at \(x=1.5\) with 128-bit point arithmetic, then checks an enclosure of the exact polynomial over a small interval around 1.5:

"""Evaluate a polynomial with rounded arithmetic and check an interval enclosure."""
from std.testing import assert_equal, assert_true
from apn_mojo import Rational, Float, FloatFormat, ArithmeticContext, Ball, BallContext
from polynomials import Budget, QQ, NoContext, DensePoly, NumericDensePoly, FloatDomain, BallDomain, enclose_dense, check_enclose_dense


def main() raises:
    var work = Budget()
    var context = ArithmeticContext(format=FloatFormat(128))
    var polynomial = NumericDensePoly[FloatDomain].from_coefficients(0, [Float(-2), Float(0), Float(1)], work)
    var value = polynomial.evaluate(Float("1.5"), context, work)
    assert_equal(value, Float("0.25"))
    print("Rounded value at 1.5:", value)

    var exact = DensePoly[QQ].from_coefficients(0, NoContext(), [QQ(Rational(-2)), QQ(Rational(0)), QQ(Rational(1))], work)
    var argument = Ball(Rational(3, 2), Rational(1, 16))
    var enclosure = enclose_dense[BallDomain](exact, argument, BallContext(128), work)
    var verified = check_enclose_dense[BallDomain](exact, argument, enclosure, work)
    assert_true(verified)
    print("Enclosure checked:", verified)

Rounded value at 1.5: 0.25
Enclosure checked: True

refine_real_roots_exact takes the original polynomial, the previous result, and both sets of options. It checks the earlier certificate, keeps its leaves and tightens its brackets:

"""Refine a checked real-root result to a tighter absolute width."""
from std.testing import assert_equal, assert_true
from polynomials import Budget, QQ, NoContext, PolynomialRing, DensePoly, NumericOptions, real_roots_exact, refine_real_roots_exact, check_real_roots_exact, descartes_intervals


def main() raises:
    var work = Budget()
    var ring = PolynomialRing[QQ].create(["x"], NoContext(), work)
    var polynomial = DensePoly[QQ].from_sparse(ring.parse("x^2 - 2", work), work, variable=Int64(0))
    var coarse = NumericOptions(absolute_bits=2, max_subdivisions=64)
    var fine = NumericOptions(absolute_bits=8, max_subdivisions=256)
    var initial = real_roots_exact(polynomial, coarse, work, complete_only=True)
    var refined = refine_real_roots_exact(polynomial, initial, coarse, fine, work, complete_only=True)
    assert_true(check_real_roots_exact(polynomial, refined, fine, work))
    assert_true(refined.complete)
    assert_true(refined.accurate)
    assert_true(refined.isolated)
    var count = len(descartes_intervals(refined.certificate, work))
    assert_equal(count, 2)
    print("Distinct real roots:", count)
    print("Complete cover:", refined.complete)
    print("Requested width reached:", refined.accurate)

Distinct real roots: 2
Complete cover: True
Requested width reached: True

API¶

NumericDomain¶

trait NumericDomain

Associate a numerical scalar with its explicit arithmetic context.

Defined in src/polynomials/numeric_domains.mojo.

NumericDomain.Scalar¶

comptime Scalar: Copyable & Writable & Deinitable

The underlying apn_mojo scalar.

NumericDomain.Context¶

comptime Context: Copyable & Writable & Deinitable

The explicit output context.

FloatDomain¶

struct FloatDomain(NumericDomain)

Rounded arbitrary-precision real arithmetic.

Defined in src/polynomials/numeric_domains.mojo.

FloatDomain.Scalar¶

comptime Scalar = Float

The apn_mojo point value.

FloatDomain.Context¶

comptime Context = ArithmeticContext

Precision, rounding mode and traps.

ComplexDomain¶

struct ComplexDomain(NumericDomain)

Rounded arbitrary-precision complex arithmetic.

Defined in src/polynomials/numeric_domains.mojo.

ComplexDomain.Scalar¶

comptime Scalar = Complex

The apn_mojo complex point value.

ComplexDomain.Context¶

comptime Context = ComplexContext

Independent real and imaginary output settings.

BallDomain¶

struct BallDomain(NumericDomain)

Real interval arithmetic with rigorous enclosures.

Defined in src/polynomials/numeric_domains.mojo.

BallDomain.Scalar¶

comptime Scalar = Ball

The apn_mojo real enclosure.

BallDomain.Context¶

comptime Context = BallContext

Explicit midpoint and working precision.

ComplexBallDomain¶

struct ComplexBallDomain(NumericDomain)

Complex rectangular interval arithmetic with rigorous enclosures.

Defined in src/polynomials/numeric_domains.mojo.

ComplexBallDomain.Scalar¶

comptime Scalar = ComplexBall

The apn_mojo rectangular enclosure.

ComplexBallDomain.Context¶

comptime Context = BallContext

Explicit midpoint and working precision.

NumericDensePoly¶

struct NumericDensePoly[D: NumericDomain](Copyable, Movable)

A finite univariate numerical polynomial in ascending coefficient order.

Parameters.

• D: An apn_mojo numerical domain adapter.

Defined in src/polynomials/numeric_dense.mojo.

NumericDensePoly.__init__¶

def __init__(out self, variable: Int64 = 0)

Construct the zero polynomial.

Arguments.

• variable: The retained variable identifier.

NumericDensePoly.from_coefficients¶

@staticmethod
def from_coefficients(variable: Int64, var coefficients: List[Self.D.Scalar], mut budget: Budget) raises PolyError -> Self

Validate finite coefficients and remove certain trailing zeros.

Arguments.

• variable: The variable identifier.
• coefficients: The owned ascending coefficient vector.
• budget: The shared work allowance.

Returns. A numerical polynomial retaining uncertain coefficients.

Raises.

• PolyError: DOMAIN for nonfinite values, LIMIT or CAPACITY on work limits.

NumericDensePoly.degree_bound¶

def degree_bound(self) -> Int

Return the degree upper bound, or minus one for zero.

Returns. The largest stored power.

NumericDensePoly.certified_degree¶

def certified_degree(self, mut budget: Budget) raises PolyError -> Optional[Int]

Determine a degree shared by every represented polynomial.

Arguments.

• budget: The shared work allowance.

Returns. The degree, minus one for zero, or None for an uncertain leading term.

Raises.

• PolyError: DOMAIN for invalid coefficients or LIMIT on exhaustion.

NumericDensePoly.add¶

def add(self, other: Self, context: Self.D.Context, mut budget: Budget) raises PolyError -> Self

Add with the requested output precision.

Arguments.

• other: The polynomial in the same variable.
• context: Explicit output settings.
• budget: The shared work allowance.

Returns. The rounded or enclosing sum.

Raises.

• PolyError: DOMAIN for incompatible or invalid values, LIMIT or CAPACITY on work limits.

NumericDensePoly.sub¶

def sub(self, other: Self, context: Self.D.Context, mut budget: Budget) raises PolyError -> Self

Subtract with the requested output precision.

Arguments.

• other: The polynomial in the same variable.
• context: Explicit output settings.
• budget: The shared work allowance.

Returns. The rounded or enclosing difference.

Raises.

• PolyError: DOMAIN for incompatible or invalid values, LIMIT or CAPACITY on work limits.

NumericDensePoly.neg¶

def neg(self, context: Self.D.Context, mut budget: Budget) raises PolyError -> Self

Negate every coefficient at the requested precision.

Arguments.

• context: Explicit output settings.
• budget: The shared work allowance.

Returns. The rounded or enclosing negation.

Raises.

• PolyError: DOMAIN for invalid values, LIMIT or CAPACITY on work limits.

NumericDensePoly.mul¶

def mul(self, other: Self, context: Self.D.Context, mut budget: Budget) raises PolyError -> Self

Multiply by convolution in increasing left and right index order.

Arguments.

• other: The polynomial in the same variable.
• context: Explicit output settings.
• budget: The shared work allowance.

Returns. The rounded or enclosing product.

Raises.

• PolyError: DOMAIN for incompatible or invalid values, LIMIT or CAPACITY on work limits.

NumericDensePoly.scale¶

def scale(self, scalar: Self.D.Scalar, context: Self.D.Context, mut budget: Budget, *, divide: Bool = False) raises PolyError -> Self

Multiply coefficients by a scalar or divide by a certified nonzero scalar.

Arguments.

• scalar: The finite scalar or bounded enclosure.
• context: Explicit output settings.
• budget: The shared work allowance.
• divide: Select division, requiring the scalar to exclude zero.

Returns. The rounded or enclosing scaled polynomial.

Raises.

• PolyError: DOMAIN for invalid or uncertain divisors, LIMIT or CAPACITY on work limits.

NumericDensePoly.pow¶

def pow(self, exponent: UInt64, context: Self.D.Context, mut budget: Budget) raises PolyError -> Self

Compute a nonnegative power by deterministic binary powering.

Arguments.

• exponent: The nonnegative power.
• context: Explicit output settings.
• budget: The shared work allowance.

Returns. The rounded or enclosing power, including one for exponent zero.

Raises.

• PolyError: DOMAIN for invalid values, LIMIT or CAPACITY on work limits.

NumericDensePoly.derivative¶

def derivative(self, context: Self.D.Context, mut budget: Budget) raises PolyError -> Self

Differentiate with coefficient products rounded at the requested precision.

Arguments.

• context: Explicit output settings.
• budget: The shared work allowance.

Returns. The rounded or enclosing derivative.

Raises.

• PolyError: DOMAIN for invalid values, LIMIT or CAPACITY on work limits.

NumericDensePoly.evaluate¶

def evaluate(self, value: Self.D.Scalar, context: Self.D.Context, mut budget: Budget) raises PolyError -> Self.D.Scalar

Evaluate by descending Horner steps without implicit reassociation.

Arguments.

• value: The finite point or bounded argument enclosure.
• context: Explicit output settings.
• budget: The shared work allowance.

Returns. The rounded value or rigorous enclosure.

Raises.

• PolyError: DOMAIN for invalid values, LIMIT or CAPACITY on work limits.

NumericDensePoly.evaluate_with_derivative¶

def evaluate_with_derivative(self, value: Self.D.Scalar, context: Self.D.Context, mut budget: Budget) raises PolyError -> Tuple[Self.D.Scalar, Self.D.Scalar]

Evaluate the value and derivative together by extended Horner steps.

Arguments.

• value: The finite point or bounded argument enclosure.
• context: Explicit output settings.
• budget: The shared work allowance.

Returns. The value and derivative, each rounded or enclosed.

Raises.

• PolyError: DOMAIN for invalid values, LIMIT or CAPACITY on work limits.

NumericTerm¶

@fieldwise_init
struct NumericTerm[D: NumericDomain](Copyable, Movable)

A monomial with an apn_mojo numerical coefficient.

Parameters.

• D: The numerical domain adapter.

Defined in src/polynomials/numeric_sparse.mojo.

NumericSparsePoly¶

struct NumericSparsePoly[D: NumericDomain](Copyable, Movable)

A sparse multivariate numerical polynomial with explicit monomial order.

Parameters.

• D: The numerical domain adapter.

Defined in src/polynomials/numeric_sparse.mojo.

NumericSparsePoly.__init__¶

def __init__(out self, var order: MonomialOrder)

Construct zero by taking ownership of its monomial order.

Arguments.

• order: The validated owned order.

NumericSparsePoly.from_terms¶

@staticmethod
def from_terms(var terms: List[NumericTerm[Self.D]], order: MonomialOrder, context: Self.D.Context, mut budget: Budget) raises PolyError -> Self

Sort stably, combine duplicate terms and remove only certain zeros.

Arguments.

• terms: The owned terms in their original accumulation order.
• order: The output monomial order.
• context: Explicit settings for duplicate coefficient sums.
• budget: The shared work allowance.

Returns. The canonical numerical polynomial.

Raises.

• PolyError: DOMAIN for invalid values or monomials, LIMIT or CAPACITY on work limits.

NumericSparsePoly.degree_bound¶

def degree_bound(self, mut budget: Budget) raises PolyError -> Int

Return the total-degree upper bound, or minus one for zero.

Arguments.

• budget: The shared work allowance.

Returns. The largest total degree among stored monomials.

Raises.

• PolyError: CAPACITY for an unrepresentable degree or LIMIT on exhaustion.

NumericSparsePoly.certified_degree¶

def certified_degree(self, mut budget: Budget) raises PolyError -> Optional[Int]

Determine the total degree shared by every represented polynomial.

Arguments.

• budget: The shared work allowance.

Returns. The degree, minus one for zero, or None for uncertain top terms.

Raises.

• PolyError: DOMAIN for invalid values, LIMIT or CAPACITY on work limits.

NumericSparsePoly.add¶

def add(self, other: Self, context: Self.D.Context, mut budget: Budget) raises PolyError -> Self

Add terms, accumulating equal monomials left before right.

Arguments.

• other: The polynomial in the same monomial order.
• context: Explicit output settings.
• budget: The shared work allowance.

Returns. The rounded or enclosing sum.

Raises.

• PolyError: DOMAIN for incompatible values, LIMIT or CAPACITY on work limits.

NumericSparsePoly.sub¶

def sub(self, other: Self, context: Self.D.Context, mut budget: Budget) raises PolyError -> Self

Subtract the right polynomial using explicit rounded coefficient negation.

Arguments.

• other: The polynomial in the same monomial order.
• context: Explicit output settings.
• budget: The shared work allowance.

Returns. The rounded or enclosing difference.

Raises.

• PolyError: DOMAIN for incompatible values, LIMIT or CAPACITY on work limits.

NumericSparsePoly.neg¶

def neg(self, context: Self.D.Context, mut budget: Budget) raises PolyError -> Self

Negate coefficients at the specified precision.

Arguments.

• context: Explicit output settings.
• budget: The shared work allowance.

Returns. The rounded or enclosing negation.

Raises.

• PolyError: DOMAIN for invalid values, LIMIT or CAPACITY on work limits.

NumericSparsePoly.mul¶

def mul(self, other: Self, context: Self.D.Context, mut budget: Budget) raises PolyError -> Self

Multiply with stable left-major accumulation of equal products.

Arguments.

• other: The polynomial in the same monomial order.
• context: Explicit output settings.
• budget: The shared work allowance.

Returns. The rounded or enclosing product.

Raises.

• PolyError: DOMAIN for incompatible values, LIMIT or CAPACITY on work limits.

NumericSparsePoly.scale¶

def scale(self, scalar: Self.D.Scalar, context: Self.D.Context, mut budget: Budget, *, divide: Bool = False) raises PolyError -> Self

Scale terms, optionally dividing by a certified nonzero scalar.

Arguments.

• scalar: The finite scalar or bounded enclosure.
• context: Explicit output settings.
• budget: The shared work allowance.
• divide: Select division with a nonzero-divisor proof.

Returns. The rounded or enclosing scaled polynomial.

Raises.

• PolyError: DOMAIN for invalid or uncertain divisors, LIMIT or CAPACITY on work limits.

NumericSparsePoly.pow¶

def pow(self, exponent: UInt64, context: Self.D.Context, mut budget: Budget) raises PolyError -> Self

Compute a nonnegative power by deterministic binary powering.

Arguments.

• exponent: The nonnegative power.
• context: Explicit output settings.
• budget: The shared work allowance.

Returns. The rounded or enclosing power.

Raises.

• PolyError: DOMAIN for invalid values, LIMIT or CAPACITY on work limits.

NumericSparsePoly.derivative¶

def derivative(self, variable: Int64, context: Self.D.Context, mut budget: Budget) raises PolyError -> Self

Differentiate with respect to one variable.

Arguments.

• variable: The differentiation variable.
• context: Explicit output settings.
• budget: The shared work allowance.

Returns. The rounded or enclosing partial derivative.

Raises.

• PolyError: DOMAIN for invalid values, LIMIT or CAPACITY on work limits.

NumericSparsePoly.evaluate¶

def evaluate(self, assignments: List[Tuple[Int64, Self.D.Scalar]], context: Self.D.Context, mut budget: Budget) raises PolyError -> Self.D.Scalar

Evaluate in canonical term order with cached variable powers.

Arguments.

• assignments: Distinct variable/value pairs, allowing unused variables.
• context: Explicit output settings.
• budget: The shared work allowance.

Returns. The rounded value or rigorous enclosure.

Raises.

• PolyError: DOMAIN for missing or repeated variables or invalid values, LIMIT or CAPACITY on work limits.

NumericSparsePoly.from_dense¶

@staticmethod
def from_dense(poly: NumericDensePoly[Self.D], order: MonomialOrder, context: Self.D.Context, mut budget: Budget) raises PolyError -> Self

Convert a dense univariate polynomial into sparse form.

Arguments.

• poly: The dense polynomial.
• order: The output monomial order.
• context: Explicit arithmetic settings.
• budget: The shared work allowance.

Returns. A value-preserving sparse representation.

Raises.

• PolyError: DOMAIN for invalid orders, LIMIT or CAPACITY on work limits.

NumericSparsePoly.to_dense¶

def to_dense(self, variable: Int64, context: Self.D.Context, mut budget: Budget) raises PolyError -> NumericDensePoly[Self.D]

Convert a polynomial in one specified variable into dense form.

Arguments.

• variable: The retained variable, including for constants and zero.
• context: Explicit settings for gap zeros.
• budget: The shared work allowance.

Returns. A value-preserving dense representation.

Raises.

• PolyError: DOMAIN for other variables, LIMIT or CAPACITY before dense allocation.

NumericBox¶

@fieldwise_init
struct NumericBox(Copyable, Movable, Equatable, Writable)

A closed complex rectangle with exact rational endpoints.

Defined in src/polynomials/numeric_bounds.mojo.

NumericBox.real_interval¶

@staticmethod
def real_interval(low: QQ, high: QQ, mut budget: Budget) raises PolyError -> Self

Construct a real interval with zero imaginary part.

Arguments.

• low: The real lower endpoint.
• high: The real upper endpoint.
• budget: The shared work allowance.

Returns. The validated exact rectangle.

Raises.

• PolyError: DOMAIN for reversed bounds, LIMIT on exhaustion.

NumericBox.point¶

@staticmethod
def point(real: QQ, imag: QQ, mut budget: Budget) raises PolyError -> Self

Construct a singleton rectangle.

Arguments.

• real: The exact real coordinate.
• imag: The exact imaginary coordinate.
• budget: The shared work allowance.

Returns. The exact point enclosure.

Raises.

• PolyError: LIMIT on exhaustion.

NumericBox.contains¶

def contains(self, other: Self, mut budget: Budget) raises PolyError -> Bool

Check exact set containment, rejecting malformed bounds.

Arguments.

• other: The proposed contained rectangle.
• budget: The shared work allowance.

Returns. Whether both rectangles are valid and containment holds.

Raises.

• PolyError: LIMIT on exhaustion.

numeric_bounds¶

def numeric_bounds[D: NumericDomain](value: D.Scalar, mut budget: Budget) raises PolyError -> NumericBox

Extract exact rational endpoints from a finite apn_mojo numerical value.

Parameters.

• D: The numerical domain adapter.

Arguments.

• value: The point value or bounded enclosure.
• budget: The shared work allowance.

Returns. The exact stored point or represented rectangle.

Raises.

• PolyError: DOMAIN for nonfinite values, LIMIT or CAPACITY on work limits.

Defined in src/polynomials/numeric_bounds.mojo.

numeric_value¶

def numeric_value[D: NumericDomain](bounds: NumericBox, context: D.Context, mut budget: Budget) raises PolyError -> D.Scalar

Convert exact bounds to an enclosure or a certainly rounded point value.

Parameters.

• D: The destination numerical domain adapter.

Arguments.

• bounds: The exact point or interval to convert.
• context: Explicit output precision and rounding settings.
• budget: The shared work allowance.

Returns. An enclosing ball or one rounded point shared by every enclosed value.

Raises.

• PolyError: DOMAIN for uncertain rounding or nonreal real-domain input, LIMIT or CAPACITY on work limits.

Defined in src/polynomials/numeric_bounds.mojo.

convert_numeric_dense¶

def convert_numeric_dense[E: NumericDomain, D: NumericDomain](poly: NumericDensePoly[D], context: E.Context, mut budget: Budget) raises PolyError -> NumericDensePoly[E]

Convert numerical coefficients with enclosing or certainly rounded semantics.

Parameters.

• E: The destination domain.
• D: The source domain.

Arguments.

• poly: The source polynomial.
• context: Explicit destination settings.
• budget: The shared work allowance.

Returns. The converted polynomial in the same variable.

Raises.

• PolyError: DOMAIN for uncertain point conversion, LIMIT or CAPACITY on work limits.

Defined in src/polynomials/numeric_convert.mojo.

convert_numeric_sparse¶

def convert_numeric_sparse[E: NumericDomain, D: NumericDomain](poly: NumericSparsePoly[D], context: E.Context, mut budget: Budget) raises PolyError -> NumericSparsePoly[E]

Convert sparse numerical coefficients explicitly between domains.

Parameters.

• E: The destination domain.
• D: The source domain.

Arguments.

• poly: The source polynomial.
• context: Explicit destination settings.
• budget: The shared work allowance.

Returns. The converted polynomial in the same monomial order.

Raises.

• PolyError: DOMAIN for uncertain point conversion, LIMIT or CAPACITY on work limits.

Defined in src/polynomials/numeric_convert.mojo.

numeric_from_dense¶

def numeric_from_dense[D: NumericDomain, C: CoefficientRing](poly: DensePoly[C], context: D.Context, mut budget: Budget) raises PolyError -> NumericDensePoly[D]

Convert an exact integer, rational, or Gaussian rational polynomial directly into a numerical domain.

Parameters.

• D: The destination numerical domain.
• C: ZZ, QQ, or QQi.

Arguments.

• poly: The exact source polynomial.
• context: Explicit destination settings.
• budget: The shared work allowance.

Returns. A rounded point polynomial or rigorous coefficient enclosure.

Raises.

• PolyError: UNSUPPORTED for other exact domains, DOMAIN for invalid conversion, LIMIT or CAPACITY on work limits.

Defined in src/polynomials/numeric_convert.mojo.

numeric_from_sparse¶

def numeric_from_sparse[D: NumericDomain, C: CoefficientRing](poly: SparsePoly[C], context: D.Context, mut budget: Budget) raises PolyError -> NumericSparsePoly[D]

Convert exact sparse integer, rational, or Gaussian rational coefficients to numerical values.

Parameters.

• D: The destination numerical domain.
• C: ZZ, QQ, or QQi.

Arguments.

• poly: The exact source polynomial.
• context: Explicit destination settings.
• budget: The shared work allowance.

Returns. A numerical polynomial preserving the monomial order.

Raises.

• PolyError: UNSUPPORTED for other exact domains, DOMAIN for invalid conversion, LIMIT or CAPACITY on work limits.

Defined in src/polynomials/numeric_convert.mojo.

NumericOutcome¶

@fieldwise_init
struct NumericOutcome(ImplicitlyCopyable, Equatable, Writable)

Classify a completed numerical request or an inconclusive analysis.

Defined in src/polynomials/numeric_options.mojo.

NumericOutcome.SUCCESS¶

comptime SUCCESS = Self(0)

The requested claims were established.

NumericOutcome.UNCERTAIN_DEGREE¶

comptime UNCERTAIN_DEGREE = Self(1)

The leading coefficient may vanish.

NumericOutcome.INPUT_UNCERTAINTY¶

comptime INPUT_UNCERTAINTY = Self(2)

Coefficient or argument uncertainty prevents the requested guarantee.

NumericOutcome.PRECISION_CEILING¶

comptime PRECISION_CEILING = Self(3)

The configured precision did not establish the requested accuracy.

NumericOutcome.SUBDIVISION_LIMIT¶

comptime SUBDIVISION_LIMIT = Self(4)

The configured subdivision allowance did not finish the analysis.

NumericOutcome.UNRESOLVED_BOUNDARY¶

comptime UNRESOLVED_BOUNDARY = Self(5)

A search boundary could not be certified root-free.

NumericOptions¶

struct NumericOptions(ImplicitlyCopyable, Writable)

Explicit precision, accuracy and subdivision limits for adaptive algorithms.

Defined in src/polynomials/numeric_options.mojo.

NumericOptions.__init__¶

def __init__(out self, *, initial_precision: Int = 128, max_precision: Int = 1024, absolute_bits: Int = 32, relative_bits: Int = 0, max_subdivisions: Int = 4096, require_isolation: Bool = True)

Set explicit numerical options, validated when an algorithm starts.

Arguments.

• initial_precision: The first working precision.
• max_precision: The precision ceiling.
• absolute_bits: The absolute width exponent, zero to disable.
• relative_bits: The relative width exponent, zero to disable.
• max_subdivisions: The deterministic search allowance.
• require_isolation: Require single-root regions.

EnclosureEvaluation¶

@fieldwise_init
struct EnclosureEvaluation[D: NumericDomain](Copyable, Movable)

A ball value with an exact endpoint witness for every evaluation step.

Parameters.

• D: BallDomain or ComplexBallDomain.

Defined in src/polynomials/numeric_evaluate.mojo.

EnclosureEvaluation.value¶

def value(self, mut budget: Budget) raises PolyError -> Self.D.Scalar

Copy the reported enclosure.

Arguments.

• budget: The shared work allowance for copying the scalar.

Returns. The enclosing scalar, independently owned by the caller.

Raises.

• PolyError: DOMAIN for malformed storage, LIMIT or CAPACITY on work limits.

AdaptiveEvaluation¶

@fieldwise_init
struct AdaptiveEvaluation[D: NumericDomain](Copyable, Movable)

An accuracy outcome accompanied by a checkable enclosure.

Parameters.

• D: BallDomain or ComplexBallDomain.

Defined in src/polynomials/numeric_evaluate.mojo.

Incremental evaluation witnesses¶

EnclosureStream and EnclosureStreamChecker are additive alternatives for transporting the existing evaluation witness one NumericBox at a time. Their from_dense, from_sparse, from_numeric and from_numeric_sparse factories own the prepared graph, so later edits to the original inputs cannot affect an active producer or checker. Exact inputs are ZZ/QQ/QQi; the four numerical coefficient families are accepted by the numerical factories. Output domains remain Ball and ComplexBall, with an explicit producer context.

Call next(budget) until it returns None. Only then may finish(budget) return a StreamedEnclosure receipt. Every successful next returns the corresponding box from the existing materialized certificate, in the same instruction order. An abandoned prefix is incomplete evidence. A failed computation does not consume a step, allowing retry with a fresh allowance.

The independent checker receives each box through accept(box, budget) and uses exact rational arithmetic to check that instruction. It retains bounds with future uses and recycles other slots. A malformed or extra box permanently invalidates the checker. Its finish(receipt, budget) returns True only after the complete stream, the reported step count and precision, and the final scalar enclosure have all been checked. A receipt alone is not a proof.

Producer and checker can be connected in one loop or separated by a caller's transport/storage layer. Neither requires storing all witness payloads. Memory still includes the input graph and live scalar/bound slots; dense input coefficients are loaded before their Horner consumers, so this is not a constant-memory algorithm in the polynomial size. Existing APIs keep their full EnclosureEvaluation.steps list and unchanged certificate format.

StreamedEnclosure¶

@fieldwise_init
struct StreamedEnclosure[D: NumericDomain](Copyable, Movable)

A completed scalar receipt requiring its separately transported witness.

Parameters.

• D: BallDomain or ComplexBallDomain.

Defined in src/polynomials/numeric_stream.mojo.

StreamedEnclosure.value¶

def value(self, mut budget: Budget) raises PolyError -> Self.D.Scalar

Copy the completed scalar enclosure.

Arguments.

• budget: The shared allowance for copying the scalar.

Returns. An independently owned value; its receipt alone is not a proof.

Raises.

• PolyError: DOMAIN for malformed storage or LIMIT on exhaustion.

EnclosureStream¶

@fieldwise_init
struct EnclosureStream[D: NumericDomain](Movable)

Produce the existing instruction witness one endpoint box at a time.

Parameters.

• D: BallDomain or ComplexBallDomain.

Defined in src/polynomials/numeric_stream.mojo.

EnclosureStream.from_dense¶

@staticmethod
def from_dense[C: CoefficientRing](poly: DensePoly[C], argument: Self.D.Scalar, context: Self.D.Context, mut budget: Budget) raises PolyError -> Self

Prepare an incremental producer for an exact dense polynomial.

Parameters.

• C: The source coefficient domain.

Arguments.

• poly: The original polynomial, borrowed during preparation.
• argument: The bounded evaluation argument.
• context: The explicit output precision.
• budget: The shared preparation allowance.

Returns. A producer owning its prepared input graph.

Raises.

• PolyError: DOMAIN for invalid inputs, UNSUPPORTED for unsupported domains, LIMIT or CAPACITY on work limits.

EnclosureStream.from_sparse¶

@staticmethod
def from_sparse[C: CoefficientRing](poly: SparsePoly[C], assignments: List[Tuple[Int64, Self.D.Scalar]], context: Self.D.Context, mut budget: Budget) raises PolyError -> Self

Prepare an incremental producer for an exact sparse polynomial.

Parameters.

• C: The source coefficient domain.

Arguments.

• poly: The original polynomial, borrowed during preparation.
• assignments: Bounded values for every occurring variable.
• context: The explicit output precision.
• budget: The shared preparation allowance.

Returns. A producer owning its prepared input graph.

Raises.

• PolyError: DOMAIN for invalid inputs, UNSUPPORTED for unsupported domains, LIMIT or CAPACITY on work limits.

EnclosureStream.from_numeric¶

@staticmethod
def from_numeric[E: NumericDomain](poly: NumericDensePoly[E], argument: Self.D.Scalar, context: Self.D.Context, mut budget: Budget) raises PolyError -> Self

Prepare an incremental producer for a numerical dense polynomial.

Parameters.

• E: The source coefficient domain.

Arguments.

• poly: The original polynomial, borrowed during preparation.
• argument: The bounded evaluation argument.
• context: The explicit output precision.
• budget: The shared preparation allowance.

Returns. A producer owning its prepared input graph.

Raises.

• PolyError: DOMAIN for invalid inputs, UNSUPPORTED for unsupported domains, LIMIT or CAPACITY on work limits.

EnclosureStream.from_numeric_sparse¶

@staticmethod
def from_numeric_sparse[E: NumericDomain](poly: NumericSparsePoly[E], assignments: List[Tuple[Int64, Self.D.Scalar]], context: Self.D.Context, mut budget: Budget) raises PolyError -> Self

Prepare an incremental producer for a numerical sparse polynomial.

Parameters.

• E: The source coefficient domain.

Arguments.

• poly: The original polynomial, borrowed during preparation.
• assignments: Bounded values for every occurring variable.
• context: The explicit output precision.
• budget: The shared preparation allowance.

Returns. A producer owning its prepared input graph.

Raises.

• PolyError: DOMAIN for invalid inputs, UNSUPPORTED for unsupported domains, LIMIT or CAPACITY on work limits.

EnclosureStream.step_count¶

def step_count(self) -> Int

Return the full witness length, including unconsumed steps.

Returns. The number of endpoint boxes needed for completion.

EnclosureStream.next¶

def next(mut self, mut budget: Budget) raises PolyError -> Optional[NumericBox]

Produce the next bound while recycling dead scalar slots.

Arguments.

• budget: The shared evaluation allowance.

Returns. The next original witness box, or None after the final step.

Raises.

• PolyError: DOMAIN for invalid arithmetic, LIMIT or CAPACITY on work limits; a failed step is not consumed.

EnclosureStream.finish¶

def finish(self, mut budget: Budget) raises PolyError -> StreamedEnclosure[Self.D]

Create a receipt only after every endpoint has been produced.

Arguments.

• budget: The allowance for copying the final scalar.

Returns. A completed receipt whose witness is the consumed endpoint stream.

Raises.

• PolyError: DOMAIN for an incomplete stream or LIMIT on exhaustion.

EnclosureStreamChecker¶

@fieldwise_init
struct EnclosureStreamChecker[D: NumericDomain](Movable)

Check streamed bounds independently while retaining only live witnesses.

Parameters.

• D: BallDomain or ComplexBallDomain.

Defined in src/polynomials/numeric_stream.mojo.

EnclosureStreamChecker.from_dense¶

@staticmethod
def from_dense[C: CoefficientRing](poly: DensePoly[C], argument: Self.D.Scalar, mut budget: Budget) raises PolyError -> Self

Prepare an incremental checker for an exact dense polynomial.

Parameters.

• C: The source coefficient domain.

Arguments.

• poly: The original polynomial, borrowed during preparation.
• argument: The bounded evaluation argument.
• budget: The shared preparation allowance.

Returns. A checker owning its prepared input graph.

Raises.

• PolyError: DOMAIN for invalid inputs, UNSUPPORTED for unsupported domains, LIMIT or CAPACITY on work limits.

EnclosureStreamChecker.from_sparse¶

@staticmethod
def from_sparse[C: CoefficientRing](poly: SparsePoly[C], assignments: List[Tuple[Int64, Self.D.Scalar]], mut budget: Budget) raises PolyError -> Self

Prepare an incremental checker for an exact sparse polynomial.

Parameters.

• C: The source coefficient domain.

Arguments.

• poly: The original polynomial, borrowed during preparation.
• assignments: Bounded values for every occurring variable.
• budget: The shared preparation allowance.

Returns. A checker owning its prepared input graph.

Raises.

• PolyError: DOMAIN for invalid inputs, UNSUPPORTED for unsupported domains, LIMIT or CAPACITY on work limits.

EnclosureStreamChecker.from_numeric¶

@staticmethod
def from_numeric[E: NumericDomain](poly: NumericDensePoly[E], argument: Self.D.Scalar, mut budget: Budget) raises PolyError -> Self

Prepare an incremental checker for an numerical dense polynomial.

Parameters.

• E: The source coefficient domain.

Arguments.

• poly: The original polynomial, borrowed during preparation.
• argument: The bounded evaluation argument.
• budget: The shared preparation allowance.

Returns. A checker owning its prepared input graph.

Raises.

• PolyError: DOMAIN for invalid inputs, UNSUPPORTED for unsupported domains, LIMIT or CAPACITY on work limits.

EnclosureStreamChecker.from_numeric_sparse¶

@staticmethod
def from_numeric_sparse[E: NumericDomain](poly: NumericSparsePoly[E], assignments: List[Tuple[Int64, Self.D.Scalar]], mut budget: Budget) raises PolyError -> Self

Prepare an incremental checker for an numerical sparse polynomial.

Parameters.

• E: The source coefficient domain.

Arguments.

• poly: The original polynomial, borrowed during preparation.
• assignments: Bounded values for every occurring variable.
• budget: The shared preparation allowance.

Returns. A checker owning its prepared input graph.

Raises.

• PolyError: DOMAIN for invalid inputs, UNSUPPORTED for unsupported domains, LIMIT or CAPACITY on work limits.

EnclosureStreamChecker.step_count¶

def step_count(self) -> Int

Return the number of bounds required by the original input graph.

Returns. The full witness length.

EnclosureStreamChecker.accept¶

def accept(mut self, var bounds: NumericBox, mut budget: Budget) raises PolyError -> Bool

Verify one next bound with exact rational arithmetic.

Arguments.

• bounds: The next owned endpoint box in instruction order.
• budget: The shared checking allowance.

Returns. True for a valid next box; False permanently invalidates this checker.

Raises.

• PolyError: LIMIT or CAPACITY on work limits; a failed computation does not advance the checker.

EnclosureStreamChecker.finish¶

def finish(self, receipt: StreamedEnclosure[Self.D], mut budget: Budget) raises PolyError -> Bool

Verify stream completeness, reported precision and final enclosure.

Arguments.

• receipt: The completed producer receipt to verify.
• budget: The allowance for validating the final scalar.

Returns. True only for a complete accepted stream and a consistent receipt.

Raises.

• PolyError: LIMIT or CAPACITY on work limits.

enclose_dense¶

def enclose_dense[D: NumericDomain, C: CoefficientRing](poly: DensePoly[C], argument: D.Scalar, context: D.Context, mut budget: Budget) raises PolyError -> EnclosureEvaluation[D]

Evaluate an exact ZZ/QQ/QQi polynomial with a rigorous ball certificate.

Parameters.

• D: BallDomain or ComplexBallDomain.
• C: ZZ, QQ, or QQi.

Arguments.

• poly: The exact polynomial.
• argument: The bounded argument enclosure.
• context: Explicit output precision.
• budget: The shared work allowance.

Returns. The enclosing value and rational endpoint trace.

Raises.

• PolyError: DOMAIN for invalid values, UNSUPPORTED for other domains, LIMIT or CAPACITY on work limits.

Defined in src/polynomials/numeric_evaluate.mojo.

check_enclose_dense¶

def check_enclose_dense[D: NumericDomain, C: CoefficientRing](poly: DensePoly[C], argument: D.Scalar, certificate: EnclosureEvaluation[D], mut budget: Budget) raises PolyError -> Bool

Verify exact dense evaluation bounds without floating-point arithmetic or search.

Parameters.

• D: BallDomain or ComplexBallDomain.
• C: ZZ, QQ, or QQi.

Arguments.

• poly: The exact polynomial.
• argument: The original bounded argument.
• certificate: The proposed evaluation witness.
• budget: The shared work allowance.

Returns. Whether every local bound and the reported value are justified.

Raises.

• PolyError: DOMAIN for invalid inputs, UNSUPPORTED for other domains, LIMIT or CAPACITY on work limits.

Defined in src/polynomials/numeric_evaluate.mojo.

enclose_numeric¶

def enclose_numeric[D: NumericDomain, E: NumericDomain](poly: NumericDensePoly[E], argument: D.Scalar, context: D.Context, mut budget: Budget) raises PolyError -> EnclosureEvaluation[D]

Enclose evaluation of every polynomial in a numerical coefficient family.

Parameters.

• D: BallDomain or ComplexBallDomain.
• E: The source coefficient domain.

Arguments.

• poly: The numerical point or family polynomial.
• argument: The bounded argument enclosure.
• context: Explicit output precision.
• budget: The shared work allowance.

Returns. A family-wide enclosure and its bound trace.

Raises.

• PolyError: DOMAIN for invalid values, UNSUPPORTED for other output domains, LIMIT or CAPACITY on work limits.

Defined in src/polynomials/numeric_evaluate.mojo.

check_enclose_numeric¶

def check_enclose_numeric[D: NumericDomain, E: NumericDomain](poly: NumericDensePoly[E], argument: D.Scalar, certificate: EnclosureEvaluation[D], mut budget: Budget) raises PolyError -> Bool

Check a numerical family evaluation using exact endpoint arithmetic.

Parameters.

• D: BallDomain or ComplexBallDomain.
• E: The source coefficient domain.

Arguments.

• poly: The original numerical polynomial.
• argument: The original bounded argument.
• certificate: The proposed evaluation witness.
• budget: The shared work allowance.

Returns. Whether the witness encloses all permitted evaluations.

Raises.

• PolyError: DOMAIN for invalid inputs, LIMIT or CAPACITY on work limits.

Defined in src/polynomials/numeric_evaluate.mojo.

enclose_sparse¶

def enclose_sparse[D: NumericDomain, C: CoefficientRing](poly: SparsePoly[C], assignments: List[Tuple[Int64, D.Scalar]], context: D.Context, mut budget: Budget) raises PolyError -> EnclosureEvaluation[D]

Evaluate an exact multivariate polynomial with a checkable enclosure trace.

Parameters.

• D: BallDomain or ComplexBallDomain.
• C: ZZ, QQ, or QQi.

Arguments.

• poly: The exact sparse polynomial.
• assignments: Distinct assignments covering every occurring variable.
• context: Explicit output precision.
• budget: The shared work allowance.

Returns. The enclosing value and local bound witnesses.

Raises.

• PolyError: DOMAIN for invalid assignments, UNSUPPORTED for other domains, LIMIT or CAPACITY on work limits.

Defined in src/polynomials/numeric_evaluate.mojo.

check_enclose_sparse¶

def check_enclose_sparse[D: NumericDomain, C: CoefficientRing](poly: SparsePoly[C], assignments: List[Tuple[Int64, D.Scalar]], certificate: EnclosureEvaluation[D], mut budget: Budget) raises PolyError -> Bool

Verify sparse exact-polynomial evaluation bounds independently.

Parameters.

• D: BallDomain or ComplexBallDomain.
• C: ZZ, QQ, or QQi.

Arguments.

• poly: The original exact polynomial.
• assignments: The original argument enclosures.
• certificate: The proposed evaluation witness.
• budget: The shared work allowance.

Returns. Whether the complete bound trace is valid.

Raises.

• PolyError: DOMAIN for invalid assignments, UNSUPPORTED for other domains, LIMIT or CAPACITY on work limits.

Defined in src/polynomials/numeric_evaluate.mojo.

enclose_numeric_sparse¶

def enclose_numeric_sparse[D: NumericDomain, E: NumericDomain](poly: NumericSparsePoly[E], assignments: List[Tuple[Int64, D.Scalar]], context: D.Context, mut budget: Budget) raises PolyError -> EnclosureEvaluation[D]

Enclose sparse numerical-family evaluation with cached variable powers.

Parameters.

• D: BallDomain or ComplexBallDomain.
• E: The source numerical domain.

Arguments.

• poly: The numerical sparse polynomial.
• assignments: Distinct assignments covering every occurring variable.
• context: Explicit output precision.
• budget: The shared work allowance.

Returns. A family-wide enclosure and its bound trace.

Raises.

• PolyError: DOMAIN for invalid assignments, LIMIT or CAPACITY on work limits.

Defined in src/polynomials/numeric_evaluate.mojo.

check_enclose_numeric_sparse¶

def check_enclose_numeric_sparse[D: NumericDomain, E: NumericDomain](poly: NumericSparsePoly[E], assignments: List[Tuple[Int64, D.Scalar]], certificate: EnclosureEvaluation[D], mut budget: Budget) raises PolyError -> Bool

Verify sparse numerical-family evaluation using rational bounds.

Parameters.

• D: BallDomain or ComplexBallDomain.
• E: The source numerical domain.

Arguments.

• poly: The original numerical polynomial.
• assignments: The original argument enclosures.
• certificate: The proposed evaluation witness.
• budget: The shared work allowance.

Returns. Whether every local bound is justified.

Raises.

• PolyError: DOMAIN for invalid assignments, LIMIT or CAPACITY on work limits.

Defined in src/polynomials/numeric_evaluate.mojo.

adaptive_enclose_dense¶

def adaptive_enclose_dense[D: NumericDomain, C: CoefficientRing](poly: DensePoly[C], argument: D.Scalar, options: NumericOptions, mut budget: Budget) raises PolyError -> AdaptiveEvaluation[D]

Refine evaluation precision from the original exact coefficients.

Parameters.

• D: BallDomain or ComplexBallDomain.
• C: ZZ, QQ, or QQi.

Arguments.

• poly: The exact polynomial.
• argument: The original bounded argument, preserving its uncertainty.
• options: The precision ceiling and requested widths.
• budget: The shared work allowance.

Returns. A certified enclosure with SUCCESS or an explicit precision-ceiling outcome.

Raises.

• PolyError: DOMAIN for invalid options or inputs, LIMIT or CAPACITY on work limits.

Defined in src/polynomials/numeric_evaluate.mojo.

adaptive_enclose_sparse¶

def adaptive_enclose_sparse[D: NumericDomain, C: CoefficientRing](poly: SparsePoly[C], assignments: List[Tuple[Int64, D.Scalar]], options: NumericOptions, mut budget: Budget) raises PolyError -> AdaptiveEvaluation[D]

Refine sparse evaluation while retaining exact coefficients and input uncertainty.

Parameters.

• D: BallDomain or ComplexBallDomain.
• C: ZZ, QQ, or QQi.

Arguments.

• poly: The exact sparse polynomial.
• assignments: Distinct variable/enclosure pairs.
• options: The precision ceiling and requested widths.
• budget: The shared work allowance.

Returns. The final checkable enclosure and its accuracy outcome.

Raises.

• PolyError: DOMAIN for invalid inputs, LIMIT or CAPACITY on work limits.

Defined in src/polynomials/numeric_evaluate.mojo.

check_numeric_accuracy¶

def check_numeric_accuracy[D: NumericDomain](result: AdaptiveEvaluation[D], options: NumericOptions, mut budget: Budget) raises PolyError -> Bool

Check an adaptive result's accuracy claim separately from its evaluation witness.

Parameters.

• D: BallDomain or ComplexBallDomain.

Arguments.

• result: The adaptive result whose evaluation witness must also be checked.
• options: The originally requested accuracy and precision limits.
• budget: The shared work allowance.

Returns. Whether its outcome agrees with the enclosure width and precision schedule.

Raises.

• PolyError: DOMAIN for invalid inputs, LIMIT or CAPACITY on work limits.

Defined in src/polynomials/numeric_evaluate.mojo.

RealRootCell¶

@fieldwise_init
struct RealRootCell(Copyable, Movable)

A real cover cell with a distinct-root count and local evidence.

Defined in src/polynomials/numeric_real_roots.mojo.

RealRootResult¶

@fieldwise_init
struct RealRootResult(Copyable, Movable)

A checked real cover, with separate completeness and accuracy flags.

Defined in src/polynomials/numeric_real_roots.mojo.

real_roots_exact¶

def real_roots_exact[C: CoefficientRing](poly: DensePoly[C], options: NumericOptions, mut budget: Budget, *, complete_only: Bool = False) raises PolyError -> DescartesRootResult

Isolate and refine the distinct real roots of an exact ZZ/QQ polynomial.

Descartes' rule of signs isolates the roots of the squarefree part; brackets are then tightened to the requested widths. The result carries a certificate that check_real_roots_exact verifies without searching.

Parameters.

• C: ZZ or QQ.

Arguments.

• poly: The original univariate polynomial.
• options: Accuracy and subdivision settings; every root is isolated.
• budget: The shared work allowance.
• complete_only: Raise unless every requested guarantee succeeds.

Returns. The roots with a Descartes certificate and explicit outcome flags.

Raises.

• PolyError: DOMAIN for zero or invalid input, UNSUPPORTED for other domains, LIMIT or CAPACITY on resource limits.

Defined in src/polynomials/numeric_real_roots.mojo.

real_roots_numeric¶

def real_roots_numeric[D: NumericDomain](poly: NumericDensePoly[D], options: NumericOptions, mut budget: Budget, *, complete_only: Bool = False) raises PolyError -> RealRootResult

Isolate real roots uniformly over stored real coefficient enclosures.

Parameters.

• D: A numerical coefficient domain with real coefficients.

Arguments.

• poly: The point or coefficient-family polynomial.
• options: Accuracy, isolation and resource settings.
• budget: The shared work allowance.
• complete_only: Raise unless every requested guarantee succeeds.

Returns. A complete checked cover or an explicitly inconclusive analysis.

Raises.

• PolyError: DOMAIN for zero or nonreal input, LIMIT or CAPACITY on resource limits.

Defined in src/polynomials/numeric_real_roots.mojo.

check_real_roots_exact¶

def check_real_roots_exact[C: CoefficientRing](poly: DensePoly[C], result: DescartesRootResult, options: NumericOptions, mut budget: Budget) raises PolyError -> Bool

Verify a Descartes real-root result without repeating root search.

Recomputes gcd(f, f') and the squarefree part, then checks the bound, every leaf's Descartes bound, the exact roots, two signs per bracket, the requested widths and the outcome flags.

Parameters.

• C: ZZ or QQ.

Arguments.

• poly: The original exact polynomial.
• result: The proposed result and certificate.
• options: The original accuracy requirements.
• budget: The shared work allowance.

Returns. Whether the result is complete and its certificate and every outcome flag are justified; incomplete results return False.

Raises.

• PolyError: DOMAIN for invalid input, LIMIT or CAPACITY on resource limits.

Defined in src/polynomials/numeric_real_roots.mojo.

check_real_roots_numeric¶

def check_real_roots_numeric[D: NumericDomain](poly: NumericDensePoly[D], result: RealRootResult, options: NumericOptions, mut budget: Budget) raises PolyError -> Bool

Verify uniform real-root counts for a numerical coefficient family.

Parameters.

• D: The original numerical coefficient domain.

Arguments.

• poly: The original point or family polynomial.
• result: The proposed complete cover and evidence.
• options: The original accuracy and isolation requirements.
• budget: The shared work allowance.

Returns. Whether all local witnesses and global coverage are valid.

Raises.

• PolyError: DOMAIN for invalid input, LIMIT or CAPACITY on resource limits.

Defined in src/polynomials/numeric_real_roots.mojo.

ComplexBoundarySegment¶

@fieldwise_init
struct ComplexBoundarySegment(Copyable, Movable)

One oriented rectangle-boundary segment and its zero-free image evidence.

Defined in src/polynomials/numeric_complex_roots.mojo.

ComplexRootRegion¶

@fieldwise_init
struct ComplexRootRegion(Copyable, Movable)

A rectangle with a uniform root count including multiplicities.

Defined in src/polynomials/numeric_complex_roots.mojo.

ComplexRootResult¶

@fieldwise_init
struct ComplexRootResult(Copyable, Movable)

A disjoint complex root cover with explicit completeness and accuracy.

Defined in src/polynomials/numeric_complex_roots.mojo.

complex_roots_exact¶

def complex_roots_exact[C: CoefficientRing](poly: DensePoly[C], options: NumericOptions, mut budget: Budget, *, complete_only: Bool = False) raises PolyError -> ComplexRootResult

Produce a validated complex cover of an exact ZZ/QQ/QQi polynomial's roots.

Parameters.

• C: ZZ, QQ, or QQi.

Arguments.

• poly: The original exact polynomial.
• options: Precision, accuracy, isolation and subdivision settings.
• budget: The shared work allowance.
• complete_only: Raise unless every requested guarantee succeeds.

Returns. Root rectangles with multiplicity counts and winding witnesses.

Raises.

• PolyError: DOMAIN for zero or invalid input, UNSUPPORTED for other domains, LIMIT or CAPACITY on work limits.

Defined in src/polynomials/numeric_complex_roots.mojo.

complex_roots_numeric¶

def complex_roots_numeric[D: NumericDomain](poly: NumericDensePoly[D], options: NumericOptions, mut budget: Budget, *, complete_only: Bool = False) raises PolyError -> ComplexRootResult

Validate complex roots uniformly over a numerical coefficient family.

Parameters.

• D: Any of the four numerical coefficient domains.

Arguments.

• poly: The point or family polynomial.
• options: Precision, accuracy, isolation and subdivision settings.
• budget: The shared work allowance.
• complete_only: Raise unless every requested guarantee succeeds.

Returns. A certified complete cover or an explicit inconclusive outcome.

Raises.

• PolyError: DOMAIN for zero or invalid input, LIMIT or CAPACITY on work limits.

Defined in src/polynomials/numeric_complex_roots.mojo.

check_complex_roots_exact¶

def check_complex_roots_exact[C: CoefficientRing](poly: DensePoly[C], result: ComplexRootResult, options: NumericOptions, mut budget: Budget) raises PolyError -> Bool

Check complex winding evidence and completeness without root search.

Parameters.

• C: ZZ, QQ, or QQi.

Arguments.

• poly: The original exact polynomial.
• result: The proposed complete root cover.
• options: The original requested guarantees.
• budget: The shared work allowance.

Returns. Whether all counts, boundaries, disjointness and outcome flags hold.

Raises.

• PolyError: DOMAIN for invalid input, LIMIT or CAPACITY on work limits.

Defined in src/polynomials/numeric_complex_roots.mojo.

check_complex_roots_numeric¶

def check_complex_roots_numeric[D: NumericDomain](poly: NumericDensePoly[D], result: ComplexRootResult, options: NumericOptions, mut budget: Budget) raises PolyError -> Bool

Verify a uniform complex root cover for the original coefficient family.

Parameters.

• D: The original numerical coefficient domain.

Arguments.

• poly: The original point or family polynomial.
• result: The proposed complete root cover.
• options: The original requested guarantees.
• budget: The shared work allowance.

Returns. Whether every root-count and global completeness obligation is valid.

Raises.

• PolyError: DOMAIN for invalid input, LIMIT or CAPACITY on work limits.

Defined in src/polynomials/numeric_complex_roots.mojo.

General toolkit workflows¶

The toolkit adds numerical calculus, interpolation, basis conversion, formal series, lossless interchange, resumable real/complex root refinement, exact real-root multiplicity certificates, diagnostic bounds, certified Newton polishing and numerical division. These APIs are documented in the toolkit reference.

Incremental root witnesses¶

real_roots_exact_to, real_roots_numeric_to, complex_roots_exact_to and complex_roots_numeric_to send completed local witnesses directly to a sink. The materialized APIs and stream producers share their workers. Exact real streams go to a DescartesRootSink: begin receives the squarefree part, gcd(f, f') and the bound exponent, and each DescartesRootItem carries one leaf in increasing order with the exact root at its lower end, if any, and its brackets. The producer holds the certificate while it streams it; the consumer need not. Numerical real streams start with borrowed shared Sturm evidence, absent for uncertain coefficient families, and emit an ordered cover including excluded cells. Complex streams emit positive-count rectangles in the original traversal order.

Prepare DescartesStreamChecker (exact real), RealRootStreamChecker (numerical real) or ComplexRootStreamChecker from the original polynomial and options, use it as the sink, then call finish(receipt, budget). For transported evidence, call begin for the real header, accept for each local witness, and finish for the receipt. Header/witness rejection or an error during begin or accept invalidates the checker permanently. finish checks the receipt without changing state. The checker never reruns root isolation.

RootStreamReceipt reports outcome, completeness, accuracy, isolation and the number of transported pieces. It requires the complete accepted witness stream; its fields alone establish no mathematical claim. The independent checkers accept only certified local counts and complete covers. Inconclusive producers can return an incomplete receipt to a general sink; such a receipt does not pass finish. A checker used directly as a sink raises on unresolved local counts. complete_only=True can raise after transporting a prefix, which must not be treated as a completed proof.

Exact real checking stores the squarefree part and a current endpoint, and recomputes each leaf's bound as it arrives. Numerical real checking stores coefficient bounds, shared Sturm evidence and a current endpoint. Complex checking stores rectangle geometry for pairwise disjointness; completed contour traces are discarded. Producers retain their active search frontier. One cell or contour witness is still materialized at a time.

ComplexRootSink¶

trait ComplexRootSink

Consume completed complex root witnesses without retaining their prefix.

Defined in src/polynomials/numeric_complex_roots.mojo.

ComplexRootSink.write¶

def write(mut self, var region: ComplexRootRegion, mut budget: Budget) raises PolyError

Consume one completed complex root witness.

Arguments.

• region: The next owned witness in traversal order.
• budget: The shared transport allowance.

Raises.

• PolyError: On transport or resource failure.

ComplexRootStreamChecker¶

@fieldwise_init
struct ComplexRootStreamChecker(ComplexRootSink, Movable)

Verify complex root witnesses incrementally without retaining completed proofs.

Defined in src/polynomials/root_stream_check.mojo.

ComplexRootStreamChecker.from_dense¶

@staticmethod
def from_dense[C: CoefficientRing](poly: DensePoly[C], options: NumericOptions, mut budget: Budget) raises PolyError -> Self

Prepare independent checking for an original polynomial.

Parameters.

• C: The source coefficient domain.

Arguments.

• poly: The original polynomial or coefficient family.
• options: The original requested guarantees.
• budget: The shared preparation allowance.

Returns. A checker owning the input bounds and retained checking state.

Raises.

• PolyError: DOMAIN for invalid input, UNSUPPORTED for unsupported domains, LIMIT or CAPACITY on work limits.

ComplexRootStreamChecker.from_numeric¶

@staticmethod
def from_numeric[D: NumericDomain](poly: NumericDensePoly[D], options: NumericOptions, mut budget: Budget) raises PolyError -> Self

Prepare independent checking for an original polynomial.

Parameters.

• D: The source coefficient domain.

Arguments.

• poly: The original polynomial or coefficient family.
• options: The original requested guarantees.
• budget: The shared preparation allowance.

Returns. A checker owning the input bounds and retained checking state.

Raises.

• PolyError: DOMAIN for invalid input, UNSUPPORTED for unsupported domains, LIMIT or CAPACITY on work limits.

ComplexRootStreamChecker.write¶

def write(mut self, var witness: ComplexRootRegion, mut budget: Budget) raises PolyError

Check a producer witness directly as a streaming destination.

Arguments.

• witness: The next owned local root certificate.
• budget: The shared checking allowance.

Raises.

• PolyError: DOMAIN for rejected evidence, LIMIT or CAPACITY on work limits.

ComplexRootStreamChecker.accept¶

def accept(mut self, var witness: ComplexRootRegion, mut budget: Budget) raises PolyError -> Bool

Check and discard a local witness while retaining coverage state.

Arguments.

• witness: The next owned local certificate.
• budget: The shared checking allowance.

Returns. Whether the witness is valid; rejection permanently invalidates the checker.

Raises.

• PolyError: LIMIT or CAPACITY on work limits; failure invalidates the checker.

ComplexRootStreamChecker.finish¶

def finish(self, receipt: RootStreamReceipt, mut budget: Budget) raises PolyError -> Bool

Check global completeness and all receipt claims after consumption.

Arguments.

• receipt: The producer's completed receipt.
• budget: The shared checking allowance.

Returns. True only for a complete valid stream with consistent outcome flags.

Raises.

• PolyError: LIMIT on exhaustion.

DescartesRootItem¶

@fieldwise_init
struct DescartesRootItem(Copyable, Movable)

One leaf of a streamed Descartes certificate with the evidence that belongs to it.

Defined in src/polynomials/descartes.mojo.

DescartesRootSink¶

trait DescartesRootSink

Consume a Descartes certificate leaf by leaf without retaining its prefix.

Defined in src/polynomials/descartes.mojo.

DescartesRootSink.begin¶

def begin(mut self, squarefree: DensePoly[ZZ], cofactor: DensePoly[ZZ], bound_exponent: Int, mut budget: Budget) raises PolyError

Receive the squarefree part and the bound before any leaves.

Arguments.

• squarefree: The primitive positive-leading g = f / gcd(f, f').
• cofactor: The cofactor gcd(f, f').
• bound_exponent: The k with every root in (-2^k, 2^k).
• budget: The shared transport allowance.

Raises.

• PolyError: On transport or resource failure.

DescartesRootSink.write¶

def write(mut self, var item: DescartesRootItem, mut budget: Budget) raises PolyError

Consume the next leaf with its exact root and brackets.

Arguments.

• item: The next owned leaf in increasing order.
• budget: The shared transport allowance.

Raises.

• PolyError: On transport or resource failure.

DescartesStreamChecker¶

@fieldwise_init
struct DescartesStreamChecker(DescartesRootSink, Movable)

Verify a streamed Descartes certificate leaf by leaf, retaining only the current edge.

Defined in src/polynomials/descartes.mojo.

DescartesStreamChecker.from_dense¶

@staticmethod
def from_dense[C: CoefficientRing](poly: DensePoly[C], options: NumericOptions, mut budget: Budget) raises PolyError -> Self