Make Complex<T> conform to C23 Annex G special values

[tannergooding]

This makes Complex<T> (and, by delegation, the non-generic Complex) conform to the C23 Annex G (IEC 60559-compatible complex arithmetic) special-value requirements for signed zeros, infinities, and NaNs. Complex numbers are outside the scope of IEEE 754 itself, so Annex G is the relevant specification of the special-value behavior IEEE 754 otherwise implies for the scalar operations these build on. The non-generic Complex defers most of its implementation to Complex<double>, so the conformance flows through to the shipped type.

The elementary functions (Sqrt, Exp, Log/Log10, and the trig / hyperbolic / inverse-trig functions) gain Annex G prologues for non-finite and overflowing inputs while leaving the finite numeric cores untouched.

---

operator * gains the Annex G.5.1 infinity recovery so an infinite operand produces a directed infinity instead of a spurious NaN; it is bit-exact to the Annex G reference over the full special-value grid.

operator / keeps Smith's formula with the recovery layered on top. It is normatively conformant and stays accurate for large-magnitude dividends where the illustrative Annex G reference algorithm would overflow; it differs from that reference only in the sign of a zero-valued quotient component, which Annex G explicitly leaves unspecified.

The scalar Complex<T> * T / Complex<T> / T operators and Reciprocal route through the complex path so their special-value behavior stays consistent, and Pow defers non-finite or magnitude-overflowing inputs to Exp(power * Log(value)), matching cpow's cexp(w * clog(z)) special values.

---

A new generic special-value harness exercises Multiply / Divide / Reciprocal / Abs (and the elementary functions) across Complex<double>, Complex<float>, and Complex<Half>, with the expected values generated from an independent literal Annex G reference. The legacy non-generic oracles that computed NaN or overflowed on the special rows now defer to that harness.

This is a behavioral (breaking) change for special-value inputs to Complex arithmetic and math functions: many of these previously returned NaN where Annex G requires a directed infinity, a signed zero, or a specific signed result.

Breaking-change documentation: dotnet/docs#54845.

Full System.Runtime.Numerics suite: 8368 passing, 0 failed, 0 skipped.

Note

This PR description was drafted with the assistance of GitHub Copilot.

[azure-pipelines]

Azure Pipelines:
Successfully started running 3 pipeline(s).
13 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[dotnet-policy-service]

Added needs-breaking-change-doc-created label because this PR has the breaking-change label.

When you commit this breaking change:

1. Create and link to this PR and the issue a matching issue in the dotnet/docs repo using the breaking change documentation template, then remove this needs-breaking-change-doc-created label.
2. Ask a committer to mail the .NET Breaking Change Notification DL.

Tagging @dotnet/compat for awareness of the breaking change.

[Copilot]

Pull request overview

This PR updates System.Numerics.Complex<T> (and, by delegation, System.Numerics.Complex) to follow C23 Annex G special-value behavior (signed zeros, infinities, NaNs) across arithmetic and elementary functions, and adds/updates tests to validate the new directed results.

Changes:

• Implement Annex G.5.1-style special-value recovery for Complex<T> multiply/divide and add Annex G prologues for several elementary functions.
• Route non-generic Complex operators and math functions through Complex<double> to pick up the updated special-value behavior.
• Add a new special-value test harness exercising Complex<double/float/Half> over a full special-value grid and adjust existing tests/oracles to defer to it.

Show a summary per file

File	Description
src/libraries/System.Runtime.Numerics/src/System/Numerics/Complex.Generic.cs	Adds Annex G special-value handling to core operators and selected elementary functions for Complex<T>.
src/libraries/System.Runtime.Numerics/src/System/Numerics/Complex.cs	Delegates non-generic Complex operations to Complex<double> to inherit the updated behavior.
src/libraries/System.Runtime.Numerics/tests/ComplexTests.SpecialValues.cs	New exhaustive special-value conformance harness (double/float/Half) using an independent reference.
src/libraries/System.Runtime.Numerics/tests/ComplexTests.cs	Updates/relaxes legacy test oracles and expectations to align with Annex G special-value behavior.
src/libraries/System.Runtime.Numerics/tests/System.Runtime.Numerics.Tests.csproj	Includes the new ComplexTests.SpecialValues.cs test file in the test project.

Copilot's findings

Comments suppressed due to low confidence (1)

