RFC: Adding complex number support to the specification

[kgryte]

Complex Number Support

Plan for complex number support in the array API specification.

What follows is a plan for adding complex number support to the 2022 array API specification. This RFC is comprised of the following sections:

• Prior discussions
• High-level summary concerns and questions
• Individual API changes

Prior Discussions

• Issue: https://github.com/data-apis/array-api/issues/102
• Issue: https://github.com/data-apis/array-api/issues/153

General Concerns

New APIs

real
conj (complex conjugate)
imag
arg/angle/phase (phase angle)
linalg.eig
linalg.eigvals

Decisions

• initial data types: complex64 and complex128?

  • Update: only complex64 and complex128 to be added, thus mirroring float32 and float64.

• rounding complex numbers (component-wise)

  • NumPy supports round, but not ceil, floor, and trunc.
  • Update: ceiling, flooring, and truncating complex numbers is not well-defined. The only rounding operation which is commonly supported is round.

• ordering (lexicographic?)

  • necessary for sorting, maximum, minimum (e.g., argsort, argmax, argmin, min, max, sort)
  • issue: https://github.com/data-apis/array-api/issues/102#issuecomment-748328170
  • choices are to define a complex number ordering or leave out of the specification
  • Update: ordering complex numbers is left out of the specification.

• branch cut policy?

  • branch cut reference: https://en.wikipedia.org/wiki/Branch_point#Branch_cuts
  • should we strictly follow NumPy/C99, or should we allow for implementation flexibility?
  • if we strictly follow something other than NumPy/C99, obvious backward compat concern
  • Update: branch cuts will be included in the 2022 revision under a provisional status. Provided no issues arise during adoption and implementation, the provisional status may be lifted in a future revision of the standard.

• casting from complex to real

  • discard imaginary component (as in C, NumPy)
  • other choice would to require user to explicitly invoke real before casting
  • Update: decision was to require that array API consumers be explicit in specifying which component they want to cast when casting from complex to real.

• complex numbers with components which are infinity and/or NaN

  • in Python, a complex number can be both infinite and NaN (according to cmath.isinf, cmath.isnan)

    In [1]: z = complex(float('inf'), float('nan'))
    
    In [2]: z
    Out[2]: (inf+nanj)
    
    In [3]: cmath.isinf(z)
    Out[3]: True
    
    In [4]: cmath.isnan(z)
    Out[4]: True

  • in NumPy (v1.23.5), behavior is consistent with Python

    In [1]: z = np.complex128(complex(float('inf'), float('nan')))
    
    In [2]: z
    Out[2]: (inf+nanj)
    
    In [3]: np.isnan([z])
    Out[3]: array([True])
    
    In [4]: np.isinf([z])
    Out[4]: array([True])

  • in C99 (see "complex floating types" section), one infinity model (e.g., inf + nan*j == inf)

    • "In order to support the one-infinity model of complex number arithmetic, C regards any complex value with at least one infinite part as an infinity even if its other part is a NaN..."
    • See C99 rationale 7.3.9.4 and SO

  • update: decision was made to allow implementation-dependent behavior for modeling complex NaNs and infinities. In particular, for complex multiplication and division, handling of complex infinities and NaNs may not be consistent across implementations.

• • *

Creation Functions

arange

• No changes. No complex number support.

  • NumPy issue: https://github.com/numpy/numpy/issues/10332

    • can be difficult to resolve step/length

asarray

• dtype

  • if one or more values are complex Python scalars, the output data type must be the default complex floating-point data type.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/434

empty

• No changes. Output array data type has no restrictions.

empty_like

• No changes. Output array data type has no restrictions.

eye

• No changes. Output array data type has not restrictions.

  • May want to include note that, for complex numbers, ones along the diagonal means 1 + 0j.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/436

from_dlpack

• No changes.

full

• fill_value

  • update to accept complex fill value.

• dtype

  • if fill value is complex, output array data type must be the default complex floating-point data type.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/435

full_like

• fill_value

  • update to accept complex fill value.

• dtype

  • update note for when dtype is None to include complex.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/435

linspace

• start

  • add support for complex

• stop

  • add support for complex

• when either start or stop is complex, the result must be complex.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/568

meshgrid

• update to accept all numeric dtypes.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/437

ones

