poly.mojo v1.0.2
Search /
API reference

Value serialization

poly.io saves complete values: dense and sparse polynomials, formal series, Newton/Chebyshev/Bernstein representations, rational functions, supported coefficient scalars, checked results, and shaped batches of these values. Nested batches work as well. Records retain exact domains, representation metadata, algebraic witnesses, and stored numerical formats.

Use io.loads[type_of(value)](text) when restoring an existing type, or name the concrete type directly, such as series.Array[1] for a rational series. The reader validates that the record matches that type. Construction and arithmetic keep their usual domain inference and explicit precision contexts.

All calls accept a shared Budget or max_steps=. Incremental readers also accept max_field_bytes=. See saving and restoring values for examples, transport behavior, and the difference between value records and the existing coefficient-array records.

dumps

def dumps[T: Copyable & Deinitable](value: T, mut budget: Budget) raises PolyError -> String

Serialize a complete value to versioned text.

Parameters.

  • T: The concrete value type, usually inferred on write or supplied as type_of(value) on read.

Arguments.

  • value: A prepared polynomial, series, basis, rational function, supported scalar, or batch.
  • budget: The shared work allowance, including decoding and validation.

Returns. Version-one text with a final newline.

Raises.

  • PolyError: ENCODING for malformed or incompatible records, DOMAIN for invalid settings or inputs, or LIMIT/CAPACITY on resource limits.

Defined in src/poly/io.mojo.

loads

def loads[T: Copyable & Deinitable](text: String, mut budget: Budget, *, max_field_bytes: Int = 16777216) raises PolyError -> T

Validate and restore a value from versioned text.

Parameters.

  • T: The concrete value type, usually inferred on write or supplied as type_of(value) on read.

Arguments.

  • text: One complete record produced by this namespace.
  • budget: The shared work allowance, including decoding and validation.
  • max_field_bytes: Maximum bytes per input field; defaults to 16 MiB.

Returns. An independent value with its domain, metadata, and stored precision preserved.

Raises.

  • PolyError: ENCODING for malformed or incompatible records, DOMAIN for invalid settings or inputs, or LIMIT/CAPACITY on resource limits.

Defined in src/poly/io.mojo.

dump

def dump[T: Copyable & Deinitable, S: PolynomialTextSink](value: T, mut sink: S, mut budget: Budget) raises PolyError

Stream a complete value, including its representation metadata.

Parameters.

  • T: The concrete value type, usually inferred on write or supplied as type_of(value) on read.
  • S: The text transport implementation.

Arguments.

  • value: A prepared polynomial, series, basis, rational function, supported scalar, or batch.
  • sink: The text sink receiving fields in order; a failure can leave partial output.
  • budget: The shared work allowance, including decoding and validation.

Raises.

  • PolyError: ENCODING for malformed or incompatible records, DOMAIN for invalid settings or inputs, or LIMIT/CAPACITY on resource limits.

Defined in src/poly/io.mojo.

load

def load[T: Copyable & Deinitable, S: PolynomialTextSource](var source: S, mut budget: Budget, *, max_field_bytes: Int = 16777216) raises PolyError -> T

Validate and restore a value from arbitrary text chunks.

Parameters.

  • T: The concrete value type, usually inferred on write or supplied as type_of(value) on read.
  • S: The text transport implementation.

Arguments.

  • source: An owned source ending immediately after this record.
  • budget: The shared work allowance, including decoding and validation.
  • max_field_bytes: Maximum bytes per input field; defaults to 16 MiB.

Returns. An independent value with its domain, metadata, and stored precision preserved.

Raises.

  • PolyError: ENCODING for malformed or incompatible records, DOMAIN for invalid settings or inputs, or LIMIT/CAPACITY on resource limits.

Defined in src/poly/io.mojo.

dump and load and the coefficient-record dump and load functions in poly.dense and poly.sparse exchange text through these two protocols. Import them from polynomials and implement them over your file, network, or other storage.

PolynomialTextSink

trait PolynomialTextSink

Consume canonical text chunks without retaining the complete record.

Defined in src/polynomials/text_stream.mojo.

PolynomialTextSink.write

def write(mut self, var chunk: String, mut budget: Budget) raises PolyError

Consume the next owned text chunk in order.

Arguments.

  • chunk: The next portion of the version-one record.
  • budget: The shared transport allowance.

Raises.

  • PolyError: ENCODING for transport failure or LIMIT on exhaustion.

PolynomialTextSource

trait PolynomialTextSource(Movable, Deinitable)

Supply arbitrary UTF-8 chunks of one canonical polynomial record.

Defined in src/polynomials/text_stream.mojo.

PolynomialTextSource.read

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

Read the next owned text chunk.

Arguments.

  • budget: The shared transport allowance.

Returns. A chunk, possibly empty, or None at the end of input.

Raises.

  • PolyError: ENCODING for transport failure or LIMIT on exhaustion.

Checked archives support exact.Result, exact real and complex root sets, interval counts, reusable Sturm plans and their counts, accepted root covers, multiplicities, diagnostics, successful polishing results, specialization results, CAD results, rational partial fractions and Laurent expansions, and polynomial or fraction enclosure results. This includes algebraic covers with conversion witnesses, AA specialization transcripts, and adaptive quotient outcomes with or without a finite enclosure. The reader restores their evidence and runs the corresponding independent checker. It does not rerun the producing solver. Unsupported result types fail at compilation; records with rejected evidence fail with ENCODING.

Certificate archives have their own versioned CHECKED-* type tag inside the value framing. CAD decompositions and full coverings now write CHECKED-3, with compact final data or an explicitly tagged legacy payload. Their readers also accept the old CHECKED-1 records and independently check the retained evidence without rerunning construction. Older readers reject the new tag. Selective solutions remain CHECKED-2. Keep the producing package version alongside long-lived archives; the tag is based on the Mojo type name plus an explicit axis count and is not a cross-version ABI promise.

CAD decomposition, solution, and covering archives retain any fixed= coordinate bindings with their exact witnesses. Loading verifies the geometry on that slice and rejects evidence for a different conjugate. Existing CAD archives without user-fixed coordinates remain readable; older library versions reject the new coordinate-scope records.