Formal series arrays¶

Construct formal series with a retained unknown-tail order. Exact integer coefficients promote to QQ; an explicit context= selects numerical arithmetic. All operations return new values.

Every computational call accepts a shared Budget or max_steps=. See the tutorial for examples, domain restrictions, and the meaning of retained metadata.

Save and restore these values with poly.io.

Array¶

@fieldwise_init
struct Array[k: Int](Copyable, Movable, Iterable, Sized, _WithModulus, _Record)

Immutable formal-series coefficients with retained representation metadata.

Parameters.

• k: The inferred exact field: QQ, QQi, GF(p), AA, or QQbar.

Defined in src/poly/series.mojo.

Array.IteratorType¶

comptime IteratorType[iterable_mut: Bool, //, iterable_origin: Origin[mut=iterable_mut]]: Iterator = _SeriesIterator[Self.k, ImmOrigin(iterable_origin)]

A borrowing coefficient iterator.

Parameters.

• iterable_mut: Whether the source origin permits mutation.
• iterable_origin: The lifetime of the source.

Array.modulus¶

def modulus(self) -> UInt64

Return the retained prime, or zero for QQ and QQi.

Returns. The prime modulus or zero.

Array.domain¶

def domain(self) -> String

Return the retained coefficient field.

Returns. QQ, QQi, or GF(p).

Array.order¶

def order(self) -> Int

Return the exponent of the unknown tail.

Returns. The exponent n in the formal remainder O(x**n).

asarray¶

def asarray[I: Iterable](values: I, mut budget: Budget, *, order: Int = -1) raises PolyError -> Array[_FieldKind[_Kind[_Element[I]]]]

Construct a formal series; integer coefficients promote to QQ.

Parameters.

• I: The inferred coefficient iterable type.

Arguments.

• values: Ascending exact coefficients or a prepared series.
• budget: The shared work allowance, including preparation and result storage.
• order: Known coefficient count; omit only when a prepared series supplies it. An explicit lower order truncates inputs.

Returns. An immutable series retaining its unknown-tail order.

Raises.

• PolyError: DOMAIN for incompatible inputs or unavailable divisions, LIMIT for exhausted work, or CAPACITY for unrepresentable storage.

Defined in src/poly/series.mojo.

add¶

def add[A: Iterable, B: Iterable](a: A, b: B, mut budget: Budget, *, order: Int = -1) raises PolyError -> Array[_FieldKind[_Join[_Kind[_Element[A]], _Kind[_Element[B]]]]]

Add series at a common explicit precision.

Parameters.

• A: The left input iterable type.
• B: The right input iterable type.

Arguments.

• a: The left series or ascending coefficients.
• b: The right series or ascending coefficients.
• budget: The shared work allowance, including preparation and result storage.
• order: Known coefficient count; omit only when a prepared series supplies it. An explicit lower order truncates inputs.

Returns. A new series in the common inferred field.

Raises.

• PolyError: DOMAIN for incompatible inputs or unavailable divisions, LIMIT for exhausted work, or CAPACITY for unrepresentable storage.

Defined in src/poly/series.mojo.

subtract¶

def subtract[A: Iterable, B: Iterable](a: A, b: B, mut budget: Budget, *, order: Int = -1) raises PolyError -> Array[_FieldKind[_Join[_Kind[_Element[A]], _Kind[_Element[B]]]]]

Subtract series at a common explicit precision.

Parameters.

• A: The left input iterable type.
• B: The right input iterable type.

Arguments.

• a: The left series or ascending coefficients.
• b: The right series or ascending coefficients.
• budget: The shared work allowance, including preparation and result storage.
• order: Known coefficient count; omit only when a prepared series supplies it. An explicit lower order truncates inputs.

Returns. A new series in the common inferred field.

Raises.

• PolyError: DOMAIN for incompatible inputs or unavailable divisions, LIMIT for exhausted work, or CAPACITY for unrepresentable storage.

Defined in src/poly/series.mojo.

multiply¶

def multiply[A: Iterable, B: Iterable](a: A, b: B, mut budget: Budget, *, order: Int = -1) raises PolyError -> Array[_FieldKind[_Join[_Kind[_Element[A]], _Kind[_Element[B]]]]]

Multiply modulo the retained power of x.

Parameters.

• A: The left input iterable type.
• B: The right input iterable type.

Arguments.

• a: The left series or ascending coefficients.
• b: The right series or ascending coefficients.
• budget: The shared work allowance, including preparation and result storage.
• order: Known coefficient count; omit only when a prepared series supplies it. An explicit lower order truncates inputs.

Returns. A new series in the common inferred field.

Raises.

• PolyError: DOMAIN for incompatible inputs or unavailable divisions, LIMIT for exhausted work, or CAPACITY for unrepresentable storage.

Defined in src/poly/series.mojo.

divide¶

def divide[A: Iterable, B: Iterable](a: A, b: B, mut budget: Budget, *, order: Int = -1) raises PolyError -> Array[_FieldKind[_Join[_Kind[_Element[A]], _Kind[_Element[B]]]]]

Divide by a series with invertible constant coefficient.

Parameters.

• A: The left input iterable type.
• B: The right input iterable type.

Arguments.

• a: The left series or ascending coefficients.
• b: The right series or ascending coefficients.
• budget: The shared work allowance, including preparation and result storage.
• order: Known coefficient count; omit only when a prepared series supplies it. An explicit lower order truncates inputs.

Returns. A new series in the common inferred field.

Raises.

• PolyError: DOMAIN for incompatible inputs or unavailable divisions, LIMIT for exhausted work, or CAPACITY for unrepresentable storage.

Defined in src/poly/series.mojo.

negative¶

def negative[I: Iterable](values: I, mut budget: Budget, *, order: Int = -1) raises PolyError -> Array[_FieldKind[_Kind[_Element[I]]]]

Negate the known coefficients without changing their order.

Parameters.

• I: The inferred coefficient iterable type.

Arguments.

• values: A prepared series or ascending coefficients.
• budget: The shared work allowance, including preparation and result storage.
• order: Known coefficient count; omit only when a prepared series supplies it. An explicit lower order truncates inputs.

Returns. A new formal series.

Raises.

• PolyError: DOMAIN for incompatible inputs or unavailable divisions, LIMIT for exhausted work, or CAPACITY for unrepresentable storage.

Defined in src/poly/series.mojo.

reciprocal¶

def reciprocal[I: Iterable](values: I, mut budget: Budget, *, order: Int = -1) raises PolyError -> Array[_FieldKind[_Kind[_Element[I]]]]

Invert a series with nonzero constant coefficient.

Parameters.

• I: The inferred input iterable type.

Arguments.

• values: A prepared series or ascending exact coefficients.
• budget: The shared work allowance, including preparation and result storage.
• order: Known coefficient count; omit only when a prepared series supplies it. An explicit lower order truncates inputs.

Returns. A new series with the mathematically available order.

Raises.

• PolyError: DOMAIN for incompatible inputs or unavailable divisions, LIMIT for exhausted work, or CAPACITY for unrepresentable storage.

Defined in src/poly/series.mojo.

compose¶

def compose[A: Iterable, B: Iterable](a: A, b: B, mut budget: Budget, *, order: Int = -1) raises PolyError -> Array[_FieldKind[_Join[_Kind[_Element[A]], _Kind[_Element[B]]]]]

Compose with a zero-constant inner series.

Parameters.

• A: The left input iterable type.
• B: The right input iterable type.

Arguments.

• a: The left series or ascending coefficients.
• b: The right series or ascending coefficients.
• budget: The shared work allowance, including preparation and result storage.
• order: Known coefficient count; omit only when a prepared series supplies it. An explicit lower order truncates inputs.

Returns. A new series in the common inferred field.

Raises.

• PolyError: DOMAIN for incompatible inputs or unavailable divisions, LIMIT for exhausted work, or CAPACITY for unrepresentable storage.

Defined in src/poly/series.mojo.

derivative¶

def derivative[I: Iterable](values: I, mut budget: Budget, *, order: Int = -1) raises PolyError -> Array[_FieldKind[_Kind[_Element[I]]]]

Differentiate, decreasing known order by one.

Parameters.

• I: The inferred input iterable type.

Arguments.

• values: A prepared series or ascending exact coefficients.
• budget: The shared work allowance, including preparation and result storage.
• order: Known coefficient count; omit only when a prepared series supplies it. An explicit lower order truncates inputs.

Returns. A new series with the mathematically available order.

Raises.

• PolyError: DOMAIN for incompatible inputs or unavailable divisions, LIMIT for exhausted work, or CAPACITY for unrepresentable storage.

Defined in src/poly/series.mojo.

integral¶

def integral[I: Iterable](values: I, mut budget: Budget, *, order: Int = -1) raises PolyError -> Array[_FieldKind[_Kind[_Element[I]]]]

Integrate with zero constant, increasing known order by one.

Parameters.

• I: The inferred input iterable type.

Arguments.

• values: A prepared series or ascending exact coefficients.
• budget: The shared work allowance, including preparation and result storage.
• order: Known coefficient count; omit only when a prepared series supplies it. An explicit lower order truncates inputs.

Returns. A new series with the mathematically available order.

Raises.

• PolyError: DOMAIN for incompatible inputs or unavailable divisions, LIMIT for exhausted work, or CAPACITY for unrepresentable storage.

Defined in src/poly/series.mojo.

log¶

def log[I: Iterable](values: I, mut budget: Budget, *, order: Int = -1) raises PolyError -> Array[_FieldKind[_Kind[_Element[I]]]]

Compute the formal logarithm of a unit-constant series.

Parameters.

• I: The inferred input iterable type.

Arguments.

• values: A prepared series or ascending exact coefficients.
• budget: The shared work allowance, including preparation and result storage.
• order: Known coefficient count; omit only when a prepared series supplies it. An explicit lower order truncates inputs.

Returns. A new series with the mathematically available order.

Raises.

• PolyError: DOMAIN for incompatible inputs or unavailable divisions, LIMIT for exhausted work, or CAPACITY for unrepresentable storage.

Defined in src/poly/series.mojo.

exp¶

def exp[I: Iterable](values: I, mut budget: Budget, *, order: Int = -1) raises PolyError -> Array[_FieldKind[_Kind[_Element[I]]]]

Compute the formal exponential of a zero-constant series.

Parameters.

• I: The inferred input iterable type.

Arguments.

• values: A prepared series or ascending exact coefficients.
• budget: The shared work allowance, including preparation and result storage.
• order: Known coefficient count; omit only when a prepared series supplies it. An explicit lower order truncates inputs.

Returns. A new series with the mathematically available order.

Raises.

• PolyError: DOMAIN for incompatible inputs or unavailable divisions, LIMIT for exhausted work, or CAPACITY for unrepresentable storage.

Defined in src/poly/series.mojo.

revert¶

def revert[I: Iterable](values: I, mut budget: Budget, *, order: Int = -1) raises PolyError -> Array[_FieldKind[_Kind[_Element[I]]]]

Invert composition for zero constant and nonzero linear coefficient.

Parameters.

• I: The inferred input iterable type.

Arguments.

• values: A prepared series or ascending exact coefficients.
• budget: The shared work allowance, including preparation and result storage.
• order: Known coefficient count; omit only when a prepared series supplies it. An explicit lower order truncates inputs.

Returns. A new series with the mathematically available order.

Raises.

• PolyError: DOMAIN for incompatible inputs or unavailable divisions, LIMIT for exhausted work, or CAPACITY for unrepresentable storage.

Defined in src/poly/series.mojo.

sqrt¶

def sqrt[I: Iterable](values: I, mut budget: Budget, *, order: Int = -1) raises PolyError -> Array[_FieldKind[_Kind[_Element[I]]]]

Compute the square root of a series whose constant term is one.

Parameters.

• I: The inferred input iterable type.

Arguments.

• values: A prepared series or ascending exact coefficients.
• budget: The shared work allowance, including preparation and result storage.
• order: Known coefficient count; omit only when a prepared series supplies it. An explicit lower order truncates inputs.

Returns. The square root with constant term one, at the same order.

Raises.

• PolyError: DOMAIN for another constant term or a field of characteristic two, LIMIT for exhausted work, or CAPACITY for unrepresentable storage.

Defined in src/poly/series.mojo.

power¶

def power[I: Iterable](values: I, exponent: Int, mut budget: Budget, *, order: Int = -1) raises PolyError -> Array[_FieldKind[_Kind[_Element[I]]]]

Raise a series to a nonnegative integer power at its order.

Parameters.

• I: The inferred input iterable type.

Arguments.

• values: A prepared series or ascending exact coefficients.
• exponent: A nonnegative exponent; zero returns one.
• budget: The shared work allowance, including preparation and result storage.
• order: Known coefficient count; omit only when a prepared series supplies it. An explicit lower order truncates inputs.

Returns. The truncated power at the same order.

Raises.

• PolyError: DOMAIN for a negative exponent, LIMIT for exhausted work, or CAPACITY for unrepresentable storage.

Defined in src/poly/series.mojo.

truncate¶

def truncate[k: Int](values: Array[k], order: Int, mut budget: Budget) raises PolyError -> Array[k]

Lower a series order without inventing unknown coefficients.

Parameters.

• k: The inferred coefficient field.

Arguments.

• values: The prepared input series.
• order: A nonnegative order no greater than the input order.
• budget: The shared work allowance, including preparation and result storage.

Returns. A new series at the requested order.

Raises.

• PolyError: DOMAIN for incompatible inputs or unavailable divisions, LIMIT for exhausted work, or CAPACITY for unrepresentable storage.

Defined in src/poly/series.mojo.

coefficients¶

def coefficients[k: Int](values: Array[k], mut budget: Budget) raises PolyError -> Values[_Scalar[k], k]

Materialize every known coefficient, including implicit trailing zeros.

Parameters.

• k: The inferred coefficient field.

Arguments.

• values: The prepared input series.
• budget: The shared work allowance, including preparation and result storage.

Returns. An immutable scalar sequence of length order().

Raises.

• PolyError: DOMAIN for incompatible inputs or unavailable divisions, LIMIT for exhausted work, or CAPACITY for unrepresentable storage.

Defined in src/poly/series.mojo.

to_polynomial¶

def to_polynomial[k: Int](values: Array[k], mut budget: Budget) raises PolyError -> dense.Array[k]

Copy the known coefficients into a polynomial, explicitly discarding the unknown tail.

Parameters.

• k: The inferred coefficient field.

Arguments.

• values: The prepared input series.
• budget: The shared work allowance, including preparation and result storage.

Returns. A canonical polynomial representing only the known part.

Raises.

• PolyError: DOMAIN for incompatible inputs or unavailable divisions, LIMIT for exhausted work, or CAPACITY for unrepresentable storage.

Defined in src/poly/series.mojo.

to_core¶

def to_core[k: Int](values: Array[k], mut budget: Budget, *, variable: Int64 = 0) raises PolyError -> TruncatedSeries[_Field[k]]

Export independent mutable core storage.

Parameters.

• k: The inferred coefficient field.

Arguments.

• values: The prepared input series.
• budget: The shared work allowance, including preparation and result storage.
• variable: The core variable ID assigned to the exported value.

Returns. A core series with the same order and field.

Raises.

• PolyError: DOMAIN for incompatible inputs or unavailable divisions, LIMIT for exhausted work, or CAPACITY for unrepresentable storage.

Defined in src/poly/series.mojo.

from_core¶

def from_core[C: CoefficientField](values: TruncatedSeries[C], mut budget: Budget) raises PolyError -> Array[_CoreKind[C]]

Validate and copy a core series into immutable array storage.

Parameters.

• C: The inferred supported exact coefficient field.

Arguments.

• values: The core series to import.
• budget: The shared work allowance, including preparation and result storage.

Returns. An independent series using array axis zero.

Raises.

• PolyError: DOMAIN for incompatible inputs or unavailable divisions, LIMIT for exhausted work, or CAPACITY for unrepresentable storage.

Defined in src/poly/series.mojo.

Numerical construction uses context=; arithmetic keeps precision explicit on every call. See the numerical tutorial.

NumericArray¶

@fieldwise_init
struct NumericArray[D: NumericDomain](Copyable, Movable, Iterable, Sized, _Record)

Immutable numerical formal coefficients with a known truncation order.

Parameters.

• D: The numerical coefficient domain.

Defined in src/poly/series.mojo.

NumericArray.IteratorType¶

comptime IteratorType[iterable_mut: Bool, //, iterable_origin: Origin[mut=iterable_mut]]: Iterator = _NumericIterator[Self.D, ImmOrigin(iterable_origin)]

Borrow the representation's complete coefficient sequence.

Parameters.

• iterable_mut: Whether the borrowing origin is mutable.
• iterable_origin: The source origin.

NumericArray.order¶

def order(self) -> Int

Return the exponent of the unknown formal tail.

Returns. The n in O(x**n); this is not an analytic error bound.