• No changes necessary.

  • May be useful to add a note that, for complex numbers, ones means 1 + 0j.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/438

ones_like

• No changes necessary.

  • May be useful to add a note that, for complex numbers, ones means 1 + 0j.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/438

tril

• No changes necessary. No restrictions on input array data types.

triu

• No changes necessary. No restrictions on input array data types.

zeros

• No changes necessary. No restrictions on output array data types.

zeros_like

• No changes necessary. No restrictions on output array data types.

• • *

Data Type Functions

astype

• Add note stating that, when casting from a complex data type to a real data type stating, the imaginary component is discarded and casting to integral data types is unspecified and thus implementation-dependent.

  • Discarding the imaginary component follows C and is done in NumPy.
  • Could also disallow/omit/not explicitly support casting from complex to real and require users to explicitly call real if they want to discard the imaginary component.
  • Update: casting from a complex data type to a real-valued data type was disallowed in the specification in favor of API consumers being explicit wrt which component should be cast.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/445

broadcast_arrays

• No changes necessary.

broadcast_to

• No changes necessary.

can_cast

• No changes necessary. Follows promotion rules for complex numbers.

finfo

• No changes necessary.

iinfo

• No changes necessary.

result_type

• No changes necessary. Follows promotion rules for complex numbers.

• • *

Data Types

• Add complex64 and complex128 following precedent where the numeric suffix specifies the number of bits.

  • The real and imaginary components should be IEEE 754 floating-point numbers.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/418

Default Data Types

• The default complex number data type is dependent on the default floating-point data type. If the latter is float32, the default complex data type must be complex64.

  • PyTorch already does this.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/418

Data Type Categories

• Add complex data types to list of numeric data types.

• Add "Real Data Types" category which should be equal to the current list of numeric data types.

• Add "Complex Data Types" category which only includes the complex number data types.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/418
• • *

Element-wise Functions

abs

• Add support by returning the complex magnitude.

• Add complex number special cases: same as hypot(creal(z), cimag(z)).

• status: implemented

  • Dependent on https://github.com/data-apis/array-api/issues/544
  • PR: https://github.com/data-apis/array-api/pull/546

acos

• Add complex number support.

• Define special cases.

  • C: https://en.cppreference.com/w/c/numeric/complex/cacos
    • [-inf,-1], [1,inf]
  • Python branch cuts: https://docs.python.org/3/library/cmath.html#cmath.acos
    • same as C
  • NumPy branch cuts: https://numpy.org/doc/stable/reference/generated/numpy.arccos.html
    • same as C

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/517

acosh

• Add complex number support.

• Define special cases.

  • C: https://en.cppreference.com/w/c/numeric/complex/cacosh
    • [-inf,1]
  • NumPy branch cuts: https://numpy.org/doc/stable/reference/generated/numpy.arccosh.html
    • same as C
  • Python branch cuts: https://docs.python.org/3/library/cmath.html#cmath.acosh
    • same as C

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/520

add

• Add complex number support. Complex number addition is well-defined.

  • Some care should be given to infinities and NaNs.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/525

asin

• Add complex number support.

• Define special cases.

  • C: https://en.cppreference.com/w/c/numeric/complex/casin
  • NumPy branch cuts: https://numpy.org/doc/stable/reference/generated/numpy.arcsin.html
  • Python branch cuts: https://docs.python.org/3/library/cmath.html#cmath.asin

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/521

asinh

• Add complex number support.

• Define special cases.

  • C: https://en.cppreference.com/w/c/numeric/complex/casinh
    • [-inf*i, -i], [i, inf*i]
  • NumPy branch cuts: https://numpy.org/doc/stable/reference/generated/numpy.arcsinh.html
    • same as C
  • Python branch cuts: https://docs.python.org/3/library/cmath.html#cmath.asinh
    • same as C

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/522

atan

• Add complex number support.

• Define special cases.

  • C: https://en.cppreference.com/w/c/numeric/complex/catan
    • [-inf*i, -i], [i, inf*i]
  • NumPy branch cuts: https://numpy.org/doc/stable/reference/generated/numpy.arctan.html
    • same as C
  • Python branch cuts: https://docs.python.org/3/library/cmath.html#cmath.atan
    • same as C

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/523

atan2

• No complex number support.
• No changes necessary as already limited to real number data types.

atanh

• Add complex number support.

