Skip to content

Commit be7b579

Browse files
Fix tensor shape consistency and native-width traversal (dotnet#135060)
## Summary Make tensor shape handling consistent across broadcasting, elementwise operations, copies, equality, reshaping, axis operations, and views: - Treat default rank-zero empty values as effective shape `[0]`, without changing their stored `Rank`, `Lengths`, or `Strides`. Only redundant leading singleton axes can be added or removed; explicit zero axes and non-leading singleton axes remain significant. Stack and concatenate interpret axes using the first input's effective shape. - Fix all ten internal `Any` span kernels to traverse the input length and handle empty inputs correctly. - Keep empty view origins within source storage, handle zero-containing shape products without intermediate overflow, and retain native-sized counts and offsets instead of narrowing them prematurely. - Preserve overlap-safe ordering for native-width dense copies. Index-of-min/max reductions reuse `TensorPrimitives` for dense spans, dense suffixes, and bounded gathered blocks, preserving first-NaN, tie, signed-zero, and magnitude semantics. - Share concatenation validation and copying, avoid revalidating prepared stack inputs, and remove redundant shape comparisons after alignment. Caller-supplied destinations retain shape and overlap validation before writes. This includes behavioral compatibility changes, not new public API. Some formerly inconsistent shape combinations are now accepted or rejected according to the shared rules. For example, default empty values can explicitly broadcast to `[2, 0]`, while binary operations with `[0, 2]` reject the incompatible trailing dimension. Unsupported overlapping layouts and self-overlapping output layouts throw before writing. The README and affected API remarks document the shape and storage contracts; breaking-change documentation is required after merge. ## Validation - Release build of the tensor solution passed across its target frameworks. - Full suites passed normally and with hardware intrinsics disabled: **6,266 net11.0 tests and 200 net481 tests** per run, with no failures or skips. - Regression coverage includes default/ranked empties, leading-padding alignment, dense and strided destinations, rejection before writes, native-width logical counts, forced chunk boundaries, NaNs/ties, high ranks, and protected-memory boundaries. - Two consecutive independent shape/storage audit passes covered **149,246 cases each**, with no failures; the second used software intrinsics. ## Performance Local BenchmarkDotNet comparisons used Windows x64, a Ryzen 9 7950X, and the .NET 11 RC SDK/runtime. For a native-width broadcast view with shape `[nint.MaxValue / 1024, 1024]`, strides `[0, 1]`, and a NaN at the end of the first dense suffix, `IndexOfMax` measured **295 ns** with dense-suffix primitive dispatch versus **4,050 ns** with an elementwise native-width fallback. This compares dispatch strategies and early NaN termination, not full traversal of a multi-gigabyte allocation or throughput against upstream's length-narrowing path. Concatenation, stack, and dispatch comparisons retained the same allocation counts. Separate-process timings varied substantially and some apparent regressions reversed with run order. A same-process comparison using separately loaded assemblies measured row dispatch at **326 -> 309 ns** for rank 2 and **351 -> 356 ns** for rank 6, within measurement variability. No general throughput improvement is claimed for the validation simplification or metadata snapshots. > [!NOTE] > This pull request was authored with assistance from GitHub Copilot. Co-authored-by: Copilot App <[email protected]>
1 parent f98a059 commit be7b579

10 files changed

Lines changed: 1903 additions & 429 deletions

File tree

‎src/libraries/System.Numerics.Tensors/README.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,30 @@ Some shape and storage behavior intentionally differs from NumPy:
77
- Creating a tensor from an empty shape (`[]`) produces shape `[0]`, with no elements. In NumPy,
88
shape `()` has rank zero but contains one scalar element; `np.empty(())` leaves that element
99
uninitialized ("empty" refers to initialization, not the number of elements).
10+
- `Tensor<T>.Empty` and default tensor spans retain rank-zero metadata but contain no
11+
elements, unlike NumPy's scalar shape `()`. Tensor computations treat them as empty
12+
vectors with effective shape `[0]`, corresponding to NumPy's `(0,)`. This includes
13+
equality, broadcasting, reshaping, stacking, concatenation, splitting, slicing, and
14+
dimension operations. Explicitly ranked empty shapes retain their axes.
1015
- Squeezing shape `[1, 1]` produces shape `[1]`, rather than NumPy's rank-zero shape `()`.
1116
Both contain one element and can broadcast as a scalar; code that inspects rank, selects
1217
axes, or indexes the result must account for the retained dimension.
18+
- Directional broadcasting can discard excess leading singleton dimensions. For example,
19+
a source with shape `[1, 1, 3]` can broadcast into destination shape `[3]`, whereas
20+
NumPy's `broadcast_to` rejects a target with fewer dimensions than the source.
21+
This also applies to tensor copies and elementwise operations with supplied destinations.
22+
Only leading singleton dimensions are redundant: `[2, 1]` and `[1, 2]` are distinct,
23+
and zero-length dimensions cannot be discarded. Source metadata and explicitly requested
24+
destination shapes are preserved.
25+
- Shape equality also ignores leading singleton padding, without broadcasting other
26+
dimensions. Stacking requires equivalent input shapes; concatenation requires matching
27+
aligned dimensions except along its selected axis. These operations use the first
28+
input's effective shape to interpret the axis and determine the result's rank. Other
29+
inputs and supplied destinations can add or omit leading singleton padding, but cannot
30+
omit significant axes. For example, stacking `[2]` with `[1, 2]` at axis `0` produces
31+
`[2, 2]`, while stacking `[1, 2]` with `[2]` at axis `0` produces `[2, 1, 2]`: inserting
32+
the new axis makes the first input's retained singleton axis non-leading. Existing
33+
axes are not renumbered or removed from the first input.
1334
- Strides must be nonnegative. NumPy can represent a reversed view with a negative stride
1435
(for example, `array[::-1]`); use `Tensor.ReverseDimension` with dimension `0` to
1536
reverse the first axis instead. This produces a new tensor, not a reversed view.
@@ -25,6 +46,16 @@ When strides are omitted, a shape containing a zero-length dimension has zero st
2546
in every dimension. Its element count and storage requirement are zero regardless of
2647
the other dimension lengths. Negative lengths remain invalid, and explicitly supplied
2748
strides must still satisfy the normal layout validation.
49+
Empty slices and empty dimension views retain their source's storage origin: endpoint
50+
ranges do not move an empty view beyond its backing storage.
51+
52+
Native-backed tensor spans can have more than `int.MaxValue` logical elements. Operations
53+
retain native-sized lengths and offsets, using bounded spans or indexed iteration rather
54+
than narrowing the total element count. Dense copies preserve overlap-safe ordering.
55+
Index-of-min/max reductions use `TensorPrimitives` over dense spans and dense suffixes.
56+
Other layouts retain the flattened primitive path for span-sized inputs and use bounded
57+
gathered blocks for native-width inputs. Chunk results retain logical native-sized indexes,
58+
including first-NaN and tie handling.
2859

2960
Overlapping sources and destinations are supported for equal-length dense copies, which
3061
use the same overlap-safe behavior as `Span<T>.CopyTo`, and for elementwise operations on identical

‎src/libraries/System.Numerics.Tensors/src/System/Numerics/Tensors/netcore/Common/TensorPrimitives.IIndexOfMinMaxOperator.cs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ namespace System.Numerics.Tensors
99
{
1010
public static unsafe partial class TensorPrimitives
1111
{
12-
private interface IIndexOfMinMaxOperator<T>
12+
internal interface IIndexOfMinMaxOperator<T>
1313
{
1414
static abstract T Aggregate(Vector128<T> value);
1515
static abstract T Aggregate(Vector256<T> value);
@@ -20,7 +20,7 @@ private interface IIndexOfMinMaxOperator<T>
2020
static abstract Vector512<T> Compare(Vector512<T> x, Vector512<T> y);
2121
}
2222

23-
private static int IndexOfMinMaxCore<T, TOperator>(ReadOnlySpan<T> x)
23+
internal static int IndexOfMinMaxCore<T, TOperator>(ReadOnlySpan<T> x)
2424
where T : INumber<T> where TOperator : struct, IIndexOfMinMaxOperator<T>
2525
{
2626
if (x.IsEmpty)

‎src/libraries/System.Numerics.Tensors/src/System/Numerics/Tensors/netcore/ReadOnlyTensorDimensionSpan_1.cs‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -18,16 +18,24 @@ public readonly ref struct ReadOnlyTensorDimensionSpan<T>
1818

1919
internal ReadOnlyTensorDimensionSpan(ReadOnlyTensorSpan<T> tensor, int dimension)
2020
{
21-
if ((uint)dimension >= tensor.Rank)
21+
int rank = tensor.Rank;
22+
if (rank == 0)
23+
{
24+
tensor = new ReadOnlyTensorSpan<T>(in tensor._reference, TensorShape.Normalize(tensor._shape));
25+
rank = tensor.Rank;
26+
}
27+
28+
if ((uint)dimension >= rank)
2229
{
2330
ThrowHelper.ThrowArgumentOutOfRangeException();
2431
}
2532
dimension += 1;
2633

34+
ReadOnlySpan<nint> lengths = tensor.Lengths;
2735
_tensor = tensor;
28-
_length = TensorShape.GetProduct(tensor.Lengths[..dimension]);
36+
_length = TensorShape.GetProduct(lengths[..dimension]);
2937
_dimension = dimension;
30-
_sliceShape = TensorShape.Create((dimension != tensor.Rank) ? tensor.Lengths[dimension..] : [1], tensor.Strides[dimension..], tensor.IsPinned);
38+
_sliceShape = TensorShape.Create((dimension != rank) ? lengths[dimension..] : [1], tensor.Strides[dimension..], tensor.IsPinned);
3139
}
3240

3341
/// <summary>Gets <c>true</c> if the slices that exist within the tracked dimension are dense; otherwise, <c>false</c>.</summary>

‎src/libraries/System.Numerics.Tensors/src/System/Numerics/Tensors/netcore/ReadOnlyTensorSpan_1.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -243,7 +243,7 @@ public unsafe ReadOnlyTensorSpan(T* data, nint dataLength, scoped ReadOnlySpan<n
243243

244244
internal ReadOnlyTensorSpan(ref readonly T data, nint dataLength, scoped ReadOnlySpan<nint> lengths, scoped ReadOnlySpan<nint> strides, bool pinned)
245245
{
246-
_shape = TensorShape.Create(in data, dataLength, lengths, strides, pinned);
246+
_shape = TensorShape.CreateForView(dataLength, lengths, strides, pinned);
247247
_reference = ref Unsafe.AsRef(in data);
248248
}
249249

0 commit comments

Comments
 (0)