Module structure 

Plans for structural operations: take and drop, rotate and reverse, windows, transpose and catenate. A plan gives the result’s layout, and Steps that read the result’s items from the argument’s items in order. gather::walk copies a compact array by a plan, and basedpl copies its other arrays by the same plan. Each plan checks its arguments.

Structs

Count

A count that an argument gives, such as a take’s or a diagonal’s offset: its sign and magnitude.

Plan

A structural result’s layout, and the steps that read its items from the argument. The steps’ lengths multiply to the result’s item count, outermost first. One entry can cover several result axes.

Routes

The selectors of a selection by written parts (routes): one for each axis of the layout that sources regroups the source into, with the source axes that each reads, and whether the selection reads one item, one position on every source axis in order.

Slide

A fold along one or two axes of a copy whose axes walk windows of its source, run as sliding folds over the source’s rows without building the windows (crate::reduce::sliding and crate::reduce::sliding_2d). Walk classifies the copy. Each folded axis is a window’s axis that moves one position at a time along its source axis. The copy’s other axes along that source axis move by 1, where the windows slide, or by whole windows, where they tile it, as pooling’s do. basedpl folds its pending copies of windows this way, and the Python API its views of windows.

Walk

How a copy walks its source: one entry for each axis of the copy, the source axis that each entry walks, and the offset of the positions on source axes that no entry walks. Axes that walk one source axis together read windows, as Windows::plan lays them out. Every reader of windows from Steps classifies them here: Walk::read gives what the axes along one source axis read.

WindowAxis

One axis of windows: windows of size items, each step items after the last. A padded axis has a window centred on every stepth position, and reads past its ends by its edge mode.

Windows

Windows over the leading axes of an array of one shape: a WindowAxis for each, and the lengths that windowed gives, the frame that counts the windows along each axis followed by the shape of one window.

Enums

Edge

How a position outside an axis maps to one inside it, as edge modes of padding do. Fill gives no position, which reads the fill.

Edged

The positions that Edge::positions gives: each item’s position on the axis, or floats where some item reads the fill, with NaN there.

IndexPart

Written index parts, before the selected axes and their lengths are known.

Selector

One independent axis selector. Positions are zero-based and already normalized; a range can walk backwards. All keeps the whole axis, whatever its length. An index array replaces its axis by the axes of its layout. Its positions, a Table, lie within the axis or are Steps::FILL, which reads the caller’s fill. The code that builds an index array checks its positions, as index_positions and index_table do. NewAxis inserts a length-one axis without consuming an input axis.

Constants

NOT_WHOLE

The message of the Domain error for an index value that isn’t a whole number.

Functions

addressed

The first axis of layout that each selector addresses, given the name of each selector’s one named axis, where it has exactly one, and the number of axes it covers, where more axes than remain cover the rest, as a coordinate past the last axis does. A selector whose name layout has addresses the axis with that name, unless another selector has the same name. Selectors with the same name take free axes in order, as unnamed selectors and NumPy’s index arrays do. Each other selector takes the first free axes whose names don’t conflict with its name. Either way a selector claims every axis it covers. Two selectors that claim one axis, or a selector with no free axis, give an Index error.

addressed_parts

Routes written parts to source axes without padding them with implicit selectors. Axis payloads give their name and consumed width; returned payloads identify the original part.

catenate

The layout of left and right joined along axis, with the lengths that catenated gives. The joined axis has both sides’ keys, with no key where a side has none, and each other axis has either side’s keys. A name survives where both sides agree.

catenated

The lengths of left and right joined along axis: their lengths along it added. They must have the same rank, and the same lengths on their other axes.

counted_positions

The positions along an axis of length size that signed positions give, as positions gives them, with Steps::FILL for None and for a position outside the axis.

diagonal

A diagonal of two distinct axes, moved to the last result axis. Positive offsets start further along axes[1]; negative ones along axes[0].

diagonal_span

