torch.nonzero
function nonzero<S extends Shape, D extends DType, Dev extends DeviceType>(input: Tensor<S, D, Dev>, options?: NonzeroOptions): Promise<Tensor | Tensor[]>function nonzero<S extends Shape, D extends DType, Dev extends DeviceType>(input: Tensor<S, D, Dev>, as_tuple: boolean, options?: NonzeroOptions): Promise<Tensor | Tensor[]>Returns indices of all non-zero elements in a tensor.
Finds all positions where tensor values are non-zero. Can return results in two formats: a 2-D tensor of coordinates (default) or a tuple of 1-D coordinate arrays (one per dimension). Useful for finding sparse tensor locations, extracting non-zero elements, and working with conditional masks. Essential for:
- Sparse data handling: Locating non-zero values in sparse tensors or weight matrices
- COO format conversion: Converting dense to sparse coordinate format
- Conditional indexing: Finding where a condition is true (e.g., gradients > 0)
- Activation analysis: Which neurons/weights are active (non-zero)
- Data extraction: Getting positions of important values above threshold
- Sparse updates: Identifying which elements to update in sparse operations
Note: This is an async function because it requires reading data from GPU to CPU.
- Async function: Requires GPU→CPU data transfer, so it's async (must await)
- Output dtype: Always returns int32 indices, regardless of input dtype
- Empty tensor: Returns shape [0, D] if no non-zero elements (empty coordinates)
- Format flexibility: as_tuple=true is useful for working with separate coordinate arrays
- Performance: Reading all data to CPU can be slow for large tensors; consider sparse operations
- GPU transfer: This function requires reading all data from GPU, which can be slow
- Memory overhead: Returns indices as int32 arrays, potentially large for dense tensors
Parameters
inputTensor<S, D, Dev>- The input tensor (any shape, any dtype)
optionsNonzeroOptionsoptional- Optional settings for nonzero
Returns
Promise<Tensor | Tensor[]>– Promise resolving to either: - Tensor of shape [N, D] where N=number of non-zero elements, D=number of dimensions (as_tuple=false) - Array of D tensors, each of shape [N], one per dimension (as_tuple=true)Examples
// Find all non-zero positions in a matrix
const x = torch.tensor([[1, 0, 0], [0, 2, 0], [0, 0, 3]]);
// Return as 2-D coordinate tensor (N × D)
const coords = await torch.nonzero(x);
// [[0, 0], [1, 1], [2, 2]] - shape [3, 2]
// Return as tuple of 1-D tensors (one per dimension)
const [rows, cols] = await torch.nonzero(x, { as_tuple: true });
// rows: [0, 1, 2]
// cols: [0, 1, 2]
// Find activations above threshold
const activations = torch.randn(10, 20);
const activeIndices = await torch.nonzero(activations.gt(0));
console.log(`Active neurons: ${activeIndices.shape[0]}`);
// Convert to sparse format (row indices, col indices, values)
const sparse = torch.tensor([[1, 0, 2], [0, 5, 0], [0, 0, 3]]);
const [row_idx, col_idx] = await torch.nonzero(sparse, { as_tuple: true });
const values = sparse[row_idx, col_idx]; // Get values at non-zero positionsSee Also
- PyTorch torch.nonzero()
- where - Get values and indices where condition is true
- argwhere - Alternative: always returns 2-D tensor format
- masked_select - Extract non-zero values without indices
- sparse_coo_tensor - Create sparse tensor from indices and values