• Define special cases.

  • C: https://en.cppreference.com/w/c/numeric/complex/catanh
    • [-inf, -1], [1,inf]
  • NumPy branch cuts: https://numpy.org/doc/stable/reference/generated/numpy.arctanh.html
    • same as C
  • Python branch cuts: https://docs.python.org/3/library/cmath.html#cmath.atanh
    • same as C

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/524

bitwise_and

• No changes. Complex dtypes are not allowed.

bitwise_left_shift

• No changes. Complex dtypes are not allowed.

bitwise_invert

• No changes. Complex dtypes are not allowed.

bitwise_or

• No changes. Complex dtypes are not allowed.

bitwise_right_shift

• No changes. Complex dtypes are not allowed.

bitwise_xor

• No changes. Complex dtypes are not allowed.

ceil

• Add complex number support. Independently round components (e.g., as in MATLAB).

  • NumPy does not support in np.ceil.
  • No complex number support due to implementation ambiguity.

cos

• Add complex number support.

• Define special cases.

  • C: https://en.cppreference.com/w/c/numeric/complex/ccos
    • no branch cuts
  • NumPy: https://numpy.org/doc/stable/reference/generated/numpy.cos.html
    • same as C
  • Python: https://docs.python.org/3/library/cmath.html#cmath.cos
    • same as C

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/454

cosh

• Add complex number support.

• Define special cases.

  • C: https://en.cppreference.com/w/c/numeric/complex/ccosh
    • no branch cuts
  • NumPy: https://numpy.org/doc/stable/reference/generated/numpy.cosh.html
    • same as C
  • Python: https://docs.python.org/3/library/cmath.html#cmath.cosh
    • same as C

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/453

divide

• Add complex number support.

• Define special cases.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/554

equal

• Add complex number support.

  • Care should be taken with infinities and NaNs.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/528

exp

• Add complex number support.

• Define special cases.

  • C: https://en.cppreference.com/w/c/numeric/complex/cexp
    • no branch cuts
  • NumPy: https://numpy.org/doc/stable/reference/generated/numpy.exp.html
    • same as C
  • Python: https://docs.python.org/3/library/cmath.html#cmath.exp
    • same as C

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/451

expm1

• Add complex number support.

• Define special cases.

  • should follow exp

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/452

floor

• Add complex number support. Independently round components (e.g., as in MATLAB).

  • NumPy does not support in np.floor.
  • No complex number support due to implementation ambiguity.

floor_divide

• No complex number support.
• No changes necessary as already limited to real number data types.

greater

• No complex number support due to complex numbers lacking a natural ordering.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/527

greater_equal

• No complex number support due to complex numbers lacking a natural ordering.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/527

isfinite

• Add support for complex numbers.

  • Care should be taken for infinities and NaNs.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/531

isinf

• Add support for complex numbers.

  • Care should be taken for infinities and NaNs.
    • how to classify a complex number as infinite?

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/530

isnan

• Add support for complex numbers.

  • Care should be taken for infinities and NaNs.
    • how to classify a complex number as NaN?
    • Update: if any component is NaN, the complex number is considered "NaN"

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/532

less

• No complex number support due to complex numbers lacking a natural ordering.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/527

less_equal

• No complex number support due to complex numbers lacking a natural ordering.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/527

log

• Add complex number support.

• Define special cases.

  • C: https://en.cppreference.com/w/c/numeric/complex/clog
    • same as NumPy
  • NumPy branch cuts: https://numpy.org/doc/stable/reference/generated/numpy.log.html
    • [-inf, 0]
  • Python branch cuts: https://docs.python.org/3/library/cmath.html#cmath.log
    • same as NumPy

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/514

log1p

• Add complex number support.

• Define special cases.

  • NumPy branch cuts: https://numpy.org/doc/stable/reference/generated/numpy.log1p.html
  • should follow similarly to log

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/534

log2

• Add complex number support.

• Define special cases.

  • NumPy branch cuts: https://numpy.org/doc/stable/reference/generated/numpy.log2.html
    • same as log

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/535

log10

• Add complex number support.

• Define special cases.

  • NumPy branch cuts: https://numpy.org/doc/stable/reference/generated/numpy.log10.html
    • same as log
  • Python branch cuts: https://docs.python.org/3/library/cmath.html#cmath.log10
    • same as NumPy

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/536