Where diagonal offset of a matrix of rows by cols starts, as a row and a column, and its length. A positive offset starts further along the columns. A negative one starts further down the rows.

expand

Undoes repeat with the same counts: one cell for each count. A positive count gives the first cell it made, and any other count a fill. One count must divide the number of cells. More counts must use every cell, unless the axis has one cell.

extended

The plan that appends the keys in added, a list for each axis, to the axes of layout, as missing_keys gives them. An axis without keys takes them after a position without a key for each of its items. The new positions read Steps::FILL, and the others read the items in place.

float_position

The whole number that a float index value names: the one it equals within tolerance t, the comparison tolerance, which only Mathish makes nonzero. None for a NaN or a value that isn’t whole, which reads the fill. A whole number past i64 saturates, and so lies outside every axis. The one rule for float index values: positions, signed_positions, index_table and Edge::positions read floats through it.

index_claims

Expands Rest once geometry is known, with one source claim per consuming part. Axis payloads identify the original written part.

index_table

A table that reads the index values in values as positions along an axis of length size, as positions reads them. Booleans and integers that all lie inside the axis read in place, each converted as it’s read: the one pass that checks them writes nothing, and also finds whether they give evenly spaced positions, so that a walk can read them as one stride. Floats, read within tolerance t, and values with any outside the axis become the list of positions that positions gives, with the fill position for each value that names none.

key_position

The position of key name on axis of layout, or Steps::FILL where the axis lacks it: a missing key reads the fill and writes nothing, as a position outside the axis does. BPL and both Python bindings read keys by this rule.

key_selector

The selector that keys give on axis of layout, by key_position: one key’s position, which removes the axis, where within is None, and otherwise an index array of the keys’ positions, laid out as within.

missing_keys

For each axis of layout, the keys that wanted names on it and it lacks, each once, in order. wanted pairs an axis with the keys that one selector names on it. A write adds these keys before it plans (extended).

pad

Pads every axis by (before, after) positions, to the lengths that padded gives. Each position past an end reads by edge: the item type’s fill, or a position on the axis. Existing axis keys remain on their positions. Padding a keyed axis by another mode than Edge::Fill repeats keyed positions, which is an error. An axis that pads by nothing keeps a plain walk.

pad_steps

The steps that pad each source axis under its edge mode.

padded

The lengths of shape with widths added before and after each axis.

plan_parts

Plans a selection by written parts on layout, as ⌷ and the Python frontends read brackets. claims give each part’s axis name and width, as for addressed_parts, and explicit its axes. decode(i, axis) gives the selector of written part i at source axis, with whether it reads one position. Axes that no part reaches stay whole, and a part wider than one axis reads its axes as one. Also gives whether the selection reads one item: one position on every source axis, in order. broadcast pairs index arrays as select does. err converts this module’s errors to the caller’s.

plan_routes

The plan of the selection that routes gives on layout, as plan_parts plans it.

position_recipe

Position i on an axis of length size, where a negative i counts back from the end. Adding size to a negative position without a branch keeps a loop over positions vectorised. A position outside the axis is then at least size.

positions

The positions that index values give along an axis of length size. A negative value counts back from the end. A value outside the axis, a float that isn’t a whole number within tolerance t (float_position), or a NaN gives the fill position (Steps::FILL), which reads the fill and writes nothing. Items that aren’t numbers are a Domain error.

regrouped

A layout of shape whose axis i comes from layout’s axes sources[i], as a transpose sends them. An axis with no sources is new, as a split or a merge makes it. A result axis keeps the keys its sources agree on when each source has its length. It keeps the name they agree on, unless names[i] gives one.

repeat

Repeats each cell along axis by its count: one count for every cell, or one for each cell. A negative count gives that many fills in place of its cell. Where the axis has one cell, every count repeats it. A fill has no key, and repeating a keyed position is an error, as it is for selection.

repeated

repeat’s items with no plan to walk: view, the items of layout, with each cell along axis written as many times as its count, a run at a time (gather::repeat, or gather::positions for counts of 0 and 1). None where a count is negative or axis has keys, which repeat’s plan serves.

