Turn same-shaped samples into a batch by stacking them along a new leading dimension.
Batching
PyTorch · Function
torch.stack
torch.stack combines equally sized tensors by inserting a new dimension. The dim argument chooses where that dimension goes and defaults to 0.
How it works
torch.stack takes a sequence of equally sized tensors and combines them by inserting one new dimension at the position selected by dim. With the default dim=0, the number of input tensors becomes the size of the leading dimension; out can optionally receive the result.
Syntax
torch.stack(*tensors, dim=0, *, out=None)Parameters
| Name | Type | Description |
|---|---|---|
tensors | sequence of Tensors | Sequence of tensors to concatenate. |
dim | int, optional | Dimension at which to insert the new axis; defaults to 0. |
out | Tensor, optional | Optional output tensor. |
Returns
A tensor containing the inputs combined along a new dimension.
Key points
- The operation joins multiple tensors by adding a fresh axis rather than reusing an existing one.
- Omitting dim is equivalent to explicitly passing dim=0.
- The resulting shape can be inspected with the tensor's size method.
- The dim parameter identifies the location of the newly created axis.
Common mistakes
- Every tensor in the input sequence must have identical dimensions and sizes; otherwise stacking is invalid.
- The insertion dimension must be within the inclusive range from zero through the inputs' dimensionality.
Example: Stack tensors along a new dimension
import torch
x = torch.tensor([[1, 2, 3], [4, 5, 6]])
result = torch.stack((x, x), dim=0)
print(result.shape) # torch.Size([2, 2, 3])Creates a new leading dimension containing the two input tensors.
When to use it
Choose a different dim when the new grouping axis belongs elsewhere in the tensor layout.
Axis placement
Use the resulting size to verify that the inserted axis has the expected length.
Shape inspection
Interview questions
QWhat does torch.stack do, and how does it differ conceptually from concatenation?
torch.stack combines a sequence of tensors along a newly inserted dimension. Unlike concatenation along an existing axis, it increases the result rank by one, and all inputs must have the same size.
Follow-up: How does torch.cat differ? torch.cat joins tensors along an existing dimension, whereas torch.stack creates a new one.
QHow does the dim argument affect the output shape?
dim specifies where the new axis is inserted, and it defaults to zero. For two tensors shaped (2, 3), stacking with dim=0 produces a tensor shaped (2, 2, 3).
Follow-up: What happens with dim=2 for those inputs? The result has shape (2, 3, 2), because the new axis is inserted after both original axes.
QWhat are the parameters of torch.stack?
The tensors argument is a sequence of tensors to combine, while out is an optional output tensor. The documented signature is torch.stack(*tensors, dim=0, *, out=None).
Follow-up: What constraint applies to dim? It must be between zero and the number of dimensions of the concatenated inputs, inclusive.
Related
torch.cat