[API Proposal]: Non-generic Tensor base type

[michaelgsharp]

Background and motivation

We currently do not have a non-generic base type for Tensor. This is fine, but there are many times you need info about the Tensor (its rank, lengths of dimenions, etc) and you can get this info without needing to know or care about the generic type itself. We need to add a base type that will better facilitate this.

I've added some basic access via boxing for the most general applications.

API Proposal

namespace System.Numerics.Tensors;

// All of these existed in higher types. Just creating a new base type and moving these down.
+ public interface IReadOnlyTensor
+ {
+    /// <summary>
+   /// Gets a value that indicates whether the collection is currently empty.
+    /// </summary>
+    bool IsEmpty { get; }
    
+     /// <summary>
+     /// Gets a value that indicates whether the underlying buffer is pinned.
+     /// </summary>
+     bool IsPinned { get; }
    
+     /// <summary>
+     /// Gets the number of elements in the tensor.
+     /// </summary>
+     nint FlattenedLength { get; }
    
+     /// <summary>
+     /// Gets the number of dimensions in the tensor.
+     /// </summary>
+     int Rank { get; }
    
+     /// <summary>
+     /// Gets the length of each dimension in the tensor.
+     /// </summary>
+     [UnscopedRef]
+     ReadOnlySpan<nint> Lengths { get; }
    
+     /// <summary>
+     /// Gets the stride of each dimension in the tensor.
+     /// </summary>
+     [UnscopedRef]
+     ReadOnlySpan<nint> Strides { get; }
    
+     /// <summary>
+     /// Gets the value at the specified indexes.
+     /// </summary>
+     /// <param name="indexes">The indexes to be used.</param>
+     object this[params scoped ReadOnlySpan<nint> indexes] { get; }
    
+     /// <summary>
+     /// Gets the value at the specified indexes.
+     /// </summary>
+     /// <param name="indexes">The indexes to be used.</param>
+     object this[params scoped ReadOnlySpan<NIndex> indexes] { get; }
+ }

+ public interface ITensor : IReadOnlyTensor
+ {
+     /// <summary>
+     /// Gets the value at the specified indexes.
+     /// </summary>
+     /// <param name="indexes">The indexes to be used.</param>
+     object this[params scoped ReadOnlySpan<nint> indexes] { get; set; }
    
+     /// <summary>
+     /// Gets the value at the specified indexes.
+     /// </summary>
+     /// <param name="indexes">The indexes to be used.</param>
+     object this[params scoped ReadOnlySpan<NIndex> indexes] { get; set; }

+     /// <summary>
+     /// Gets a value that indicates whether the collection is read-only.
+     /// </summary>
+     bool IsReadOnly { get; }

+     /// <summary>
+     /// Clears the tensor.
+     /// </summary>
+     void Clear();

+     /// <summary>
+     /// Fills the contents of this tensor with the given value.
+     /// </summary>
+     void Fill(object value);
+ }

// And we are removing these methods from the typed base interfaces
public interface IReadOnlyTensor<TSelf, T> : IReadOnlyTensor, IEnumerable<T>
        where TSelf : IReadOnlyTensor<TSelf, T>
{
-    /// <summary>
-    /// Gets a value that indicates whether the collection is currently empty.
-    /// </summary>
-    bool IsEmpty { get; }
    
-     /// <summary>
-     /// Gets a value that indicates whether the underlying buffer is pinned.
-     /// </summary>
-     bool IsPinned { get; }
    
-     /// <summary>
-     /// Gets the number of elements in the tensor.
-     /// </summary>
-     nint FlattenedLength { get; }
    
-     /// <summary>
-     /// Gets the number of dimensions in the tensor.
-     /// </summary>
-     int Rank { get; }
    
-     /// <summary>
-     /// Gets the length of each dimension in the tensor.
-     /// </summary>
-     [UnscopedRef]
-     ReadOnlySpan<nint> Lengths { get; }
    
-     /// <summary>
-     /// Gets the stride of each dimension in the tensor.
-     /// </summary>
-     [UnscopedRef]
-     ReadOnlySpan<nint> Strides { get; }
}

public interface ITensor<TSelf, T>  : ITensor, IReadOnlyTensor<TSelf, T>
        where TSelf : ITensor<TSelf, T>
{
-     /// <summary>
-     /// Gets a value that indicates whether the collection is read-only.
-     /// </summary>
-    bool IsReadOnly { get; }

-     /// <summary>
-     /// Clears the tensor.
-     /// </summary>
-     void Clear();
}

API Usage

public void DoStuffWithNonGenericTensor(ITensor tensor);

Tensor<int> tensor = Tensor.Create<int>([1, 2, 3, 4], [2, 2]);

DoStuffWithNonGenericTensor(tensor);

Alternative Designs

We may decide we don't want access to the data via boxing, in which case we can remove those methods.

Risks

Low risk because it's a preview type, but because we are changing the class hierarchy there is more than none.

[michaelgsharp]

@tannergooding

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-numerics-tensors
See info in area-owners.md if you want to be subscribed.

[tannergooding]

We can evaluate whether we need to add more methods, maybe involving boxing, as time goes on.

This notably needs to be decided up front, prior to shipping, as we cannot expose such APIs after we ship it as stable.

Such considerations should likely be part of this API proposal.

