Tracking issue for the 2023 revision of the array API specification

[kgryte]

This is a tracking issue for tasks related to the 2023 revision of the array API specification. The issue is comprised of 3 parts: general todos, new APIs, and issues needing triage.

TODO

• Add page discussing delayed evaluation

  • ref: Eager functions in API appear in conflict with lazy implementation  #642 (comment)
  • PR: Allow lazy implementations to raise from intrinsically eager functions #652
  • PR: Add a design topic page on lazy vs. eager implementations #708

• Clarify out-of-bounds behavior in take

  • ref: Proposal: add APIs for getting and setting elements via a list of indices (i.e., take, put, etc) #177 (comment)
  • PR: Add note clarifying behavior for out-of-bounds indices in take #701

• Clarify minimum rank upper bound

  • ref: Array objects of arbitrary rank are infeasible - require a reasonable range of ranks instead #479
  • PR: Revise guidance to require a minimum upper bound for supported ranks #702

• Clarify sum description when dtype=None

  • ref: sum docstring's description of dtype=None behavior is muddled #623
  • PR: Clarify behavior when dtype=None in sum, prod and trace #666

• Resolve choice of conjugation in complex inner product

  • ref: Choice of conjugation in complex inner product #616
  • PR: Fix definition of complex inner product in vecdot #723

• Clarify broadcasting in linalg functions that accept an axis

  • ref: Broadcasting for linalg functions that accept an axis #617

• Fix descriptions for constants in rendered specification

  • ref: Bug: descriptions for constants included in the standard are incorrect #601
  • PR: Fix documentation for constants #659

• Clarify index array in unique_all

  • ref: unique_all doesn't specify that indices should be a flattened index #588
  • PR: Clarify flattening behavior and fix required output shape for inverse indices in unique_* APIs #700
  • PR: docs: clarify shape of values and order of counts in unique APIs #752

• [ ] Add note clarifying __imatmul__ broadcast behavior

  • ref: Should implementing __imatmul__ really be enforced? #509
  • Update: moved to 2024

• [ ] Add section indicating it's okay to duck type objects (finfo, constants)

  • ref: finfo should not require float type for the result fields #405 (comment)
  • Update: moved to 2024

• DLPack related

  • Anything more to discuss regarding DLPack and readonly/immutable arrays? (priority: high)
    • ref: DLPack and readonly/immutable arrays #191
    • PR: Add versioning support to DLPack APIs #602
  • Anything more to say for forcing back to host? (priority: high; include as part of DLPack discussion?)
    • ref: to_device() -- any way to force back to host "portably?" #626

New APIs

• copysign

  • task size: XS
    • IEEE 754
    • risk: TensorFlow does not implement
  • priority: low
  • ref: Add copysign function to the standard #593
  • PR: Add support for copysign to the specification #693

• [ ] cbrt

  • task size: XS
    • IEEE 754
    • risk: need PyTorch to implement
  • priority: low
  • ref: RFC: add cbrt #590
  • Update: PyTorch still does not have a dedicated cbrt API. We can revisit in 2024.

• [ ] exp2

  • task size: XS
    • IEEE 754
    • risk: MXNet does not implement
  • priority: low
  • ref: RFC: add exp2 function to the standard #591
  • Update: this is low priority and should be revisited in 2024.

• hypot

  • task size: XS
    • IEEE 754
    • risk: none (implemented across all major libraries)
  • priority: medium
  • ref: Add support for computing the hypotenuse via hypot #544
  • PR: Add hypot specification for computing the square root of the sum of squares #703

• [ ] copy (for copying data)

  • task size: S
    • risk: could become M depending on community feedback; need to ensure library alignment
  • priority: ???
  • ref: RFC: add copy #495
  • decisions:
    • name: copy vs clone
  • Update: this is low priority and not clear whether it's needed.

• moveaxis

  • task size: S
  • priority: medium
    • no simple equivalent
  • ref: Adding moveaxis & swapaxes #483
  • PR: Add specification for moving array axes to new positions #656

• searchsorted

  • task size: S
  • priority: medium
  • ref: RFC: add searchsorted to the specification #688
  • PR: Add searchsorted to the specification #699

• [ ] angle

  • task size: S
    • complex number dtypes
    • risk: MXNet does not implement
  • priority: low
  • ref: RFC: add angle for computing the argument of a complex number #595
  • Update: this is low priority and should be revisited in 2024.

