Tensor Stack

Shipping

tensor_stack

Stack up to four equal-shaped arrays along a NEW axis (numpy stack); result rank is ndim+1

Signature

Inputs

aVector|Matrix|Tensorrequired— First array to stack.
bVector|Matrix|Tensorrequired— Second array; must share `a`'s exact shape.
cVector|Matrix|Tensor— Optional third array of the same shape.
dVector|Matrix|Tensor— Optional fourth array of the same shape.

Outputs

resultMatrix|Tensor— The stacked array, rank ndim+1. The new axis length equals the number of wired inputs.

Parameters

Key	Type	Default	Notes
`axis`	int	0	Position of the NEW axis in the result (0..=ndim). All inputs must share the same shape.

Description

Tensor Stack joins up to four equal-shaped inputs along a freshly-inserted axis, exactly like numpy's stack. Inputs a and b are required; c and d are optional. Because a brand-new axis is created, the result rank is $ndim + 1$ , and the new axis's length equals the number of wired inputs.

The axis parameter chooses where the new axis is inserted (valid range $0 \dots ndim$ ): axis = 0 stacks the inputs as leading slices, higher values interleave the new axis deeper. All inputs must share the same shape — unlike tensor_concat, no dimension is extended in place.

Unit handling: if every stacked input carries the same unit it is kept; a disagreement yields a dimensionless result. (The module note describes stacking as producing a dimensionless result in the mixed case.)

Mathematics

stack (a, b, \dots; axis = k) : shape_{out} = (s_{0}, \dots, s_{k - 1}, M, s_{k}, \dots, s_{n - 1})

M = # {wired inputs}, rank_{out} = rank_{in} + 1

(result)_{\dots, m, \dots} = input_{m} (the m -th operand becomes slice m of the new axis)

Examples

Two vectors into a matrix

Wire [1,2,3] into a and [4,5,6] into b with axis = 0. A new leading axis of length 2 is inserted, giving the $2 \times 3$ matrix:

[[1, 2, 3],
 [4, 5, 6]]

Column stacking

The same two vectors with axis = 1 insert the new axis last, producing a $3 \times 2$ matrix [[1,4],[2,5],[3,6]] — the operands become columns instead of rows.

Assembling a 3-channel image

Stack three equal-shaped $H \times W$ matrices (R, G, B planes) into a, b, c with axis = 2. The result is an $H \times W \times 3$ tensor — a channels-last image cube.

Applications

Building a batch axis by stacking several equal-shaped samples for vectorized downstream reduction.
Assembling multi-channel data (e.g. RGB planes, or x/y/z component grids) into one higher-rank tensor.
Turning a set of equal-length vectors into a matrix whose orientation (rows vs columns) is chosen by the axis parameter.

Neat

Stack shares its input-gathering and shared-unit logic with tensor_concat (it imports collect_arrays and shared_input_unit), so wiring and unit rules stay identical between the two join nodes.

Unwired optional ports are simply skipped when collecting operands, so the new-axis length adapts to how many inputs you actually connect (2, 3, or 4).

The distinction from concat is exact: stack always adds a dimension (ndim+1), concat never does — the same operands give a rank-3 vs rank-2 result respectively.

Known issues

All wired inputs must have identical shape; any mismatch is an error (stack cannot broadcast, unlike tensor_math).

Mixed input units collapse the result to dimensionless rather than raising, so a unit typo silently drops dimensions.

axis must lie in 0..=ndim; a value outside that range is invalid for the resulting rank.