logaddexp

• No complex number support. This function is mainly useful for stats.
• No changes necessary as already limited to real-valued data types.

logical_and

• No changes necessary. Input arrays expected to have boolean data type.

logical_not

• No changes necessary. Input arrays expected to have boolean data type.

logical_or

• No changes necessary. Input arrays expected to have boolean data type.

logical_xor

• No changes necessary. Input arrays expected to have boolean data type.

multiply

• Add complex number support. Complex number multiplication is well-defined.

  • Care should be taken with regard to infinities and NaNs.

• Define special cases.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/551

negative

• Add complex number support. No real changes necessary, as relies on multiply.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/448

not_equal

• Add complex number support.

  • Care should be taken with infinities and NaNs.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/529

positive

• Add complex number support. No changes necessary, as this is effectively the identity function.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/447

pow

• Add complex number support.

• Define special cases.

  • C: https://en.cppreference.com/w/c/numeric/complex/cpow
    • branch cut for the first parameter along the negative real axis
  • NumPy: https://numpy.org/doc/stable/reference/generated/numpy.power.html
  • Python supports, but not exposed via cmath.
    • pinning down exact behavior could be tricky (see Python issue 15996)

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/537

remainder

• No complex number support.
• No changes necessary as already limited to real-valued data types.

round

• Add complex number support.

  • Independently round components (e.g., as in MATLAB and NumPy).

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/440

sign

• Add complex number support.

• Define special cases.

  • NumPy: https://numpy.org/doc/stable/reference/generated/numpy.sign.html

    • NumPy uses x / sqrt(x*x); could also use x/|x|
    • see comment: https://github.com/data-apis/array-api/issues/153#issuecomment-869059671

  • Update: consensus is to use x/|x|.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/556

sin

• Add complex number support.

• Define special cases. No branch cuts.

  • C: https://en.cppreference.com/w/c/numeric/complex/csin
    • no branch cuts
  • NumPy: https://numpy.org/doc/stable/reference/generated/numpy.sin.html
    • same as C
  • Python: https://docs.python.org/3/library/cmath.html#cmath.sin
    • same as C

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/457

sinh

• Add complex number support.

• Define special cases.

  • C: https://en.cppreference.com/w/c/numeric/complex/csinh
    • no branch cuts
  • NumPy: https://numpy.org/doc/stable/reference/generated/numpy.sinh.html
    • same as C
  • Python: https://docs.python.org/3/library/cmath.html#cmath.sinh
    • same as C

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/456

square

• Add complex number support. Complex number multiplication is well-defined.

  • question whether to add abs2: https://github.com/data-apis/array-api/issues/153#issuecomment-896339259

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/552

sqrt

• Add complex number support.

• Define special cases.

  • C: https://en.cppreference.com/w/c/numeric/complex/csqrt
    • branch cut along the negative real axis [-inf,0)
  • NumPy branch cuts: https://numpy.org/doc/stable/reference/generated/numpy.sqrt.html
    • same as C
  • Python branch cuts: https://docs.python.org/3/library/cmath.html#cmath.sqrt
    • same as C

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/461

subtract

• Add complex number support. Complex number addition is well-defined.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/526

tan

• Add complex number support.

• Define special cases.

  • C: https://en.cppreference.com/w/c/numeric/complex/ctan
    • no branch cuts
  • NumPy: https://numpy.org/doc/stable/reference/generated/numpy.tan.html
    • same as C
  • Python: https://docs.python.org/3/library/cmath.html#cmath.tan
    • same as C

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/459

tanh

• Add complex number support.

• Define special cases.

  • C: https://en.cppreference.com/w/c/numeric/complex/ctanh
    • no branch cuts
  • NumPy: https://numpy.org/doc/stable/reference/generated/numpy.tanh.html
    • same as C
  • Python branch cuts: https://docs.python.org/3/library/cmath.html#cmath.tanh
    • same as C

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/458

trunc

• Add complex number support. Independently truncate components (e.g., as in MATLAB).

  • NumPy does not support in np.trunc.
  • No complex number support due to implementation ambiguity.
• • *

Linear Algebra Functions

matmul

• Add complex number support.

  • complex number addition is well-defined.
  • complex number multiplication is less well-defined and depends on how an implementation chooses to model complex infinity.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/557

matrix_transpose

