Complex Numbers¶
The Complex Plane¶
Mathematically, equality comparison between complex numbers depends on the choice of topology. For example, the complex plane has a continuum of infinities; however, when the complex plane is projected onto the surface of a sphere (a stereographic projection commonly referred to as the Riemann sphere), infinities coalesce into a single point at infinity, thus modeling the extended complex plane. For the former, the value
Modeling complex numbers as a Riemann sphere conveys certain mathematical niceties (e.g., well-behaved division by zero and preservation of the identity
In short, given the constraints of floating-point arithmetic and the subtleties of signed zeros, infinities, NaNs, and their interaction, crafting a specification which always yields intuitive results and satisfies all use cases involving complex numbers is not possible. Instead, this specification attempts to follow precedent (e.g., C99, Python, Julia, NumPy, and elsewhere), while also minimizing surprise. The result is an imperfect balance in which certain APIs may appear to embrace the one-infinity model found in C/C++ for algebraic operations involving complex numbers (e.g., considering
Branch Cuts¶
In the mathematical field of complex analysis, a branch cut is a curve in the complex plane across which an analytic multi-valued function is discontinuous. Branch cuts are often taken as lines or line segments, and the choice of any particular branch cut is a matter of convention.
For example, consider the function
Branch cuts do not arise for single-valued trigonometric, hyperbolic, integer power, or exponential functions; however, branch cuts do arise for their multi-valued inverses.
In contrast to real-valued floating-point numbers which have well-defined behavior as specified in IEEE 754, complex-valued floating-point numbers have no equivalent specification. Accordingly, this specification chooses to follow C99 conventions for special cases and branch cuts for those functions supporting complex numbers. For those functions which do not have C99 equivalents (e.g., linear algebra APIs), the specification relies on dominant conventions among existing array libraries.
Warning
All branch cuts documented in this specification are considered provisional. While conforming implementations of the array API standard should adopt the branch cuts described in this standard, consumers of array API standard implementations should not assume that branch cuts are consistent between implementations.
Provided no issues arise due to the choice of branch cut, the provisional status is likely to be removed in a future revision of this standard.
Complex Number Ordering¶
Given a set
Reflexive: for any
in the set, .Transitive: for any
, , and in the set, if and , then .Antisymmetric: for any
and in the set, if and , then .Total Order: in addition to the partial order established by 1-3, for any
and in the set, either or (or both).Compatible with Addition: for all
, , and in the set, if , then .Compatible with Multiplication: for all
, , and in the set, if and , then .
Defining an order relation for complex numbers which satisfies all six properties defined above is not possible. Accordingly, this specification does not require that a conforming implementation of the array API standard adopt any specific complex number order relation.
In order to satisfy backward compatibility guarantees, conforming implementations of the array API standard may choose to define an ordering for complex numbers (e.g., lexicographic); however, consumers of the array API standard should not assume that complex number ordering is consistent between implementations or even supported.
If a conforming implementation chooses to define an ordering for complex numbers, the ordering must be clearly documented.
Valued-based Promotion¶
According to the type promotion rules described in this specification (see Type Promotion Rules), only the data types of the input arrays participating in an operation matter, not their values. The same principle applies to situations in which one or more results of operations on real-valued arrays are mathematically defined in the complex domain, but not in their real domain.
By convention, the principal square root of sqrt()
, the output array must also be real-valued, even if the input array contains negative values. Accordingly, if a consumer of a conforming implementation of this specification desires for an operation’s results to include the complex domain, the consumer should first cast the input array(s) to an appropriate complex floating-point data type before performing the operation.