src/libraries/System.Runtime.Numerics/src/System/Numerics/Complex.Generic.cs:335

• operator /(Complex<T>, T) now always promotes the scalar divisor to a complex value and routes through the full Complex/Complex divide path. That adds extra work to the common finite, non-zero divisor case. A simple fast path for finite inputs can keep the new Annex-G behavior (via the fallback) without regressing typical scalar-division performance.

        {
            // Promote to (right + 0i) so Annex G special-value behavior stays consistent
            // with the Complex/Complex operator.
            return left / new Complex<T>(right, T.Zero);
        }

• Files reviewed: 5/5 changed files
• Comments generated: 2

[Copilot]

Copilot's findings

• Files reviewed: 5/5 changed files
• Comments generated: 5

[Copilot]

Copilot's findings

Comments suppressed due to low confidence (1)

src/libraries/System.Runtime.Numerics/tests/ComplexTests.SpecialValues.cs:55

• Same as the unary Verify overload: the tuple-form context string uses default double formatting, which loses the -0.0 sign and makes sign-of-zero failures hard to interpret. It’s worth preserving negative-zero in the printed input tuples for these special-value tests.

        private static void Verify<T>(Func<Complex<T>, Complex<T>, Complex<T>> op, string name, double leftReal, double leftImaginary, double rightReal, double rightImaginary, double expectedReal, double expectedImaginary, bool exactZeroSign)
            where T : IFloatingPointIeee754<T>, IMinMaxValue<T>
        {
            Complex<T> left = new Complex<T>(T.CreateTruncating(leftReal), T.CreateTruncating(leftImaginary));
            Complex<T> right = new Complex<T>(T.CreateTruncating(rightReal), T.CreateTruncating(rightImaginary));
            Complex<T> actual = op(left, right);
            string context = $"{name}<{typeof(T).Name}>(({leftReal}, {leftImaginary}), ({rightReal}, {rightImaginary})).";
            AssertSame(actual.Real, expectedReal, context + "Real", exactZeroSign);
            AssertSame(actual.Imaginary, expectedImaginary, context + "Imaginary", exactZeroSign);

• Files reviewed: 5/5 changed files
• Comments generated: 3

[Copilot]

Copilot's findings

• Files reviewed: 5/5 changed files
• Comments generated: 1

[Copilot]

Copilot's findings

• Files reviewed: 5/5 changed files
• Comments generated: 1

[Copilot]

Copilot's findings

Comments suppressed due to low confidence (1)

src/libraries/System.Runtime.Numerics/src/System/Numerics/Complex.Generic.cs:327

• This comment says the zero-divisor recovery produces a "directed infinity", but ∞ * 0 still yields NaN for zero dividend components (and NaN dividend components remain NaN). Consider rewording to reflect that this branch scales the dividend by a directed infinity (producing infinities and/or NaNs depending on the dividend components).

            if ((c == T.Zero) && (d == T.Zero) && (!T.IsNaN(a) || !T.IsNaN(b)))
            {
                // Divisor is zero and the dividend is not fully NaN: directed infinity.
                T inf = T.CopySign(T.PositiveInfinity, c);
                x = inf * a;
                y = inf * b;

• Files reviewed: 5/5 changed files
• Comments generated: 1

[azure-pipelines]

Azure Pipelines:
Successfully started running 3 pipeline(s).
13 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[eiriktsarpalis]

Do we need a feature switch so that users can flip back to the old semantics, or is this going to be too complicated to maintain going forward?

[eiriktsarpalis]

Do we need a feature switch so that users can flip back to the old semantics, or is this going to be too complicated to maintain going forward?

Having taken a closer look, I understand that the divergences specifically concern special value recovery. Given you've factored these into distinct methods, a feature flag seems potentially feasible.

[tannergooding]

Having taken a closer look, I understand that the divergences specifically concern special value recovery. Given you've factored these into distinct methods, a feature flag seems potentially feasible.

Given this is a correctness fix, the default preference is to not opportunistically provide anything here, but it is something we could consider if enough feedback is given.

Such switches often introduce problems because its typically an all or non global switch for the program, which can fix some and break others, particularly for math oriented APIs like this. So we typically recommend users who are truly dependent on the old behavior to roll their own helper functions for just their code by copying the old (MIT licensed) implementation (which is often a trivial 1-2 lines).