• No changes necessary.

tensordot

• Add complex number support.

  • complex number addition is well-defined.
  • complex number multiplication is less well-defined and depends on how an implementation chooses to model complex infinity.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/558

vecdot

• Implementations should conjugate when computing the complex dot product: x^H y

  • Issue: https://github.com/data-apis/array-api/issues/356
  • PR: https://github.com/data-apis/array-api/pull/512

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/512
• • *

Manipulation Functions

concat

• No changes necessary.

expand_dims

• No changes necessary.

flip

• No changes necessary.

permute_dims

• No changes necessary.

reshape

• No changes necessary.

roll

• No changes necessary.

squeeze

• No changes necessary.

stack

• No changes necessary.

• • *

Searching Functions

argmax

• Require that complex numbers be ordered in lexicographic order?

  • While not compatible with multiplication, lexicographic order is a common total order. E.g., NumPy uses lexicographic order.
  • Another alternative is by magnitude and then phase angle. E.g., MATLAB supports this order.
  • The specification could default to lexicographic, and revisit the ordering relation in the future with possible support for optionally specifying an alternative comparison method.
  • Some care needs to be given to sorting when one or more components is NaN.
  • Update: no support for complex numbers due to a lack of a natural order.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/527

argmin

• No complex number support due to complex numbers lacking a natural ordering.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/527

nonzero

• No changes necessary. A nonzero complex number is a complex number whose real or imaginary component is nonzero.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/441

where

• No changes necessary.

• • *

Set Functions

unique_all

• Specify complex number value equality.

  • In C, "In order to support the one-infinity model of complex number arithmetic, C regards any complex value with at least one infinite part as an infinity even if its other part is a NaN..."
  • Need to resolve isinf and isnan duality
  • Update: base equality comparison on equal.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/540

unique_counts

• Same as unique_all.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/540

unique_inverse

• Same as unique_all.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/540

unique_values

• Same as unique_all.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/540
• • *

Sorting Functions

argsort

• No complex number support due to complex numbers lacking a natural ordering.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/527

sort

• No complex number support due to complex numbers lacking a natural ordering.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/527
• • *

Statistical Functions

max

• No complex number support due to complex numbers lacking a natural ordering.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/527

mean

• No complex number support.
• Change to only real number data types.

min

• No complex number support due to complex numbers lacking a natural ordering.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/527

prod

• Add support for complex numbers. Complex number multiplication is well-defined.

  • The dtype option needs to be updated to accommodate complex numbers.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/553

std

• No complex number support.
• Change to only real number data types.

sum

• Add support for complex numbers. Complex number addition is well-defined.

  • The dtype option needs to be updated to accommodate complex numbers.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/538

var

• No complex number support.

• Change to only real number data types.

• • *

Type Promotion

Rules

• Add complex number type promotion table.

• Related complex number type promotion to floating-point number type promotion (e.g., f8 and c16)

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/491

Mixing arrays with Python Scalars

• Add complex Python scalars.

• Update note concerning mixed "kind" operations.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/513
• • *

Utility Functions

all

• No changes necessary. The value 0+0j should evaluate to False. If a complex number has a non-zero component, the value should evaluate to True.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/442

any

• Same as all.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/442
• • *

Linear Algebra Extension

cholesky

• Add complex number support.

• Require that each square matrix must be Hermitian.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/443

cross

• Add complex number support.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/559

det (determinant)

• Add complex number support.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/542

diagonal

• No changes necessary.

eigh

• Add complex number support.

  • Require that each matrix must be Hermitian and the returned Q unitary.
  • May want to make the dtype of the eigevalues unconditionally real.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/543

eigvalsh

• Add complex number support.

  • Require that each matrix must be Hermitian.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/543

inv

• Add complex number support.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/547

matmul

• Support added in main namespace.

matrix_norm

• Add complex number support.

• Depends on svd.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/565

matrix_power

• Add complex number support.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/549

matrix_rank

• Add complex number support.

• Depends on svd.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/563

matrix_transpose

• No changes necessary.

outer

• Add complex number support.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/560

pinv

• Add complex number support.

• Depends on svd.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/564

qr

• Add complex number support.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/548

slogdet

• Add complex number support.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/567

solve

• Add complex number support.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/566

svd

