Mark the new tensor APIs as experimental for .NET 9

[tannergooding]

Marking Tensor<T> as [Experimental]

Expanding .NET to provide built-in types for exchanging tensor data across libraries and allowing accelerated handling for core operations is an important but large undertaking. The work done in .NET 9 currently encompasses 8 types and nearly 600 new public APIs, many of which are generic and can support arbitrary T or T constrained to one of the generic math interfaces (see https://learn.microsoft.com/en-us/dotnet/standard/generics/math).

Due to the size of this work and the recognized importance of it to the long term growth of the .NET ecosystem, it has been decided to mark these new APIs as [Experimental] (see https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.codeanalysis.experimentalattribute) for .NET 9 and to plan on supporting them officially in .NET 10 instead. This is not being done due to a lack of confidence in the direction we're going, but rather is explictly being done to allow time for additional feedback from the community and important libraries in the .NET ecosystem that plan on taking advantage of the provided functionality. It also gives us additional time to coordinate with improvements to the C# language to ensure a great end-to-end experience.

Call to Action

Please try out the new APIs and provide feedback on the overall experience. This includes (but is not limited to) the naming or shape of APIs, any core functionality that appears to be missing or that behaves unexpectedly, and how the general user experience was.

Some additional callouts include:

• Despite being marked [Experimental] much of the surface is relatively stable and isn't expectied to change, there isn't much you can get wrong for an API like Add(x, y) after all. This isn't a guarantee that we won't change such APIs, but the expected churn for these ones is minimal.
• There's known missing functionality such as no operator support given that we want Tensor<T> to work over all T but operator + can only be defined for types that implement the generic math IAdditionOperators interface. This requires language support for extension operators to achieve.
• The TensorSpan<T> types can wrap native allocations, but we don't have a non-ref struct type equivalent. Such a type would need to be disposable and needs additional design consideration around how ownership/lifetime tracking works. If this is an important scenario to you, we'd like to hear about it.
• The names/concepts used for some APIs can be very inconsistent across the entire machine learning ecosystem (both inside and outside .NET) and in many cases we opted choose the name that was most consistent with existing .NET concepts or behavior. This decision is typically matching the same semantics given to other major tensor libraries, but if there are any quirks or unexpected behaviors found then we'd like to hear about it.

TensorPrimitives is stable and improved

As a final note, the TensorPrimitives class which we shipped in .NET 8 is stable and has been expanded in .NET 9 with additional API surface that is also considered stable. It is the class that contains most of the accelerated algorithms that underpin the Tensor<T> type and so they can still be used to accelerate your code where applicable. There are many potential applications for these algorithms including in machine learning/AI, image processing, games, and beyond.

[dotnet-issue-labeler]

Note regarding the new-api-needs-documentation label:

This serves as a reminder for when your PR is modifying a ref *.cs file and adding/modifying public APIs, please make sure the API implementation in the src *.cs file is documented with triple slash comments, so the PR reviewers can sign off that change.

[dotnet-issue-labeler]

Note regarding the new-api-needs-documentation label:

This serves as a reminder for when your PR is modifying a ref *.cs file and adding/modifying public APIs, please make sure the API implementation in the src *.cs file is documented with triple slash comments, so the PR reviewers can sign off that change.

[tannergooding]

CC. @terrajobst, I don't think we have an existing format for these. So I've somewhat just followed what some other users (ASP.NET/Azure) are doing here.

Namely, SNT for System.Numerics.Tensors, then EXP for Experimental, then 0001 since this is the first ID.

[tannergooding]

The wording we get from this resembles:

SNTEXP0001: 'System.Numerics.Tensors.IReadOnlyTensor<System.Numerics.Tensors.Tensor<T>, T>' is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.

[jeffhandley]

@terrajobst Should we instead use SYSLIB5### to follow suit of Obsoletions (SYSLIB0###) and Analyzers (SYSLIB1###) and leave plenty of room for analyzers?

[terrajobst]

I think we should stick to SYSLIB for all diagnostics (obsoletions, experimental, and analyzers).

My concern with having separate prefixes is that it will be very inconsistent across all the parties. It's hard enough to come up with a prefix that is short enough and identifies a single party that can keep track of the numbers to avoid duplicates. Asking folks to have separate prefixes for obsoletions, experimental, and general purposes analyzers and have that scheme make sense across all parties, is a bit too much IMHO. And frankly it doesn't seem to add much more value to the consumer as the way a given diagnostic needs to be addressed often differs between different cases within the same category anyway. So the expectation is: read the message and follow the link if you need more information.

I don't have strong opinions on whether we should use numeric ranges for the different categories; if having separate ranges makes our lives easier (or is more consistent with what we have done before), then let's do that. If not, I don't think it's worth introducing though.

[tannergooding]

CC. @michaelgsharp, @stephentoub, @ericstj, @jeffhandley, @luisquintanilla

[michaelgsharp]

LGTM.

[michaelgsharp]

Though it does seem to be failing some builds having that annotation there for some reason.

[eiriktsarpalis]

If we're using the markdown file as the source of truth for claiming new diagnostic IDs, what's the need for also consolidating them in source? IIRC we don't do this for other diagnostics.

[jeffhandley]

We do this with Obsoletions as well. I assert that it has helped keep the process discoverable and consistent.

[eiriktsarpalis]

Why do we need to mark internal types?

[tannergooding]

That's just the way the analyzer currently works. Presumably to ensure that consumers of those internal types are also aware that its using experimental features

[tannergooding]

/backport to release/9.0-preview7

[github-actions]

Started backporting to release/9.0-preview7: https://github.com/dotnet/runtime/actions/runs/10069224280

[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.