torch.unravel_index accepts a shape containing a zero-sized dimension only when the input indices tensor is empty. With nonempty indices, current PyTorch main rejects the call before coordinate arithmetic, because a shape with zero elements cannot contain any valid flat index.
What torch.unravel_index does
The function converts flat indices into coordinate tensors for a requested shape. It returns one coordinate tensor for each shape dimension, and each output has the same shape as the input indices. The API documentation requires shape dimensions to be nonnegative. PyTorch API documentation and implementation
As an Amazon Associate I earn from qualifying purchases.
How zero-sized dimensions affect the call
The behavior turns on two conditions: whether any requested dimension is zero and whether the indices tensor contains any elements.
Recommended Free Tools
| Shape condition | Indices condition | Current PyTorch main behavior |
|---|---|---|
| All dimensions are positive | Empty or nonempty | Not the zero-dimension edge case; the shape passes the zero-dimension validation. |
| At least one dimension is zero | Empty | Permitted by the current validation. |
| At least one dimension is zero | Nonempty | Rejected with a validation error before coordinate calculation. |
The current implementation checks that dimensions are nonnegative, then requires either every dimension to be positive or the indices tensor to have zero elements. Its error text is shape cannot have zero dimensions when indices is non-empty, with the implementation adding quotation marks and the shape tuple in the rendered message. PyTorch source
#1 Best Overall
Why nonempty indices cannot fit a zero-sized shape
A zero in the shape means the indexed space contains no elements. A nonempty flat-index tensor therefore cannot refer to a valid element in that space. Without an explicit guard, the function could proceed into coordinate arithmetic involving division or remainder by zero rather than returning a direct validation error.
The contribution report describes adding validation before this arithmetic while preserving the empty-index case. That distinction matters: empty indices have no values to map, so allowing them with a zero-sized dimension does not create an invalid flat-element reference. Contribution report
What the contribution changes—and what is confirmed
The contribution author links the validation change to PyTorch PR #191092 and describes it as merged. The available report does not independently establish the PR’s official status, exact merge date, or the first PyTorch release that includes it. The behavior described here is the current main-branch implementation; do not infer a particular released-version boundary from the report alone. Contribution report
Keep the related PyTorch reports separate
PR #189389: validation and error wording
PR #189389 is separate from the contribution report’s PR #191092. Its search-result diff shows a test expecting an error for a nonempty index with shape (2, 0), alongside a source change to validation and error wording. Current main uses the phrasing about “zero dimensions when indices is non-empty”; do not substitute wording from a separate change when explaining present behavior. PyTorch PR #189389
Issue #136736: out-of-bounds indices for nonzero shapes
Issue #136736 reports a different behavior: out-of-bounds indices wrapping for a nonzero shape, in a PyTorch 2.3.0 context. It is adjacent to index validation, but it is not the zero-dimension case discussed here. PyTorch issue #136736
Quick Recap
Practical takeaway for contributors
- When reproducing the zero-dimension case, vary both the shape and the number of elements in the indices tensor; an empty index tensor and a nonempty one are expected to take different paths.
- For a regression test, use a shape with a zero dimension and a nonempty flat index to check that validation rejects the call rather than allowing coordinate arithmetic to fail.
- Keep tests and explanations for out-of-bounds indices with nonzero shapes separate from tests for zero-sized dimensions.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