• Add complex number support.

  • Require that each U, Vh must be unitary.
  • May want to require that the returned dtype of S is unconditionally real.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/561

svdvals

• Add complex number support.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/562

trace

• Add complex number support.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/541

vecdot

• Changes made in main namespace.

vector_norm

• Add complex number support.

• status: implemented

  • PR: https://github.com/data-apis/array-api/pull/550

[honno]

Would we want a data type function for complex dtypes i.e. cinfo()? Currently NumPy and PyTorch don't have a dedicate method, but complex dtypes can fallback on finfo().

Interestingly there was a little discussion of a torch.cinfo() at https://github.com/pytorch/pytorch/issues/35954#issuecomment-620223025

[leofang]

• branch cut policy?

I don't know why I missed it... CuPy uses Thrust (and it's likely being used by many other projects that depends on CUDA; IIUC the implementation was ported to libcudacxx) so it's worth mentioning.

Thrust's complex math funcs were based on FreeBSD's. In each FreeBSD man page the branch cut is clearly documented so it's a good starting point. However, as Thrust didn't document it clearly (I asked internally and was told to inspect the source directly, which is challenging given my lack of bandwidth) and it's unclear to me if the Thrust impl was a one-to-one translation of FreeBSD's since I don't have access to the FreeBSD source code, I'd proceed with caution.

[kgryte]

Tracking changes to existing APIs within the array API specification:

• [x] Data Types: complex64 and complex128
  • https://github.com/data-apis/array-api/pull/418
• [x] Type Promotion Rules (including mixing arrays with Python scalars)
  • https://github.com/data-apis/array-api/pull/491
  • https://github.com/data-apis/array-api/pull/513
• [x] asarray
  • https://github.com/data-apis/array-api/pull/434
• [x] eye
  • https://github.com/data-apis/array-api/pull/436
• [x] full
  • https://github.com/data-apis/array-api/pull/435
• [x] full_like
  • https://github.com/data-apis/array-api/pull/435
• [x] linspace
  • https://github.com/data-apis/array-api/pull/568
• [x] meshgrid
  • https://github.com/data-apis/array-api/pull/437
• [x] ones
  • https://github.com/data-apis/array-api/pull/438
• [x] ones_like
  • https://github.com/data-apis/array-api/pull/438
• [x] astype
  • https://github.com/data-apis/array-api/pull/445
• [x] abs/__abs__
  • https://github.com/data-apis/array-api/pull/546
• [x] acos
  • https://github.com/data-apis/array-api/pull/517
• [x] acosh
  • https://github.com/data-apis/array-api/pull/520
• [x] add/__add__
  • https://github.com/data-apis/array-api/pull/525
• [x] asin
  • https://github.com/data-apis/array-api/pull/521
• [x] asinh
  • https://github.com/data-apis/array-api/pull/522
• [x] atan
  • https://github.com/data-apis/array-api/pull/523
• [x] atanh
  • https://github.com/data-apis/array-api/pull/524
• [x] cos
  • https://github.com/data-apis/array-api/pull/454
• [x] cosh
  • https://github.com/data-apis/array-api/pull/453
• [x] divide/__truediv__
  • https://github.com/data-apis/array-api/pull/554
• [x] equal/__equal__
  • https://github.com/data-apis/array-api/pull/528
• [x] exp
  • https://github.com/data-apis/array-api/pull/451
• [x] expm1
  • https://github.com/data-apis/array-api/pull/452
• [x] greater/__gt__
  • https://github.com/data-apis/array-api/pull/527
• [x] greaterequal/__ge_\
  • https://github.com/data-apis/array-api/pull/527
• [x] isfinite
  • https://github.com/data-apis/array-api/pull/531
• [x] isinf
  • https://github.com/data-apis/array-api/pull/530
• [x] isnan
  • https://github.com/data-apis/array-api/pull/532
• [x] less/__lt__
  • https://github.com/data-apis/array-api/pull/527
• [x] lessequal/__le_\
  • https://github.com/data-apis/array-api/pull/527
• [x] log
  • https://github.com/data-apis/array-api/pull/514
• [x] log1p
  • https://github.com/data-apis/array-api/pull/534
• [x] log2
  • https://github.com/data-apis/array-api/pull/535
• [x] log10
  • https://github.com/data-apis/array-api/pull/536
• [x] multiply/__mul__
  • https://github.com/data-apis/array-api/pull/551
