Tracking issue: Add array API standard support to the main namespace #25076

mtsokol · 2023-11-06T15:03:46Z

See the slides from the NumPy 2.0 developer meeting in the numpy archive for an initial overview. That content has to be expanded into a NEP.

Backlog

Infra/support/docs

a CI job that runs https://github.com/data-apis/array-api-tests/ on the main namespace (MAINT: Add array-api-tests CI stage, add ndarray.__array_namespace__ #25167)
reference guide documentation
~~a user guide documentation page~~

main namespace

np.bool (API: Add and redefine numpy.bool [Array API] #25080)
np.astype (API: Introduce np.astype [Array API] #25079)
unique_all, unique_counts, unique_inverse, unique_values (API: Add Array API setops [Array API] #25088)
concat, permute_dims (API: Add Array API aliases (math, bitwise, linalg, misc) [Array API] #25086)
Trigonometric functions' aliases (API: Add Array API aliases (math, bitwise, linalg, misc) [Array API] #25086)
bitwise_left_shift, bitwise_right_shift, bitwise_invert (API: Add Array API aliases (math, bitwise, linalg, misc) [Array API] #25086)
copy keyword argument for np.asarray (API: Introduce copy argument for np.asarray [Array API] #25168)

`linalg` namespace


 outer (API: Add outer to numpy.linalg [Array API] #25101)
 svdvals (API: Add svdvals to numpy.linalg [Array API] #24940)
 tensordot (API: Add Array API aliases (math, bitwise, linalg, misc) [Array API] #25086)
 vecdot (API: Add matrix_norm, vector_norm, vecdot and matrix_transpose [Array API] #25155)
 vector_norm (API: Add matrix_norm, vector_norm, vecdot and matrix_transpose [Array API] #25155)


ndarray methods and attributes

 __array_namespace__ method (MAINT: Add array-api-tests CI stage, add ndarray.__array_namespace__ #25167)
 to_device and device members (API: Add device and to_device to numpy.ndarray [Array API] #25233)

miscellaneous

 correction argument for var and std (API: Introduce correction argument for np.var and np.std [Array API] #25169)
 rtol parameter for pinv and upper parameter for cholesky (API: Adjust linalg.pinv and linalg.cholesky to Array API #25388)

The text was updated successfully, but these errors were encountered:

asmeurer · 2023-11-06T21:48:06Z

This mailing list thread goes into details for some of the "easy and useful" changes https://mail.python.org/archives/list/numpy-discussion@python.org/thread/TTZEUKXUICDHGTCX5EMR6DQTYOSDGRV7/#YKBWQ2AP76WYWAP6GFRYMPHZCKTC43KM

seberg · 2023-11-07T12:16:27Z

I would be very happy to hear any opinion here around adding aliases for functions or kwargs that do the exact same thing as existing ones. I don't dislike at least most of them.
But we do have a choice: __array_namespace__ definitions can differ from the normal definitions without making the transition story for libraries really harder, there is a certain symmetry to doing it maybe, but I still cannot see it as a necessity, so I think we should do whatever we think is best for users.

rgommers · 2023-11-08T14:17:26Z

__array_namespace__ definitions can differ from the normal definitions without making the transition story for libraries really harder

It looks to me like that would require adding a whole new hidden namespace, rather then a simple return numpy, potentially confusing, a lot of extra work, and the potential for extra bugs. Plus it would mean that the main namespace would actually not be compatible, which has other side effects. So that does not sound all that appealing. I'll add it to the NEP draft (ETA within a week; hard to keep up with Mateusz:)) as a design alternative though.

mtsokol · 2023-11-15T15:28:29Z

Hi! I'm finalizing the last np.linalg Array API PR and I realized that although vecdot (vector dot) is available only in np.array_api:

# Note: vecdot is not in NumPy
def vecdot(x1: Array, x2: Array, /, *, axis: int = -1) -> Array:

there's np.vdot that also claims to be a vector dot, but with completely different semantics (it ravels input to 1-D arrays, doesn't have axis keyword and it's Complex-conjugating dot product). I find it a bit confusing to have np.vdot and np.vecdot.
What do you think about renaming vdot to something else, like conj_vecdot?

rgommers · 2023-11-16T17:38:13Z

vdot is a bit unfortunate indeed, but on the other hand we already have a lot of similar functions so adding yet another name perhaps does not help. The four array API functions should be orthogonal and complete, so I'd suggest applying the new .. legacy:: admonition to vdot and de-emphasizing it when we reorganize the docs.

rgommers · 2023-11-24T11:46:25Z

We discussed this topic in the community meeting two days ago. Quick summary:

Let's get np.bool and the new CI job with xfails merged now,
For the other PRs, let's go ahead with the ones that are an improvement either way (independent of the array API standard)
For the ones that we would not do without the array API standard exists (e.g., adding device), those are blocked on writing/reviewing the NEP.
@seberg pointed out that it would be helpful to give a thumbs up on PRs from (2) that look fine, with 1-2 thumbs up emojis, it's easier to move ahead and merge them.

lucascolley · 2023-12-16T22:31:52Z

also, numpy.fft.{fftfreq, rfftfreq} need the device parameter.

jakevdp · 2024-01-04T19:06:09Z

Another TODO to add here: np.sort() and np.argsort() need a descending argument: https://data-apis.org/array-api/2022.12/API_specification/generated/array_api.sort.html

I'm interested in what choice NumPy will make regarding the treatment of NaN entries when sorted in descending order, as this is not specified by the array API, but we'd like to make jax.numpy follow the numpy implementation in this respect.

rgommers · 2024-01-05T19:35:30Z

I'm interested in what choice NumPy will make regarding the treatment of NaN entries when sorted in descending order, as this is not specified by the array API, but we'd like to make jax.numpy follow the numpy implementation in this respect.

Good question. Whether nans go at the beginning or the end for sort output is undefined on purpose, and in numpy they go at the end. For consistency, I'd expect for descending=False the whole array to be reversed, so then nans go at the beginning:

>>> x = np.asarray([1.0, 2.0, np.nan, 3.0, 4.0, np.nan, 5.0])
>>> np.sort(x)
array([ 1.,  2.,  3.,  4.,  5., nan, nan])
>>> np.sort(x)[::-1]
array([nan, nan,  5.,  4.,  3.,  2.,  1.])

jakevdp · 2024-01-05T19:41:45Z

Great, thanks! That's exactly how I ended up implementing it here: jax-ml/jax#19201

For NumPy 2.0. xref numpygh-25076 as the main tracking issue for this topic. [skip actions] [skip azp] [skip cirrus]

* NEP: add NEP 56 on array API standard support in main namespace For NumPy 2.0. xref gh-25076 as the main tracking issue for this topic. [skip actions] [skip azp] [skip cirrus] * DOC: rework for review comments: textual suggestions and easy changes [skip actions] [skip cirrus] [skip azp] * DOC: second batch of smaller textual changes [skip actions] [skip azp] [skip cirrus] * DOC: adopt suggestions on namespace and alias count/hiding [skip actions] [skip cirrus] [skip azp] * DOC: extend abstract with the main rationale and benefits * add section about which parts of the standard are not adopted [skip actions] [skip azp] [skip cirrus] * Add the in-place "no unsafe casting" item to the not adopted section Also a few smaller textual changes. [skip actions] [skip cirrus] [skip azp] * NEP: update content mentioning array scalars Addresses review feedback. Array scalars aren't actually incompatible with the design of the standard. * NEP: improve backwards compatibility section and describe `copy=` better As requested in PR review, better delineate the different types of changes in the backwards compatibility section, and add assessments of what the impact of changes is. In addition, expect the description of the `copy=` keyword semantics changes. [skip cirrus] [skip actions] [skip azp] * NEP: update description of `fft` changes [skip actions] [skip cirrus] [skip azp]

rgommers · 2024-03-04T10:48:53Z

This is all done, so let's close this tracking issue. Thanks all!

mdhaber · 2024-12-01T23:16:29Z

@rgommers Re: #25076 (comment), was closing this without sort/argsort having a descending keyword intentional? Crossref gh-14728.

rgommers · 2024-12-02T10:04:41Z

Yes, intentional to close this tracking issue as "declaring victory for 2.0.0". For several of the loose ends we decided that individual issues could be used - tracking issues shouldn't stay open indefinitely.

IIRC descending was investigated and determined that it was a lot of work (because of nan sorting, as noted in gh-14728) and hence we punted on that for 2.0. @mtsokol you may be able to add some extra color here (I thought there was discussion elsewhere aside from gh-14728, but can't remember where)?

mtsokol · 2024-12-02T10:55:34Z

Apart from that issue I had one attempt to implement it, here: mtsokol#5 but it turned out to be too much to bite at once. I also found another attempt here: #14989.

lucascolley · 2024-12-02T11:02:54Z

shall we open a new issue to track it? Or are there other array API standard compatibility things tracked somewhere?

rgommers · 2024-12-02T11:13:03Z

shall we open a new issue to track it? Or are there other array API standard compatibility things tracked somewhere?

Please use gh-14728 for this descending one, adding content as needed.

I'm not in favor of a permanent array API compatibility issue if that's what you meant, it'd be better to use the existing label for it.

seberg added this to NumPy 2.0 Roadmap Jan 11, 2023

mtsokol assigned asmeurer and rgommers Nov 6, 2023

mtsokol converted this from a draft issue Nov 6, 2023

mtsokol changed the title ~~Add array API standard support to the main namespace~~ Tracking issue: Add array API standard support to the main namespace Nov 6, 2023

mtsokol added this to the 2.0.0 release milestone Nov 6, 2023

mtsokol added 01 - Enhancement Numpy 2.0 API Changes labels Nov 6, 2023

mtsokol mentioned this issue Nov 6, 2023

API: Introduce np.astype [Array API] #25079

Merged

rgommers assigned mtsokol Nov 6, 2023

seberg added the triage review Issue/PR to be discussed at the next triage meeting label Nov 7, 2023

This was referenced Nov 7, 2023

API: Add Array API setops [Array API] #25088

Merged

API: Add Array API aliases (math, bitwise, linalg, misc) [Array API] #25086

Merged

lucascolley mentioned this issue Nov 11, 2023

RFC: new rule category for array-agnostic code (XP) astral-sh/ruff#8615

Open

jakevdp mentioned this issue Nov 16, 2023

Tracking issue: support Array API jax-ml/jax#18353

Closed

38 tasks

rgommers removed the triage review Issue/PR to be discussed at the next triage meeting label Nov 24, 2023

lucascolley mentioned this issue Nov 29, 2023

New rule category XP, implement not-array-agnostic-numpy (XP001) astral-sh/ruff#8910

Closed

lucascolley mentioned this issue Dec 10, 2023

[RFC] Implement the Python array API standard ml-explore/mlx#48

Open

asmeurer mentioned this issue Dec 12, 2023

ENH: Make the dtype objects in numpy.array_api more strict #23883

Closed

lucascolley mentioned this issue Dec 20, 2023

ENH/TST/MAINT: fft: follow-ups for array API support scipy/scipy#19257

Open

9 tasks

rgommers moved this from 🔖 Proposal to 🏗 In progress in NumPy 2.0 Roadmap Dec 20, 2023

lucascolley mentioned this issue Dec 26, 2023

API: adjust nD fft s param to array API #25495

Merged

mtsokol mentioned this issue Jan 2, 2024

Align torch.sign with Array API pytorch/pytorch#116610

Open

lucascolley mentioned this issue Jan 4, 2024

Tracking issue for temporary test skips/xfails to revert scipy/scipy#17278

Open

6 tasks

rgommers added a commit to rgommers/numpy that referenced this issue Jan 5, 2024

NEP: add NEP 56 on array API standard support in main namespace

b871142

For NumPy 2.0. xref numpygh-25076 as the main tracking issue for this topic. [skip actions] [skip azp] [skip cirrus]

rgommers mentioned this issue Jan 5, 2024

NEP: add NEP 56 on array API standard support in main namespace #25542

Merged

mtsokol mentioned this issue Jan 19, 2024

API: Introduce copy argument for np.asarray [Array API] #25168

Merged

asmeurer mentioned this issue Jan 26, 2024

np.fft.fft always returns np.complex128 regardless of input type #17801

Closed

rgommers closed this as completed Mar 4, 2024

rgommers moved this from 🏗 In progress to ✅ Done in NumPy 2.0 Roadmap Mar 5, 2024

fandreuz mentioned this issue Oct 6, 2024

Array API standard compatibility PyDMD/PyDMD#545

Open

mdhaber mentioned this issue Dec 1, 2024

ENH: sort/argsort: add descending parameter #14728

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Tracking issue: Add array API standard support to the main namespace #25076

Tracking issue: Add array API standard support to the main namespace #25076

`ndarray` methods and attributes

miscellaneous

Tracking issue: Add array API standard support to the main namespace #25076

Tracking issue: Add array API standard support to the main namespace #25076

Comments

Backlog

Infra/support/docs

main namespace

linalg namespace

ndarray methods and attributes

miscellaneous

`linalg` namespace

`ndarray` methods and attributes