Reshape

Shipping

reshape

Re-lay a flat row-major array under a new shape (numpy reshape); rank picks Vector/Matrix/Tensor

Signature

Inputs

aVector|Matrix|Tensorrequired— The array to reshape. Read as a single flat, row-major (C-order) buffer regardless of its current rank.

Outputs

resultVector|Matrix|Tensor— Same data, new declared shape. Output variant is chosen by the rank of `shape`: 1 → Vector, 2 → Matrix, 3+ → Tensor.

Parameters

Key	Type	Default	Notes
`shape`	text	-1	Comma-separated target dimensions, numpy-style (e.g. `3, 4` or `2, 3, 4`). Exactly one axis may be `-1` to be inferred from the element count. `-1` alone flattens to a 1-D Vector. The total element count must match exactly — a mismatch is an error, never a silent crop.

Description

Reshape re-lays the SAME flat, row-major (C-order) buffer under a new shape — the exact contract of numpy.reshape. The element count is invariant; only the declared dimensionality changes, so the operation is a pure metadata rewrite of an unchanged data vector: no value is moved, copied out of order, or recomputed. This makes it O(1) in data motion — the flat buffer is passed through byte-for-byte.

The rank of the requested shape selects the output variant: a 1-element shape yields a Vector, a 2-element shape a Matrix($rows \times cols$), and 3+ a Tensor with C-order strides. The shape string mirrors numpy exactly — "-1, 4" fixes 4 columns and solves for the rows; "-1" flattens; "2, 3, 4" builds a 3-D tensor.

Exactly one -1 is permitted (two would be ambiguous). The inferred axis must divide the element count evenly and the product of the explicit dims must divide $n$ — otherwise an InvalidParam error is raised ("cannot reshape array of size N into shape ..."), never a silent truncation.

Unit handling: only Vector carries a unit field, so a Vector→Vector reshape preserves the unit, while reshaping OUT of a Vector into a Matrix/Tensor (or flattening a Matrix/Tensor back to a Vector) yields a dimensionless result. Re-attach a unit downstream with set_unit if you reshape out of a grid.

Mathematics

prod (shape) = n, n = len(data)

shape [k] = - 1 \Rightarrow shape [k] = \frac{n}{\prod _{j \neq = k} shape [ j ]}

Examples

Vector to matrix (row-major)

A 6-element Vector [1,2,3,4,5,6] with shape = "2, 3" becomes a 2×3 Matrix laid out row-major:

1 2 3
4 5 6

The flat buffer is identical to the input; only the declared shape changes.

Infer a dimension with -1

12 elements with shape = "-1, 4" fixes 4 columns and solves $12/4 = 3$ rows → a 3×4 Matrix. shape = "3, -1" gives the same result the other way around.

Flatten a grid

A 2×3 Matrix with shape = "-1" collapses to a length-6 Vector. Because Matrix carries no unit, the result is dimensionless — pipe it through set_unit to re-attach one.

Applications

Turning a 1-D acquisition buffer into a frame/channel grid (e.g. reshape a raster scan into an image-like Matrix).
Preparing a Vector as a batch of fixed-length windows (`-1, window_len`) before matrix or tensor math.
Collapsing a Matrix or Tensor back to a flat Vector for a 1-D processing stage.
Adapting data rank to match a downstream node that expects a specific dimensionality.

Neat

Because the data model stores Matrix and Tensor row-major already, reshape is the identity permutation of the flat array — it never touches a single float, only the shape metadata.

The `-1` inference and the divisibility checks are numpy-exact, so behaviour transfers 1:1 from any numpy prototype.

Vector/Matrix/Tensor carry no σ² or timestamp arrays, so a reshape is trivially uncertainty- and time-coherent: there is nothing to permute.

Known issues

Reshaping out of (or into) a Vector drops the physical unit because Matrix and Tensor have no unit field — re-attach it with `set_unit` if the dimension matters downstream.

A `-1` paired with an explicit zero-size axis is rejected as ambiguous (matching numpy), even when the array is empty.