• [x] negative/__neg__
  • https://github.com/data-apis/array-api/pull/448
• [x] notequal/__ne_\
  • https://github.com/data-apis/array-api/pull/529
• [x] positive/__pos__
  • https://github.com/data-apis/array-api/pull/447
• [x] pow/__pow__
  • https://github.com/data-apis/array-api/pull/537
• [x] round
  • https://github.com/data-apis/array-api/pull/440
• [x] sign
  • https://github.com/data-apis/array-api/pull/556
• [x] sin
  • https://github.com/data-apis/array-api/pull/457
• [x] sinh
  • https://github.com/data-apis/array-api/pull/456
• [x] square
  • https://github.com/data-apis/array-api/pull/552
• [x] sqrt
  • https://github.com/data-apis/array-api/pull/461
• [x] subtract/__sub__
  • https://github.com/data-apis/array-api/pull/526
• [x] tan
  • https://github.com/data-apis/array-api/pull/459
• [x] tanh
  • https://github.com/data-apis/array-api/pull/458
• [x] matmul/__matmul__
  • https://github.com/data-apis/array-api/pull/557
• [x] tensordot
  • https://github.com/data-apis/array-api/pull/558
• [x] vecdot
  • https://github.com/data-apis/array-api/pull/512
• [x] argmax
  • https://github.com/data-apis/array-api/pull/527
• [x] argmin
  • https://github.com/data-apis/array-api/pull/527
• [x] nonzero
  • https://github.com/data-apis/array-api/pull/441
• [x] unique_all
  • https://github.com/data-apis/array-api/pull/540
• [x] unique_counts
  • https://github.com/data-apis/array-api/pull/540
• [x] unique_inverse
  • https://github.com/data-apis/array-api/pull/540
• [x] unique_values
  • https://github.com/data-apis/array-api/pull/540
• [x] argsort
  • https://github.com/data-apis/array-api/pull/527
• [x] sort
  • https://github.com/data-apis/array-api/pull/527
• [x] max
  • https://github.com/data-apis/array-api/pull/527
• [x] min
  • https://github.com/data-apis/array-api/pull/527
• [x] prod
  • https://github.com/data-apis/array-api/pull/553
• [x] sum
  • https://github.com/data-apis/array-api/pull/538
• [x] all
  • https://github.com/data-apis/array-api/pull/442
• [x] any
  • https://github.com/data-apis/array-api/pull/442
• [x] cholesky
  • https://github.com/data-apis/array-api/pull/443
• [x] cross
  • https://github.com/data-apis/array-api/pull/559
• [x] det
  • https://github.com/data-apis/array-api/pull/542
• [x] eigh
  • https://github.com/data-apis/array-api/pull/543
• [x] eigvalsh
  • https://github.com/data-apis/array-api/pull/543
• [x] inv
  • https://github.com/data-apis/array-api/pull/547
• [x] matrix_norm
  • https://github.com/data-apis/array-api/pull/565
• [x] matrix_power
  • https://github.com/data-apis/array-api/pull/549
• [x] matrix_rank
  • https://github.com/data-apis/array-api/pull/563
• [x] outer
  • https://github.com/data-apis/array-api/pull/560
• [x] pinv
  • https://github.com/data-apis/array-api/pull/564
• [x] qr
  • https://github.com/data-apis/array-api/pull/548
• [x] slogdet
  • https://github.com/data-apis/array-api/pull/567
• [x] solve
  • https://github.com/data-apis/array-api/pull/566
• [x] svd
  • https://github.com/data-apis/array-api/pull/561
• [x] svdvals
  • https://github.com/data-apis/array-api/pull/562
• [x] trace
  • https://github.com/data-apis/array-api/pull/541
• [x] vector_norm
  • https://github.com/data-apis/array-api/pull/550

New APIs

• [x] conj
  • https://github.com/data-apis/array-api/pull/446
• [x] real
  • https://github.com/data-apis/array-api/pull/427
• [x] imag
  • https://github.com/data-apis/array-api/pull/496

[kgryte]

At this point, PRs have been submitted for all existing APIs for which we currently expect complex number support.

[rgommers]

All PRs have been merged - adding complex number support to the API is complete. Thanks a lot to everyone who contributed - and in particular @kgryte for all the spec writing.