Exact algebraic values¶
Use poly.algebraic for exact real and complex algebraic arithmetic. Its scalar
types also serve as coefficients in the inferred AA and QQbar fields. Start
with algebraic coefficients for construction
and polynomial workflows; approximation stays explicit.
Every computational operation has a shared Budget overload and a convenience
overload with max_steps=. Borrowed evidence is immutable; call .copy() on
it when you need independent mutable data for a core checker or serialization.
Save and restore these values with poly.io.
Real¶
@fieldwise_init
struct Real(CoefficientField)
An exact real number sharing its root witness and any arithmetic proof.
Use asreal or a polynomial's real_roots function to construct a value. Arithmetic stays exact; bounds and approximate make approximation explicit.
Defined in src/poly/_algebraic_value.mojo.
Real.witness¶
def witness(self) -> ref[ImmOrigin(origin_of(self._data[].plain))] RealAlgebraic
Borrow the exact value's defining polynomial and root witness.
Returns. Immutable core evidence tied to this value's shared storage.
Real.evidence¶
def evidence(self) -> ref[ImmOrigin(origin_of(self._data[].arithmetic))] Optional[AlgebraicArithmeticCertificate]
Borrow the arithmetic proof, when this value came from arithmetic.
Returns. The optional immutable arithmetic certificate.
Real.division_evidence¶
def division_evidence(self) -> ref[ImmOrigin(origin_of(self._data[].division))] Optional[AlgebraicArithmeticCertificate]
Borrow the inverse proof retained by divide.
Returns. An inverse certificate when this result came from divide.
Real.Context¶
comptime Context = NoContext
The context shared by all real algebraic values.
Real.zero¶
@staticmethod
def zero(ctx: NoContext) -> Self
Construct exact zero in the real algebraic field.
Arguments.
ctx: The field context.
Returns. The exact immutable value in this coefficient field.
Real.one¶
@staticmethod
def one(ctx: NoContext) -> Self
Construct exact one in the real algebraic field.
Arguments.
ctx: The field context.
Returns. The exact immutable value in this coefficient field.
Real.context¶
def context(self) -> NoContext
Return the real algebraic field's unique context.
Returns. The unique field context.
Real.is_zero¶
def is_zero(self) -> Bool
Test zero using the normalized rational representation.
Returns. Whether the exact condition holds.
Real.size¶
def size(self) -> Int
Return the cached witness size used for work accounting.
Returns. The stored size used for precharging work.
Real.add¶
def add(self, other: Self, mut budget: Budget) raises PolyError -> Self
Add real algebraic coefficients with retained arithmetic evidence.
Arguments.
other: The other coefficient in this field.budget: The caller-owned work allowance.
Returns. The exact immutable value in this coefficient field.
Raises.
PolyError: DOMAIN for division by zero, or LIMIT/CAPACITY on resource limits.
Real.sub¶
def sub(self, other: Self, mut budget: Budget) raises PolyError -> Self
Subtract real algebraic coefficients exactly.
Arguments.
other: The other coefficient in this field.budget: The caller-owned work allowance.
Returns. The exact immutable value in this coefficient field.
Raises.
PolyError: DOMAIN for division by zero, or LIMIT/CAPACITY on resource limits.
Real.mul¶
def mul(self, other: Self, mut budget: Budget) raises PolyError -> Self
Multiply real algebraic coefficients exactly.
Arguments.
other: The other coefficient in this field.budget: The caller-owned work allowance.
Returns. The exact immutable value in this coefficient field.
Raises.
PolyError: DOMAIN for division by zero, or LIMIT/CAPACITY on resource limits.
Real.neg¶
def neg(self, mut budget: Budget) raises PolyError -> Self
Negate a real algebraic coefficient exactly.
Arguments.
budget: The caller-owned work allowance.
Returns. The exact immutable value in this coefficient field.
Raises.
PolyError: DOMAIN for division by zero, or LIMIT/CAPACITY on resource limits.
Real.inverse¶
def inverse(self, mut budget: Budget) raises PolyError -> Self
Invert a nonzero coefficient; zero raises DOMAIN.
Arguments.
budget: The caller-owned work allowance.
Returns. The exact immutable value in this coefficient field.
Raises.
PolyError: DOMAIN for division by zero, or LIMIT/CAPACITY on resource limits.
Real.write_to¶
def write_to[W: Writer](self, mut writer: W)
Write an exact rational or a defining polynomial and isolating interval.
Parameters.
W: The output writer type.
Arguments.
writer: The destination for the exact representation.
Complex¶
@fieldwise_init
struct Complex(CoefficientField)
An exact complex algebraic number represented by two real algebraic parts.
Construct values with algebraic.ascomplex(real, imag). No precision context or chosen primitive element is required.
Defined in src/poly/_algebraic_value.mojo.
Complex.Context¶
comptime Context = NoContext
The context shared by all complex algebraic values.
Complex.zero¶
@staticmethod
def zero(ctx: NoContext) -> Self
Construct exact complex zero.
Arguments.
ctx: The field context.
Returns. The exact immutable value in this coefficient field.
Complex.one¶
@staticmethod
def one(ctx: NoContext) -> Self
Construct exact complex one.
Arguments.
ctx: The field context.
Returns. The exact immutable value in this coefficient field.
Complex.context¶
def context(self) -> NoContext
Return the complex algebraic field's unique context.
Returns. The unique field context.
Complex.real¶
def real(self) -> Real
Return the immutable exact real part.
Returns. The exact immutable value in this coefficient field.
Complex.imag¶
def imag(self) -> Real
Return the immutable exact imaginary part.
Returns. The exact immutable value in this coefficient field.
Complex.is_zero¶
def is_zero(self) -> Bool
Test whether both real parts are exactly zero.
Returns. Whether the exact condition holds.
Complex.size¶
def size(self) -> Int
Return the larger component witness size; copies share both components.
Returns. The stored size used for precharging work.
Complex.add¶
def add(self, other: Self, mut budget: Budget) raises PolyError -> Self
Add exact complex algebraic coefficients.
Arguments.
other: The other coefficient in this field.budget: The caller-owned work allowance.
Returns. The exact immutable value in this coefficient field.
Raises.
PolyError: DOMAIN for division by zero, or LIMIT/CAPACITY on resource limits.
Complex.sub¶
def sub(self, other: Self, mut budget: Budget) raises PolyError -> Self
Subtract exact complex algebraic coefficients.
Arguments.
other: The other coefficient in this field.budget: The caller-owned work allowance.
Returns. The exact immutable value in this coefficient field.
Raises.
PolyError: DOMAIN for division by zero, or LIMIT/CAPACITY on resource limits.
Complex.mul¶
def mul(self, other: Self, mut budget: Budget) raises PolyError -> Self
Multiply exact complex algebraic coefficients.
Arguments.
other: The other coefficient in this field.budget: The caller-owned work allowance.
Returns. The exact immutable value in this coefficient field.
Raises.
PolyError: DOMAIN for division by zero, or LIMIT/CAPACITY on resource limits.
Complex.neg¶
def neg(self, mut budget: Budget) raises PolyError -> Self
Negate both exact algebraic components.
Arguments.
budget: The caller-owned work allowance.
Returns. The exact immutable value in this coefficient field.
Raises.
PolyError: DOMAIN for division by zero, or LIMIT/CAPACITY on resource limits.
Complex.inverse¶
def inverse(self, mut budget: Budget) raises PolyError -> Self
Invert using the squared modulus; zero raises DOMAIN.
Arguments.
budget: The caller-owned work allowance.
Returns. The exact immutable value in this coefficient field.
Raises.
PolyError: DOMAIN for division by zero, or LIMIT/CAPACITY on resource limits.
Complex.write_to¶
def write_to[W: Writer](self, mut writer: W)
Write both exact algebraic components.
Parameters.
W: The output writer type.
Arguments.
writer: The destination for the exact representation.
ascomplex¶
def ascomplex[A: Copyable & Deinitable, B: Copyable & Deinitable](real: A, imag: B, mut budget: Budget) raises PolyError -> Complex
Build an exact complex algebraic value from its real and imaginary parts.
Parameters.
A: The real component's input type.B: The imaginary component's input type.
Arguments.
real: An integer, rational, or algebraic.Real.imag: An integer, rational, or algebraic.Real.budget: The work allowance shared by both conversions.
Returns. The exact complex value, sharing existing real witnesses.
Raises.
PolyError: LIMIT or CAPACITY when conversion exceeds available resources.
Defined in src/poly/algebraic.mojo.
conjugate¶
def conjugate(value: Complex, mut budget: Budget) raises PolyError -> Complex
Conjugate an exact complex value by negating its imaginary part.
Arguments.
value: The exact complex value.budget: The shared work allowance.
Returns. The exact complex conjugate.
Raises.
PolyError: LIMIT or CAPACITY on resource limits.
Defined in src/poly/algebraic.mojo.
asreal¶
def asreal[T: Copyable & Deinitable](value: T, mut budget: Budget) raises PolyError -> Real
Construct an exact real value from a scalar or core root witness.
Parameters.
T: The inferred input type.
Arguments.
value: An integer, Rational, existing Real, or mutable core RealAlgebraic witness.budget: The shared work allowance for preparation and computation.
Returns. The computed result, with its evidence retained.
Raises.
PolyError: DOMAIN for incompatible input, UNSUPPORTED for an unavailable operation, or LIMIT/CAPACITY on resource limits.
Defined in src/poly/algebraic.mojo.
add¶
def add[A: Copyable & Deinitable, B: Copyable & Deinitable](a: A, b: B, mut budget: Budget) raises PolyError -> _Arithmetic[A, B]
Add exact real or complex algebraic values with retained component evidence.
Parameters.
A: The inferred input type.B: The inferred input type.
Arguments.
a: The left exact integer, rational, Real, ExactComplex, or algebraic.Complex.b: The right exact integer, rational, Real, ExactComplex, or algebraic.Complex.budget: The shared work allowance for preparation and computation.
Returns. The computed result, with its evidence retained.
Raises.
PolyError: DOMAIN for incompatible input, UNSUPPORTED for an unavailable operation, or LIMIT/CAPACITY on resource limits.
Defined in src/poly/algebraic.mojo.
subtract¶
def subtract[A: Copyable & Deinitable, B: Copyable & Deinitable](a: A, b: B, mut budget: Budget) raises PolyError -> _Arithmetic[A, B]
Subtract exact real or complex algebraic values with retained component evidence.
Parameters.
A: The inferred input type.B: The inferred input type.
Arguments.
a: The left exact integer, rational, Real, ExactComplex, or algebraic.Complex.b: The right exact integer, rational, Real, ExactComplex, or algebraic.Complex.budget: The shared work allowance for preparation and computation.
Returns. The computed result, with its evidence retained.
Raises.
PolyError: DOMAIN for incompatible input, UNSUPPORTED for an unavailable operation, or LIMIT/CAPACITY on resource limits.
Defined in src/poly/algebraic.mojo.
multiply¶
def multiply[A: Copyable & Deinitable, B: Copyable & Deinitable](a: A, b: B, mut budget: Budget) raises PolyError -> _Arithmetic[A, B]
Multiply exact real or complex algebraic values with retained component evidence.
Parameters.
A: The inferred input type.B: The inferred input type.
Arguments.
a: The left exact integer, rational, Real, ExactComplex, or algebraic.Complex.b: The right exact integer, rational, Real, ExactComplex, or algebraic.Complex.budget: The shared work allowance for preparation and computation.
Returns. The computed result, with its evidence retained.
Raises.
PolyError: DOMAIN for incompatible input, UNSUPPORTED for an unavailable operation, or LIMIT/CAPACITY on resource limits.
Defined in src/poly/algebraic.mojo.
negative¶
def negative[T: Copyable & Deinitable](value: T, mut budget: Budget) raises PolyError -> _Arithmetic[T, T]
Negate an exact real or complex algebraic value.
Parameters.
T: The inferred input type.
Arguments.
value: An exact real, integer, or rational; inversion requires a nonzero value.budget: The shared work allowance for preparation and computation.
Returns. The computed result, with its evidence retained.
Raises.
PolyError: DOMAIN for incompatible input, UNSUPPORTED for an unavailable operation, or LIMIT/CAPACITY on resource limits.
Defined in src/poly/algebraic.mojo.
reciprocal¶
def reciprocal[T: Copyable & Deinitable](value: T, mut budget: Budget) raises PolyError -> _Arithmetic[T, T]
Invert an exact real or complex algebraic value.
Parameters.
T: The inferred input type.
Arguments.
value: An exact real, integer, or rational; inversion requires a nonzero value.budget: The shared work allowance for preparation and computation.
Returns. The computed result, with its evidence retained.
Raises.
PolyError: DOMAIN for incompatible input, UNSUPPORTED for an unavailable operation, or LIMIT/CAPACITY on resource limits.
Defined in src/poly/algebraic.mojo.
divide¶
def divide[A: Copyable & Deinitable, B: Copyable & Deinitable](a: A, b: B, mut budget: Budget) raises PolyError -> _Arithmetic[A, B]
Divide exact real or complex algebraic values.
Real results retain both inverse and multiplication certificates. Complex results retain the latest arithmetic evidence for each real component.
Parameters.
A: The inferred input type.B: The inferred input type.
Arguments.
a: The numerator.b: The nonzero denominator.budget: The shared work allowance for preparation and computation.
Returns. The computed result, with its evidence retained.
Raises.
PolyError: DOMAIN for incompatible input, UNSUPPORTED for an unavailable operation, or LIMIT/CAPACITY on resource limits.
Defined in src/poly/algebraic.mojo.
compare¶
def compare[A: Copyable & Deinitable, B: Copyable & Deinitable](a: A, b: B, mut budget: Budget) raises PolyError -> Int
Compare two exact real values.
Parameters.
A: The inferred input type.B: The inferred input type.
Arguments.
a: The left exact value.b: The right exact value.budget: The shared work allowance for preparation and computation.
Returns. Minus one, zero, or one according to the exact ordering.
Raises.
PolyError: DOMAIN for incompatible input, UNSUPPORTED for an unavailable operation, or LIMIT/CAPACITY on resource limits.
Defined in src/poly/algebraic.mojo.
check¶
def check(value: Real, mut budget: Budget) raises PolyError -> Bool
Verify the value and its retained arithmetic step, if present.
Arguments.
value: The exact real value to verify.budget: The shared work allowance for preparation and computation.
Returns. Whether the retained evidence proves the value or arithmetic step.
Raises.
PolyError: DOMAIN for incompatible input, UNSUPPORTED for an unavailable operation, or LIMIT/CAPACITY on resource limits.
Defined in src/poly/algebraic.mojo.
bounds¶
def bounds(value: Real, mut budget: Budget) raises PolyError -> Tuple[Rational, Rational]
Return rational bounds for an exact real value.
Arguments.
value: The exact real value.budget: The shared work allowance for preparation and computation.
Returns. Equal endpoints for rationals, or an open isolating interval for an irrational root.
Raises.
PolyError: DOMAIN for incompatible input, UNSUPPORTED for an unavailable operation, or LIMIT/CAPACITY on resource limits.
Defined in src/poly/algebraic.mojo.
refine¶
def refine[T: Copyable & Deinitable](value: Real, width: T, mut budget: Budget) raises PolyError -> Real
Return the same exact root with a narrower rational enclosure.
The refined result retains a root witness. Its earlier arithmetic derivation remains on the original value.
Parameters.
T: The inferred input type.
Arguments.
value: The exact value; the input remains unchanged.width: A positive exact bound on the returned interval width.budget: The shared work allowance for preparation and computation.
Returns. The computed result, with its evidence retained.
Raises.
PolyError: DOMAIN for incompatible input, UNSUPPORTED for an unavailable operation, or LIMIT/CAPACITY on resource limits.
Defined in src/poly/algebraic.mojo.
approximate¶
def approximate[T: Copyable & Deinitable](value: Real, width: T, mut budget: Budget) raises PolyError -> Rational
Return the rational midpoint of an explicitly narrowed enclosure.
Parameters.
T: The inferred input type.
Arguments.
value: The exact value to approximate.width: A positive interval-width target.budget: The shared work allowance for preparation and computation.
Returns. A rational approximation with absolute error less than width/2; exact for rational inputs.
Raises.
PolyError: DOMAIN for incompatible input, UNSUPPORTED for an unavailable operation, or LIMIT/CAPACITY on resource limits.
Defined in src/poly/algebraic.mojo.
evaluate¶
def evaluate[I: Iterable, X: Copyable & Deinitable](coefficients: I, point: X, mut budget: Budget) raises PolyError -> Real
Evaluate ascending real coefficients exactly, retaining the complete Horner proof.
Parameters.
I: The inferred input iterable type.X: The evaluation point or seed type.
Arguments.
coefficients: Ascending real coefficients, including exact algebraic values.point: The evaluation scalar or ordered coordinate tuple.budget: The shared work allowance, including preparation, computation, and result storage.
Returns. The evaluated scalar; algebraic results retain the evaluation proof.
Raises.
PolyError: DOMAIN for invalid or incompatible input, or LIMIT/CAPACITY on resource limits.
Defined in src/poly/algebraic.mojo.
Specialization¶
@fieldwise_init
struct Specialization[P: Copyable & Deinitable](_Archive, Copyable, Movable, Iterable, Sized)
Sparse algebraic coefficients after a partial assignment; original axes are retained.
Parameters.
P: The sparse power shape or retained source array type, inferred from the input.
Defined in src/poly/algebraic.mojo.
Specialization.IteratorType¶
comptime IteratorType[iterable_mut: Bool, //, iterable_origin: Origin[mut=iterable_mut]]: Iterator = _SpecializationIterator[Self.P, ImmOrigin(iterable_origin)]
Iterate over remaining powers and exact real coefficients.
Parameters.
iterable_mut: Whether the borrowing source origin allows mutation.iterable_origin: The lifetime of the borrowed source.
Returns. The borrowing iterator type.
Specialization.evidence¶
def evidence(self) -> ref[ImmOrigin(origin_of(self._data[].proof))] AlgebraicSpecializationCertificate
Borrow the immutable proofs for every specialized coefficient.
Returns. An immutable reference to the retained core evidence.
coefficients¶
def coefficients[P: Copyable & Deinitable](value: Specialization[P], mut budget: Budget, *, axis: Int = 0) raises PolyError -> Values[Real, 4]
Extract ascending algebraic coefficients when only one unassigned axis remains.
Parameters.
P: The sparse power shape or retained source array type, inferred from the input.
Arguments.
value: The value to convert or inspect.budget: The shared work allowance, including preparation, computation, and result storage.axis: The zero-based polynomial axis; defaults to zero.
Returns. Ascending exact algebraic coefficients of the remaining univariate polynomial.
Raises.
PolyError: DOMAIN for invalid or incompatible input, or LIMIT/CAPACITY on resource limits.
Defined in src/poly/algebraic.mojo.
Retained ordering evidence¶
compare_checked and sign_checked retain their operands and an ordering certificate. Read relation() for the claimed sign and use algebraic.check to verify it.
Comparison¶
@fieldwise_init
struct Comparison(Copyable, Movable)
An exact ordering relation retaining both values and independent evidence.
Defined in src/poly/algebraic.mojo.
Comparison.relation¶
def relation(self) -> Int
Return the claimed exact ordering.
Returns. Minus one, zero or one; use algebraic.check to verify the evidence.
Comparison.evidence¶
def evidence(self) -> ref[ImmOrigin(origin_of(self._data[].proof))] AlgebraicComparisonCertificate
Borrow the independent comparison witness.
Returns. Immutable evidence bound to the original values.
compare_checked¶
def compare_checked[A: Copyable & Deinitable, B: Copyable & Deinitable](a: A, b: B, mut budget: Budget) raises PolyError -> Comparison
Compare exact real values and retain the ordering proof.
Parameters.
A: Inferred from the input types unless explicitly supplied.B: Inferred from the input types unless explicitly supplied.
Arguments.
a: The first polynomial.b: The second polynomial.budget: The shared work allowance, including preparation and output storage.
Returns. A comparison retaining the original exact values and its claimed relation.
Raises.
PolyError: DOMAIN for incompatible input, UNSUPPORTED for an unavailable coefficient domain, or LIMIT/CAPACITY on resource limits.
Defined in src/poly/algebraic.mojo.
sign_checked¶
def sign_checked[A: Copyable & Deinitable](value: A, mut budget: Budget) raises PolyError -> Comparison
Determine the exact sign and retain its comparison with zero.
Parameters.
A: Inferred from the input types unless explicitly supplied.
Arguments.
value: The supplied value.budget: The shared work allowance, including preparation and output storage.
Returns. A checked comparison against exact zero.
Raises.
PolyError: DOMAIN for incompatible input, UNSUPPORTED for an unavailable coefficient domain, or LIMIT/CAPACITY on resource limits.
Defined in src/poly/algebraic.mojo.
For AA coefficients and real assignments, sparse.specialize returns an
iterable AlgebraicSpecialization. Its checker binds the original polynomial
and assignments to each returned coefficient. sparse.real_roots accepts this
result; sparse.roots_at retains it together with complete root evidence.
AlgebraicSpecialization¶
@fieldwise_init
struct AlgebraicSpecialization[P: Copyable & Deinitable](_Archive, Copyable, Movable, Iterable, Sized)
Specialized AA coefficients retaining the source, assignments, and proofs.
Parameters.
P: The original sparse power shape.
Defined in src/poly/_specialization.mojo.
AlgebraicSpecialization.IteratorType¶
comptime IteratorType[iterable_mut: Bool, //, iterable_origin: Origin[mut=iterable_mut]]: Iterator = _Iterator[Self.P, ImmOrigin(iterable_origin)]
Borrow powers and exact real coefficients.
Parameters.
iterable_mut: Whether the source origin permits mutation.iterable_origin: The source lifetime.
AlgebraicSpecialization.domain¶
def domain(self) -> String
Return the exact real algebraic coefficient domain.
Returns. AA.
AlgebraicSpecialization.ndim¶
def ndim(self) -> Int
Return the retained polynomial axis count.
Returns. The original power-shape width.
AlgebraicSpecialization.evidence¶
def evidence(self) -> ref[ImmOrigin(origin_of(self._lifted._data[].proof))] AlgebraicSpecializationCertificate
Borrow the coefficient evaluation transcript.
Returns. The rational lifting and algebraic evaluation evidence.