rotate

Rotates the items along axis, or reverses them when counts is None. counts gives the counts’ shape and items: one count for every lane, or one for each lane in the shape of layout without axis. A lane starts at position count of the axis, counted modulo its length. Keys on the axis move with their items when every lane rotates alike, and are dropped otherwise.

rotate_steps

The steps that rotate an axis by its count, or reverse it when no count is given.

rotated

The lengths of shape rotated along axis, which are its own. frame, the shape of counts that give one count for each lane, must match shape without axis, which is one of its axes.

routes

The routes of a selection by written parts on layout, as plan_parts takes them. claims give each part’s axis name and width, as for addressed_parts, and explicit its axes. decode(i, axis) gives the selector of written part i at source axis, with whether it reads one position. Axes that no part reaches stay whole (Selector::All), and a part wider than one axis reads its axes as one.

select

Selects with one selector for each leading axis of layout, in order, keeping the axes that no selector mentions. A single position removes its axis, and a range keeps it in place. An index array’s axes replace its axis. An unnamed vector keeps the axis’s name and the keys at the positions it selects if none repeats, as a named vector without keys of its own keeps those keys, and an unnamed index array of another rank has plain axes. Index arrays pair, as arguments pair in arithmetic: all of them with broadcast, as .[] reads them, and otherwise those that share an axis name, as ⌷ reads them. Paired index arrays put their axes where the first of them was. A range pairs with an index array that has its axis’s name. Positions that step evenly along each axis read as strides (strided), whether one index array gives them or paired arrays sum to them. One index array whose positions read a stretch of its axis past the ends, as edge modes and positions that count back from the end give them, reads as one padded or rotated entry.

select_axis

select with selector on axis and every other axis whole. A NewAxis goes in before axis.

signed_positions

The signed position that each index value gives, before any axis applies: integers as they are, and floats as float_position reads them within tolerance t, with None for a NaN or a value that isn’t whole. Items that aren’t real numbers have no position. positions reads the values and checks them against an axis in one pass.

sole_name

The name of the one named axis of layout, where it has exactly one.

take

Takes count items along axis for each (axis, count) in counts, at the lengths that taken gives, or drops them when take is false. A negative count works from the end. A take past an end reads fill there. A later count for the same axis replaces an earlier one.

take_steps

The steps that read counts taken from shape, or dropped where take is false, one entry for each axis (take).

taken

The lengths of shape after taking or dropping counts, each along its axis: a take keeps |k| positions, and a drop keeps max(0, n-|k|). A later count for the same axis replaces an earlier one.

transpose

Sends axis i of layout to result axis axes[i], at the lengths that transposed gives. A result axis keeps the keys and name its source axes agree on.

transpose_steps

The steps that read shape transposed by axes, one entry for each result axis (transpose).

transposed

The lengths of shape transposed by axes, which sends axis i to result axis axes[i]. Axes sent to the same result axis select their diagonal, at the shortest of their lengths. Every result axis from 0 to the largest destination needs a source.

walked_source

The row-major shape of a source of len items whose axes the entries of tables step along, for a copy of shape, for a caller that holds a source’s storage without its shape, as a Python view does. It has one axis for each distinct stride, and each axis holds as many items as the next larger stride spans. None where a stride doesn’t divide the next, or len isn’t a whole number of the largest.

window_padding_steps

Pads the positions that windows read, or returns None when no axis pads or there are no windows.

window_steps

The windows’ frame steps followed by the steps within each window.

windowed

The lengths of the windows of shape that axes give along its leading axes: the number of windows along each of those axes, then a window’s lengths. Along an axis of length n, ⌊(n-size)÷step⌋+1 windows fit, or none where size is longer. A padded window is centred on each position, which gives ⌈(n-[size even])÷step⌉ windows. Its size must be less than twice the length of an axis that isn’t empty.