[michaelgsharp]

Updated with boxing methods for access.

Background and motivation

We currently do not have a non-generic base type for Tensor. This is fine, but there are many times you need info about the Tensor (its rank, lengths of dimenions, etc) and you can get this info without needing to know or care about the generic type itself. We need to add a base type that will better facilitate this.

I've added some basic access via boxing for the most general applications.

API Proposal

namespace System.Numerics.Tensors;

// All of these existed in higher types. Just creating a new base type and moving these down.
public interface ITensor
{
    /// <summary>
    /// Gets a value that indicates whether the collection is currently empty.
    /// </summary>
    bool IsEmpty { get; }
    
    /// <summary>
    /// Gets a value that indicates whether the underlying buffer is pinned.
    /// </summary>
    bool IsPinned { get; }
    
    /// <summary>
    /// Gets the number of elements in the tensor.
    /// </summary>
    nint FlattenedLength { get; }
    
    /// <summary>
    /// Gets the number of dimensions in the tensor.
    /// </summary>
    int Rank { get; }
    
    /// <summary>
    /// Gets a value that indicates whether the collection is read-only.
    /// </summary>
    bool IsReadOnly { get; }
    
    /// <summary>
    /// Gets the length of each dimension in the tensor.
    /// </summary>
    [UnscopedRef]
    ReadOnlySpan<nint> Lengths { get; }
    
    /// <summary>
    /// Gets the stride of each dimension in the tensor.
    /// </summary>
    [UnscopedRef]
    ReadOnlySpan<nint> Strides { get; }
    
    /// <summary>
    /// Gets the value at the specified indexes.
    /// </summary>
    /// <param name="indexes">The indexes to be used.</param>
    object this[params scoped ReadOnlySpan<nint> indexes] { get; }
    
    /// <summary>
    /// Gets the value at the specified indexes.
    /// </summary>
    /// <param name="indexes">The indexes to be used.</param>
    object this[params scoped ReadOnlySpan<NIndex> indexes] { get; }
    
    /// <summary>
    /// Gets the values at the specified ranges.
    /// </summary>
    /// <param name="ranges">The ranges to be used.</param>
    ITensor this[params scoped ReadOnlySpan<NRange> ranges] { get; }
    
    /// <summary>
    /// Slices the tensor using the specified start indexes.
    /// </summary>
    /// <param name="start">The start locations to be used.</param>
    /// <returns>The sliced tensor.</returns>
    ITensor Slice(params scoped ReadOnlySpan<nint> start);
    
    /// <summary>
    /// Slices the tensor using the specified start indexes.
    /// </summary>
    /// <param name="startIndex">The start indexes to be used.</param>
    /// <returns>The sliced tensor.</returns>
    ITensor Slice(params scoped ReadOnlySpan<NIndex> startIndex);
    
    /// <summary>
    /// Slices the tensor using the specified ranges.
    /// </summary>
    /// <param name="range">The ranges to be used.</param>
    /// <returns>The sliced tensor.</returns>
    ITensor Slice(params scoped ReadOnlySpan<NRange> range);
    
    // TODO: We will also want to pin this when we approve the api that does pinning.
}

API Usage

public void DoStuffWithNonGenericTensor(ITensor tensor);

Tensor<int> tensor = Tensor.Create<int>([1, 2, 3, 4], [2, 2]);

DoStuffWithNonGenericTensor(tensor);

Alternative Designs

We may decide we don't want access to the data via boxing, in which case we can remove those methods.

Risks

Low risk because it's a preview type, but because we are changing the class hierarchy there is more than none.

[bartonjs]

Video

Looks good as proposed

namespace System.Numerics.Tensors;

+ public interface IReadOnlyTensor
+ {
+     bool IsEmpty { get; }
+     bool IsPinned { get; }
+     nint FlattenedLength { get; }
+     int Rank { get; }

+     [UnscopedRef]
+     ReadOnlySpan<nint> Lengths { get; }
    
+     [UnscopedRef]
+     ReadOnlySpan<nint> Strides { get; }
    
+     object this[params scoped ReadOnlySpan<nint> indexes] { get; }
+     object this[params scoped ReadOnlySpan<NIndex> indexes] { get; }
+ }

+ public interface ITensor : IReadOnlyTensor
+ {
+     object this[params scoped ReadOnlySpan<nint> indexes] { get; set; }
+     object this[params scoped ReadOnlySpan<NIndex> indexes] { get; set; }

+     bool IsReadOnly { get; }
+     void Clear();
+     void Fill(object value);
+ }

public interface IReadOnlyTensor<TSelf, T> : IReadOnlyTensor, IEnumerable<T>
    where TSelf : IReadOnlyTensor<TSelf, T>
{
-     bool IsEmpty { get; }
-     bool IsPinned { get; }
-     nint FlattenedLength { get; }
-     int Rank { get; }

-     [UnscopedRef]
-     ReadOnlySpan<nint> Lengths { get; }
    
-     [UnscopedRef]
-     ReadOnlySpan<nint> Strides { get; }
}

public interface ITensor<TSelf, T>  : ITensor, IReadOnlyTensor<TSelf, T>
        where TSelf : ITensor<TSelf, T>
{
-     bool IsReadOnly { get; }
-     void Clear();
}