Batch maps, broadcasting, and reductions¶
poly.batch applies budget-aware functions to shaped collections of values.
The tutorial explains shape rules, traversal
order, callback signatures, and empty inputs.
reduce accepts axis= as an integer, a tuple or finite iterable of integers,
Optional[Int], or None for all axes. keepdims=True retains reduced axes
with size 1. Negative axes count from the end; duplicate and out-of-range axes
raise DOMAIN. Each output is a row-major left fold from its own initial.
Without either shape keyword, reduce returns one value. Supplying axis or
keepdims returns a batch, including a zero-dimensional batch when all axes
are removed. Array.item() extracts the only value from a one-item result.
An empty axis selection applies function(initial, item) independently to each
input; an empty reduced group returns initial without calling the function.
Save and restore these values with poly.io.
Array¶
@fieldwise_init
struct Array[T: Copyable & Deinitable](Copyable, Movable, Iterable, Sized, _Record)
An immutable row-major batch; each item can be an entire polynomial.
Parameters.
T: The scalar or batch item type.
Defined in src/poly/batch.mojo.
Array.IteratorType¶
comptime IteratorType[iterable_mut: Bool, //, iterable_origin: Origin[mut=iterable_mut]]: Iterator = _Iterator[Self.T, ImmOrigin(iterable_origin)]
A row-major iterator over the logical batch, including broadcast views.
Parameters.
iterable_mut: Whether the borrowing source origin allows mutation.iterable_origin: The lifetime of the borrowed source.
Returns. The borrowing iterator type.
Array.ndim¶
def ndim(self) -> Int
Return the number of batch dimensions.
Returns. The number of batch axes.
Array.shape¶
def shape(self) -> ref[ImmOrigin(origin_of(self._layout[].shape))] List[Int]
Borrow the immutable batch shape.
Returns. An immutable reference to the logical dimensions.
Array.item¶
def item(self, mut budget: Budget) raises PolyError -> Self.T
Copy the only item of a batch containing exactly one value.
Arguments.
budget: The shared allowance for locating and copying the item.
Returns. The value, independent of the batch rank.
Raises.
PolyError: DOMAIN unless the batch has one item, or LIMIT on exhausted work.
Array.item¶
def item(self, *, max_steps: UInt64 = UInt64.MAX) raises PolyError -> Self.T
Copy the only item, including the result of an all-axis reduction.
Arguments.
max_steps: The copying allowance; defaults to UInt64.MAX.
Returns. The value, independent of the batch rank.
Raises.
PolyError: DOMAIN unless the batch has one item, or LIMIT on exhausted work.
asarray¶
def asarray[I: Iterable](values: I, mut budget: Budget, *, shape: Optional[List[Int]] = None) raises PolyError -> Array[downcast[_Element[I], Copyable & Deinitable]]
Collect one pass of batch items; shape defaults to a one-dimensional batch.
Parameters.
I: The inferred input iterable type.
Arguments.
values: Input coefficients, sparse terms, or prepared values as required by this overload.budget: The shared work allowance, including preparation, computation, and result storage.shape: The row-major batch dimensions; the product must match the logical item count.
Returns. An immutable prepared array in the selected domain or batch shape.
Raises.
PolyError: DOMAIN for invalid or incompatible input, or LIMIT/CAPACITY on resource limits.
Defined in src/poly/batch.mojo.
scalar¶
def scalar[T: Copyable & Deinitable](value: T, mut budget: Budget) raises PolyError -> Array[T]
Make a zero-dimensional batch that broadcasts one value.
Parameters.
T: The scalar or batch item type.
Arguments.
value: The value to convert or inspect.budget: The shared work allowance, including preparation, computation, and result storage.
Returns. A zero-dimensional batch sharing one logical item.
Raises.
PolyError: DOMAIN for invalid or incompatible input, or LIMIT/CAPACITY on resource limits.
Defined in src/poly/batch.mojo.
broadcast_to¶
def broadcast_to[T: Copyable & Deinitable](values: Array[T], shape: List[Int], mut budget: Budget) raises PolyError -> Array[T]
Create a shared view using NumPy's trailing-axis broadcasting rules.
Parameters.
T: The scalar or batch item type.
Arguments.
values: Input coefficients, sparse terms, or prepared values as required by this overload.shape: The row-major batch dimensions; the product must match the logical item count.budget: The shared work allowance, including preparation, computation, and result storage.
Returns. A shared broadcast view with the requested shape.
Raises.
PolyError: DOMAIN for invalid or incompatible input, or LIMIT/CAPACITY on resource limits.
Defined in src/poly/batch.mojo.
vmap¶
def vmap[T: Copyable & Deinitable, R: Copyable & Deinitable](function: def(x: T, mut budget: Budget) raises PolyError thin -> R, values: Array[T], mut budget: Budget) raises PolyError -> Array[R]
Apply a budget-aware function to every batch item, preserving shape.
Parameters.
T: The scalar or batch item type.R: The callback result type.
Arguments.
function: A thin Mojo callback with a final shared Budget argument and typed PolyError failures.values: Input coefficients, sparse terms, or prepared values as required by this overload.budget: The shared work allowance, including preparation, computation, and result storage.
Returns. Callback results in row-major order and the resulting broadcast shape.
Raises.
PolyError: DOMAIN for invalid or incompatible input, or LIMIT/CAPACITY on resource limits.
Defined in src/poly/batch.mojo.
outer¶
def outer[A: Copyable & Deinitable, B: Copyable & Deinitable, R: Copyable & Deinitable](function: def(a: A, b: B, mut budget: Budget) raises PolyError thin -> R, a: Array[A], b: Array[B], mut budget: Budget) raises PolyError -> Array[R]
Apply a binary function to every pair; the output shape concatenates both shapes.
Parameters.
A: The first input type.B: The second input type.R: The callback result type.
Arguments.
function: A thin Mojo callback with a final shared Budget argument and typed PolyError failures.a: The first input value.b: The second input value.budget: The shared work allowance, including preparation, computation, and result storage.
Returns. Every pairwise result with the concatenated input shapes.
Raises.
PolyError: DOMAIN for invalid or incompatible input, or LIMIT/CAPACITY on resource limits.
Defined in src/poly/batch.mojo.
reduce¶
def reduce[T: Copyable & Deinitable](function: def(a: T, b: T, mut budget: Budget) raises PolyError thin -> T, values: Array[T], initial: T, mut budget: Budget) raises PolyError -> T
Fold row-major batch items from an explicit initial value, including empty batches.
Parameters.
T: The scalar or batch item type.
Arguments.
function: A thin Mojo callback with a final shared Budget argument and typed PolyError failures.values: Input coefficients, sparse terms, or prepared values as required by this overload.initial: The initial accumulator, also returned for an empty reduction.budget: The shared work allowance, including preparation, computation, and result storage.
Returns. The final left-fold accumulator.
Raises.
PolyError: DOMAIN for invalid or incompatible input, or LIMIT/CAPACITY on resource limits.
Defined in src/poly/batch.mojo.
accumulate¶
def accumulate[T: Copyable & Deinitable](function: def(a: T, b: T, mut budget: Budget) raises PolyError thin -> T, values: Array[T], initial: T, mut budget: Budget) raises PolyError -> Array[T]
Return each running row-major fold result in the original batch shape.
Parameters.
T: The scalar or batch item type.
Arguments.
function: A thin Mojo callback with a final shared Budget argument and typed PolyError failures.values: Input coefficients, sparse terms, or prepared values as required by this overload.initial: The initial accumulator, also returned for an empty reduction.budget: The shared work allowance, including preparation, computation, and result storage.
Returns. Each running fold result in the original batch shape.
Raises.
PolyError: DOMAIN for invalid or incompatible input, or LIMIT/CAPACITY on resource limits.
Defined in src/poly/batch.mojo.
accumulate accepts one integer axis, including negative axes, or
Optional[Int]. It starts each line from initial and returns the original
shape. axis=None and the call without axis use one flattened scan. Invalid
axes raise DOMAIN; Boolean, floating-point, tuple, and iterable axes are
rejected at compilation.