• [ ] Hermitian transpose

  • task size: S
  • priority: low
    • convenience function
  • ref: RFC: add Hermitian transpose function #555
  • Update: this is low enough priority that this can be bumped to the 2024 revision.

• Inspection API namespace

  • task size: M
  • priority: high
  • ref: RFC: add a unified inspection API namespace #640
  • PR: Add Array API inspection utilities #689

• clip

  • task size: M
    • bikeshed
  • priority: medium
  • ref: Add clip #482
  • decisions:
    • type promotion
    • kwarg names
    • kwarg value types
  • PR: Add clip to the specification #715

• cumulative sum

  • task size: M
    • bikeshed and alignment
  • priority: medium
  • ref: Add support for computing the cumulative sum to the standard #597
  • decisions:
    • name
    • optional argument for initial value
  • PR: Add specification for computing the cumulative sum #653

• [ ] cumulative prod

  • task size: M
    • bikeshed and alignment
  • priority: low
  • ref: RFC: add support for computing the cumulative product to the standard #598
  • decisions:
    • name
    • optional argument for initial value
  • Update: this is low enough priority that it can wait until the 2024 specification revision.

• [ ] topk

  • task size: M
  • priority: medium
  • ref: RFC: add topk and / or argpartition #629
  • decisions:
    • name
  • PR: feat: add API specification for returning the k largest elements #722
  • Update: moved to 2024 to allow for further R&D.

• repeat/tile

  • task size: M
    • risk: potential to become L; need to ensure community alignment
  • priority: medium
    • xarray adoption
  • ref: Common APIs across array libraries (1 year later) #187 (comment)
  • ref: RFC: add support for repeating each element of an array #654
  • ref: RFC: add support for creating a new array by tiling a provided array #655
  • PR: Add repeat to the specification #690
  • PR: Add support for tiling an array to the specification #692

• [ ] nan-reductions

  • task size: L
    • risk: requires NumPy buy-in
  • priority: high
  • ref: RFC: add support for nan* reductions #621
  • decisions:
    • API design
    • engagement with NumPy community
  • Update: this requires additional discussion and consensus and should be moved to the 2024 revision.

• [ ] logsumexp

  • task size: L
    • risk: requires NumPy buy-in (would duplicate behavior present in SciPy)
  • priority: medium
  • ref: RFC: add logsumexp #596
  • requires addition to NumPy
  • Update:
    • this API was also mentioned as a candidate for inclusion in the special functions extension: RFC: special function extension #725

Triage

• Specification maintenance tasks

  • ref: Tracking issue for specification maintenance tasks #533

• LU factorization

  • ref: RFC: add support for LU factorization in the linalg extension #627

• Anything more to say regarding libraries negotiating that they understand NumPy arrays?

  • ref: Allow libraries to negotiate that they understand e.g. NumPy arrays? #586

• Anything more to discuss for run-time version of API (static typing)?

  • ref: Run-time version of API #584

• Make dtypes obey Python hashing rules?

  • ref: RFC: require that dtypes obey Python hashing rules #582
  • requires changes to NumPy

• Specify that __getitem__ and __setitem__ accepts SupportsIndex

  • ref: Specify that dunder get/set item accepts SupportsIndex #383

• Special cases for +/-0 around branch cuts

  • ref: Special cases for +/- 0 around branch cuts #570

• Add batch support to linalg.outer

  • ref: RFC: linalg.outer support batches of vectors #242
  • awaiting PyTorch and updates to NumPy

• Support for closeness comparison

  • ref: RFC: add support for closeness comparison #170

• Enforcing shape to accommodate data-dependent (unknown) dimensionality

  • ref: RFC: add API to enforce a specified dimensionality #494

• Adding spec guidance regarding exceptions to positional-only arguments

  • ref: Rationale behind not setting positional arguments to positional only for few functions. #475

[leofang]

Should we include #589 or push to 2024 (and perhaps backport it)?

[kgryte]

@leofang My inclination is that #589 should be pushed to 2024 with the possibility of backporting. I think it is lower priority compared to some of the other items we need to get over the finish line before cutting the 2023 release.

[leofang]

• Anything more to say for forcing back to host? (priority: high; include as part of DLPack discussion?)
  • ref: to_device() -- any way to force back to host "portably?" #626

I raised #741 to address this.

[rgommers]

Everything in this tracking issue is now done (or moved to 2024, or descoped), so let's close it. On to the changelog and tagging a release. Thanks all!