YouTip

# PyTorch torch.tril_indices The `torch.tril_indices` function in PyTorch is used to generate the indices of the lower triangular part of a 2D matrix (including the diagonal by default). It returns a 2-tuple of tensors containing the row and column indices of these elements. This function is highly useful for masking operations, extracting lower triangular matrices, or performing operations on symmetric/triangular matrices without allocating memory for unnecessary elements. --- ## Syntax ```python torch.tril_indices(row, column, offset=0, dtype=torch.long, device='cpu', layout=torch.strided) ``` ### Parameter Descriptions | Parameter | Type | Description | | :--- | :--- | :--- | | `row` | `int` | The number of rows in the 2D matrix. | | `column` | `int` | The number of columns in the 2D matrix. | | `offset` | `int` (optional) | The diagonal offset. Default is `0` (main diagonal).
• `offset = 0`: Includes the main diagonal and below.
• `offset > 0`: Includes diagonals above the main diagonal.
• `offset < 0`: Excludes the main diagonal and elements below it up to the offset. | | `dtype` | `torch.dtype` (optional) | The desired data type of returned tensors. Default is `torch.long`. | | `device` | `torch.device` (optional) | The desired device of returned tensors. Default is `'cpu'`. | | `layout` | `torch.layout` (optional) | The desired layout of returned tensors. Default is `torch.strided`. | ### Return Value * Returns a 2-tuple of tensors of shape `(2, N)`, where `N` is the number of elements in the lower triangular part. * The first tensor contains the **row indices**, and the second tensor contains the **column indices**. --- ## Code Examples ### Example 1: Basic Usage (Square Matrix) Generate the lower triangular indices for a $3 \times 3$ matrix. ```python import torch # Generate lower triangular indices for a 3x3 matrix row, col = torch.tril_indices(3, 3) print("row indices:", row) print("col indices:", col) ``` **Output:** ```text row indices: tensor([0, 1, 1, 2, 2, 2]) col indices: tensor([0, 0, 1, 0, 1, 2]) ``` --- ### Example 2: Using Indices for Masking and Assignment You can use the generated indices to directly index into a tensor and modify its values. ```python import torch # Generate indices with an offset of 1 (includes one diagonal above the main diagonal) row, col = torch.tril_indices(3, 3, offset=1) # Create a 3x3 matrix of ones a = torch.ones(3, 3) # Set the elements outside the specified lower triangular area to 0 # Note: To zero out the upper triangular part, we invert the selection logic mask = torch.ones(3, 3) mask[row, col] = 0 print("Mask matrix:") print(mask) ``` **Output:** ```text Mask matrix: tensor([[0., 0., 1.], [0., 0., 0.], [0., 0., 0.]]) ``` --- ### Example 3: Non-Square Matrix `torch.tril_indices` also works seamlessly with non-square matrices. ```python import torch # Generate lower triangular indices for a 3x4 rectangular matrix row, col = torch.tril_indices(3, 4) print("row indices:", row) print("col indices:", col) ``` **Output:** ```text row indices: tensor([0, 1, 1, 2, 2, 2]) col indices: tensor([0, 0, 1, 0, 1, 2]) ``` --- ### Example 4: Using Negative Offset Using a negative offset excludes the main diagonal and elements immediately below it. ```python import torch # Generate lower triangular indices with offset = -1 (excludes the main diagonal) row, col = torch.tril_indices(3, 3, offset=-1) print("row indices:", row) print("col indices:", col) ``` **Output:** ```text row indices: tensor([1, 2, 2]) col indices: tensor([0, 0, 1]) ``` --- ## Considerations 1. **Memory Efficiency**: `torch.tril_indices` returns only the coordinate indices rather than a full dense mask matrix. This is highly memory-efficient when working with large sparse matrices. 2. **Device Allocation**: If you are performing operations on a GPU, make sure to set `device='cuda'` inside `torch.tril_indices` to avoid unnecessary CPU-to-GPU data transfer overhead. 3. **Relationship with `torch.tril`**: While `torch.tril` zeroes out elements of an existing tensor, `torch.tril_indices` provides the raw coordinate indices, which is useful for advanced indexing, sparse tensor creation, and custom loss functions (e.g., calculating pairwise distances without duplicates).