torch.block_diag
Create a block diagonal matrix from provided tensors.
Constructs a large matrix with input tensors arranged along the main diagonal, with zeros filling the off-diagonal blocks. The input tensors are flattened to 1D and then arranged on the diagonal of the output 2D matrix.
Commonly used for:
- Constructing block-diagonal matrices for structured linear algebra
- Creating block-structured neural network architectures
- Combining independent linear transformations
- Building Kronecker products and tensor network structures
- Efficient sparse matrix representations
- Input tensors are flattened before being placed on diagonal
- Output is always 2D
- All inputs must be same dtype
- Zero matrix returned for empty input list
- Total elements = sum of all input tensor sizes
Parameters
tensorsTensor[]- One or more input tensors to place on the diagonal. Each tensor is flattened and placed along the diagonal.
Returns
Tensor– 2D tensor where each input tensor is placed on the diagonal block, with zeros elsewhere. Total shape is [sum(flattened sizes), sum(flattened sizes)].Examples
// Basic 2x2 and 1x3 block on diagonal
const a = torch.tensor([[1, 2], [3, 4]]);
const b = torch.tensor([[5, 6, 7]]);
const result = torch.block_diag(a, b);
// [[1, 2, 0, 0, 0],
// [3, 4, 0, 0, 0],
// [0, 0, 5, 6, 7]]
// Multiple matrices
const x = torch.tensor([[1, 2], [3, 4]]);
const y = torch.tensor([[5]]);
const z = torch.tensor([[6, 7], [8, 9]]);
const result = torch.block_diag(x, y, z);
// With 3D tensors (flattened to 1D on diagonal)
const a = torch.randn(2, 3, 4); // Flattened to 24 elements
const b = torch.randn(5); // Already 1D
const result = torch.block_diag(a, b); // [29, 29]See Also
- PyTorch torch.block_diag()
- diag - Create diagonal matrix from 1D tensor
- diag_embed - Embed diagonals in 2D planes of higher-dimensional tensor
- eye - Create identity matrix