YouTip

## PyTorch torch.row_stack In PyTorch, `torch.row_stack` is a utility function used to stack a sequence of tensors vertically (row-wise) to form a single tensor. It is an alias for `torch.vstack` and behaves identically to it. This function is highly useful when you want to combine multiple feature vectors or matrices along their first dimension (rows). --- ### Function Definition ```python torch.row_stack(tensors, *, out=None) -> Tensor ``` ### Parameters * **`tensors`** *(Sequence)*: A sequence of tensors to stack (such as a list or tuple). The tensors must have the same shape along all dimensions except the first dimension (vertical axis). * **`out`** *(Tensor, optional)*: The output tensor. ### Return Value * A new stacked `Tensor` formed by stacking the input tensors row-wise. --- ### Behavior with Different Dimensions * **1D Tensors:** Stacking 1D tensors of shape `(N,)` results in a 2D tensor of shape `(M, N)`, where `M` is the number of input tensors. * **2D Tensors:** Stacking 2D tensors of shape `(R, C)` results in a 2D tensor of shape `(total_R, C)`, where `total_R` is the sum of the rows of all input tensors. * **3D and Higher Tensors:** Stacking occurs along the first dimension (index 0). --- ## Code Examples The following examples demonstrate how to use `torch.row_stack` with 1D and 2D tensors, and verify its equivalence to `torch.vstack`. ```python import torch # 1. Stacking 1D Tensors (Row-wise) x1 = torch.tensor([1, 2, 3]) x2 = torch.tensor([4, 5, 6]) result_1d = torch.row_stack([x1, x2]) print("--- 1D Tensor Row Stacking ---") print(f"x1: {x1}") print(f"x2: {x2}") print(f"Result:\n{result_1d}\n") # 2. Stacking 2D Tensors (Row-wise) y1 = torch.tensor([[1, 2, 3]]) y2 = torch.tensor([[4, 5, 6]]) result_2d = torch.row_stack([y1, y2]) print("--- 2D Tensor Row Stacking ---") print(f"y1:\n{y1}") print(f"y2:\n{y2}") print(f"Result:\n{result_2d}\n") # 3. Equivalence to torch.vstack z1 = torch.tensor([1, 2, 3]) z2 = torch.tensor([4, 5, 6]) result_vstack = torch.vstack([z1, z2]) result_row_stack = torch.row_stack([z1, z2]) print("--- Equivalence Check ---") print(f"vstack output: {result_vstack.tolist()}") print(f"row_stack output: {result_row_stack.tolist()}") ``` ### Output ```text --- 1D Tensor Row Stacking --- x1: tensor([1, 2, 3]) x2: tensor([4, 5, 6]) Result: tensor([[1, 2, 3], [4, 5, 6]]) --- 2D Tensor Row Stacking --- y1: tensor([[1, 2, 3]]) y2: tensor([[4, 5, 6]]) Result: tensor([[1, 2, 3], [4, 5, 6]]) --- Equivalence Check --- vstack output: [[1, 2, 3], [4, 5, 6]] row_stack output: [[1, 2, 3], [4, 5, 6]] ``` --- ## Key Considerations 1. **Alias of `torch.vstack`**: `torch.row_stack` is fully equivalent to `torch.vstack`. You can use either depending on which naming convention fits your codebase better (e.g., matching NumPy's `np.row_stack`). 2. **Dimension Matching**: Except for the stacking dimension (the first dimension), all other dimensions of the input tensors must match exactly. For example, you cannot stack a tensor of shape `(2, 3)` with a tensor of shape `(2, 4)` using `row_stack`. 3. **Memory Copy**: Like most stacking operations in PyTorch, `torch.row_stack` typically returns a new tensor with copied data. If you are working with large datasets, keep memory allocation in mind.