-
Notifications
You must be signed in to change notification settings - Fork 8
/
Copy pathnep-0047-array-api-standard.html
1234 lines (1041 loc) · 87.7 KB
/
nep-0047-array-api-standard.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html lang="en" data-content_root="./" >
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>NEP 47 — Adopting the array API standard — NumPy Enhancement Proposals</title>
<script data-cfasync="false">
document.documentElement.dataset.mode = localStorage.getItem("mode") || "";
document.documentElement.dataset.theme = localStorage.getItem("theme") || "";
</script>
<!--
this give us a css class that will be invisible only if js is disabled
-->
<noscript>
<style>
.pst-js-only { display: none !important; }
</style>
</noscript>
<!-- Loaded before other Sphinx assets -->
<link href="_static/styles/theme.css?digest=8878045cc6db502f8baf" rel="stylesheet" />
<link href="_static/styles/pydata-sphinx-theme.css?digest=8878045cc6db502f8baf" rel="stylesheet" />
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=03e43079" />
<!-- So that users can add custom icons -->
<script src="_static/scripts/fontawesome.js?digest=8878045cc6db502f8baf"></script>
<!-- Pre-loaded scripts that we'll load fully later -->
<link rel="preload" as="script" href="_static/scripts/bootstrap.js?digest=8878045cc6db502f8baf" />
<link rel="preload" as="script" href="_static/scripts/pydata-sphinx-theme.js?digest=8878045cc6db502f8baf" />
<script src="_static/documentation_options.js?v=7f41d439"></script>
<script src="_static/doctools.js?v=888ff710"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script>DOCUMENTATION_OPTIONS.pagename = 'nep-0047-array-api-standard';</script>
<link rel="icon" href="_static/favicon.ico"/>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Rejected and Withdrawn NEPs" href="rejected.html" />
<link rel="prev" title="NEP 37 — A dispatch protocol for NumPy-like modules" href="nep-0037-array-module.html" />
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<meta name="docsearch:language" content="en"/>
<meta name="docsearch:version" content="" />
<meta name="docbuild:last-update" content="Feb 11, 2025"/>
</head>
<body data-bs-spy="scroll" data-bs-target=".bd-toc-nav" data-offset="180" data-bs-root-margin="0px 0px -60%" data-default-mode="">
<div id="pst-skip-link" class="skip-link d-print-none"><a href="#main-content">Skip to main content</a></div>
<div id="pst-scroll-pixel-helper"></div>
<button type="button" class="btn rounded-pill" id="pst-back-to-top">
<i class="fa-solid fa-arrow-up"></i>Back to top</button>
<dialog id="pst-search-dialog">
<form class="bd-search d-flex align-items-center"
action="search.html"
method="get">
<i class="fa-solid fa-magnifying-glass"></i>
<input type="search"
class="form-control"
name="q"
placeholder="Search the docs ..."
aria-label="Search the docs ..."
autocomplete="off"
autocorrect="off"
autocapitalize="off"
spellcheck="false"/>
<span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd>K</kbd></span>
</form>
</dialog>
<div class="pst-async-banner-revealer d-none">
<aside id="bd-header-version-warning" class="d-none d-print-none" aria-label="Version warning"></aside>
</div>
<header class="bd-header navbar navbar-expand-lg bd-navbar d-print-none">
<div class="bd-header__inner bd-page-width">
<button class="pst-navbar-icon sidebar-toggle primary-toggle" aria-label="Site navigation">
<span class="fa-solid fa-bars"></span>
</button>
<div class="col-lg-3 navbar-header-items__start">
<div class="navbar-item">
<a class="navbar-brand logo" href="content.html">
<img src="_static/numpylogo.svg" class="logo__image only-light" alt="NumPy Enhancement Proposals - Home"/>
<img src="_static/numpylogo_dark.svg" class="logo__image only-dark pst-js-only" alt="NumPy Enhancement Proposals - Home"/>
</a></div>
</div>
<div class="col-lg-9 navbar-header-items">
<div class="me-auto navbar-header-items__center">
<div class="navbar-item">
<nav>
<ul class="bd-navbar-elements navbar-nav">
<li class="nav-item current active">
<a class="nav-link nav-internal" href="index.html">
Index
</a>
</li>
<li class="nav-item ">
<a class="nav-link nav-internal" href="scope.html">
The Scope of NumPy
</a>
</li>
<li class="nav-item ">
<a class="nav-link nav-internal" href="roadmap.html">
Current roadmap
</a>
</li>
<li class="nav-item ">
<a class="nav-link nav-external" href="https://github.com/numpy/numpy/issues?q=is%3Aopen+is%3Aissue+label%3A%2223+-+Wish+List%22">
Wishlist
</a>
</li>
</ul>
</nav></div>
</div>
<div class="navbar-header-items__end">
<div class="navbar-item navbar-persistent--container">
<button class="btn search-button-field search-button__button pst-js-only" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip">
<i class="fa-solid fa-magnifying-glass"></i>
<span class="search-button__default-text">Search</span>
<span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd class="kbd-shortcut__modifier">K</kbd></span>
</button>
</div>
<div class="navbar-item">
<button class="btn btn-sm nav-link pst-navbar-icon theme-switch-button pst-js-only" aria-label="Color mode" data-bs-title="Color mode" data-bs-placement="bottom" data-bs-toggle="tooltip">
<i class="theme-switch fa-solid fa-sun fa-lg" data-mode="light" title="Light"></i>
<i class="theme-switch fa-solid fa-moon fa-lg" data-mode="dark" title="Dark"></i>
<i class="theme-switch fa-solid fa-circle-half-stroke fa-lg" data-mode="auto" title="System Settings"></i>
</button></div>
<div class="navbar-item"><ul class="navbar-icon-links"
aria-label="Icon Links">
<li class="nav-item">
<a href="https://github.com/numpy/numpy" title="GitHub" class="nav-link pst-navbar-icon" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><i class="fa-brands fa-square-github fa-lg" aria-hidden="true"></i>
<span class="sr-only">GitHub</span></a>
</li>
</ul></div>
</div>
</div>
<div class="navbar-persistent--mobile">
<button class="btn search-button-field search-button__button pst-js-only" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip">
<i class="fa-solid fa-magnifying-glass"></i>
<span class="search-button__default-text">Search</span>
<span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd class="kbd-shortcut__modifier">K</kbd></span>
</button>
</div>
<button class="pst-navbar-icon sidebar-toggle secondary-toggle" aria-label="On this page">
<span class="fa-solid fa-outdent"></span>
</button>
</div>
</header>
<div class="bd-container">
<div class="bd-container__inner bd-page-width">
<dialog id="pst-primary-sidebar-modal"></dialog>
<div id="pst-primary-sidebar" class="bd-sidebar-primary bd-sidebar">
<div class="sidebar-header-items sidebar-primary__section">
<div class="sidebar-header-items__center">
<div class="navbar-item">
<nav>
<ul class="bd-navbar-elements navbar-nav">
<li class="nav-item current active">
<a class="nav-link nav-internal" href="index.html">
Index
</a>
</li>
<li class="nav-item ">
<a class="nav-link nav-internal" href="scope.html">
The Scope of NumPy
</a>
</li>
<li class="nav-item ">
<a class="nav-link nav-internal" href="roadmap.html">
Current roadmap
</a>
</li>
<li class="nav-item ">
<a class="nav-link nav-external" href="https://github.com/numpy/numpy/issues?q=is%3Aopen+is%3Aissue+label%3A%2223+-+Wish+List%22">
Wishlist
</a>
</li>
</ul>
</nav></div>
</div>
<div class="sidebar-header-items__end">
<div class="navbar-item">
<button class="btn btn-sm nav-link pst-navbar-icon theme-switch-button pst-js-only" aria-label="Color mode" data-bs-title="Color mode" data-bs-placement="bottom" data-bs-toggle="tooltip">
<i class="theme-switch fa-solid fa-sun fa-lg" data-mode="light" title="Light"></i>
<i class="theme-switch fa-solid fa-moon fa-lg" data-mode="dark" title="Dark"></i>
<i class="theme-switch fa-solid fa-circle-half-stroke fa-lg" data-mode="auto" title="System Settings"></i>
</button></div>
<div class="navbar-item"><ul class="navbar-icon-links"
aria-label="Icon Links">
<li class="nav-item">
<a href="https://github.com/numpy/numpy" title="GitHub" class="nav-link pst-navbar-icon" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><i class="fa-brands fa-square-github fa-lg" aria-hidden="true"></i>
<span class="sr-only">GitHub</span></a>
</li>
</ul></div>
</div>
</div>
<div class="sidebar-primary-items__start sidebar-primary__section">
<div class="sidebar-primary-item">
<nav class="bd-docs-nav bd-links"
aria-label="Section Navigation">
<p class="bd-links__title" role="heading" aria-level="1">Section Navigation</p>
<div class="bd-toc-item navbar-nav"><ul class="nav bd-sidenav">
<li class="toctree-l1"><a class="reference internal" href="scope.html">The Scope of NumPy</a></li>
<li class="toctree-l1"><a class="reference internal" href="roadmap.html">Current roadmap</a></li>
</ul>
<ul class="current nav bd-sidenav">
<li class="toctree-l1 has-children"><a class="reference internal" href="meta.html">Meta-NEPs (NEPs about NEPs or active Processes)</a><details><summary><span class="toctree-toggle" role="presentation"><i class="fa-solid fa-chevron-down"></i></span></summary><ul>
<li class="toctree-l2"><a class="reference internal" href="nep-0000.html">NEP 0 — Purpose and process</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0023-backwards-compatibility.html">NEP 23 — Backwards compatibility and deprecation policy</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0036-fair-play.html">NEP 36 — Fair play</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0045-c_style_guide.html">NEP 45 — C style guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0046-sponsorship-guidelines.html">NEP 46 — NumPy sponsorship guidelines</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0048-spending-project-funds.html">NEP 48 — Spending NumPy project funds</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-template.html">NEP X — Template and instructions</a></li>
</ul>
</details></li>
<li class="toctree-l1 has-children"><a class="reference internal" href="provisional.html">Provisional NEPs (provisionally accepted; interface may change)</a><details><summary><span class="toctree-toggle" role="presentation"><i class="fa-solid fa-chevron-down"></i></span></summary><ul class="simple">
</ul>
</details></li>
<li class="toctree-l1 has-children"><a class="reference internal" href="accepted.html">Accepted NEPs (implementation in progress)</a><details><summary><span class="toctree-toggle" role="presentation"><i class="fa-solid fa-chevron-down"></i></span></summary><ul>
<li class="toctree-l2"><a class="reference internal" href="nep-0041-improved-dtype-support.html">NEP 41 — First step towards a new datatype system</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0042-new-dtypes.html">NEP 42 — New and extensible DTypes</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0044-restructuring-numpy-docs.html">NEP 44 — Restructuring the NumPy documentation</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0051-scalar-representation.html">NEP 51 — Changing the representation of NumPy scalars</a></li>
</ul>
</details></li>
<li class="toctree-l1 has-children"><a class="reference internal" href="open.html">Open NEPs (under consideration)</a><details><summary><span class="toctree-toggle" role="presentation"><i class="fa-solid fa-chevron-down"></i></span></summary><ul>
<li class="toctree-l2"><a class="reference internal" href="nep-0043-extensible-ufuncs.html">NEP 43 — Enhancing the extensibility of UFuncs</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0053-c-abi-evolution.html">NEP 53 — Evolving the NumPy C-API for NumPy 2.0</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0054-simd-cpp-highway.html">NEP 54 — SIMD infrastructure evolution: adopting Google Highway when moving to C++?</a></li>
</ul>
</details></li>
<li class="toctree-l1 has-children"><a class="reference internal" href="finished.html">Finished NEPs</a><details><summary><span class="toctree-toggle" role="presentation"><i class="fa-solid fa-chevron-down"></i></span></summary><ul>
<li class="toctree-l2"><a class="reference internal" href="nep-0001-npy-format.html">NEP 1 — A simple file format for NumPy arrays</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0005-generalized-ufuncs.html">NEP 5 — Generalized universal functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0007-datetime-proposal.html">NEP 7 — A proposal for implementing some date/time types in NumPy</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0010-new-iterator-ufunc.html">NEP 10 — Optimizing iterator/UFunc performance</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0013-ufunc-overrides.html">NEP 13 — A mechanism for overriding Ufuncs</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0014-dropping-python2.7-proposal.html">NEP 14 — Plan for dropping Python 2.7 support</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0015-merge-multiarray-umath.html">NEP 15 — Merging multiarray and umath</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0018-array-function-protocol.html">NEP 18 — A dispatch mechanism for NumPy's high level array functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0019-rng-policy.html">NEP 19 — Random number generator policy</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0020-gufunc-signature-enhancement.html">NEP 20 — Expansion of generalized universal function signatures</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0022-ndarray-duck-typing-overview.html">NEP 22 — Duck typing for NumPy arrays – high level overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0027-zero-rank-arrarys.html">NEP 27 — Zero rank arrays</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0028-website-redesign.html">NEP 28 — numpy.org website redesign</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0029-deprecation_policy.html">NEP 29 — Recommend Python and NumPy version support as a community policy standard</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0032-remove-financial-functions.html">NEP 32 — Remove the financial functions from NumPy</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0034-infer-dtype-is-object.html">NEP 34 — Disallow inferring ``dtype=object`` from sequences</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0035-array-creation-dispatch-with-array-function.html">NEP 35 — Array creation dispatching with __array_function__</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0038-SIMD-optimizations.html">NEP 38 — Using SIMD optimization instructions for performance</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0040-legacy-datatype-impl.html">NEP 40 — Legacy datatype implementation in NumPy</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0049.html">NEP 49 — Data allocation strategies</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0050-scalar-promotion.html">NEP 50 — Promotion rules for Python scalars</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0052-python-api-cleanup.html">NEP 52 — Python API cleanup for NumPy 2.0</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0055-string_dtype.html">NEP 55 — Add a UTF-8 variable-width string DType to NumPy</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0056-array-api-main-namespace.html">NEP 56 — Array API standard support in NumPy's main namespace</a></li>
</ul>
</details></li>
<li class="toctree-l1 current active has-children"><a class="reference internal" href="deferred.html">Deferred and Superseded NEPs</a><details open="open"><summary><span class="toctree-toggle" role="presentation"><i class="fa-solid fa-chevron-down"></i></span></summary><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="nep-0002-warnfix.html">NEP 2 — A proposal to build numpy without warning with a big set of warning flags</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0003-math_config_clean.html">NEP 3 — Cleaning the math configuration of numpy.core</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0004-datetime-proposal3.html">NEP 4 — A (third) proposal for implementing some date/time types in NumPy</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0006-newbugtracker.html">NEP 6 — Replacing Trac with a different bug tracker</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0008-groupby_additions.html">NEP 8 — A proposal for adding groupby functionality to NumPy</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0009-structured_array_extensions.html">NEP 9 — Structured array extensions</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0011-deferred-ufunc-evaluation.html">NEP 11 — Deferred UFunc evaluation</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0012-missing-data.html">NEP 12 — Missing data functionality in NumPy</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0021-advanced-indexing.html">NEP 21 — Simplified and explicit advanced indexing</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0024-missing-data-2.html">NEP 24 — Missing data functionality - alternative 1 to NEP 12</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0025-missing-data-3.html">NEP 25 — NA support via special dtypes</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0026-missing-data-summary.html">NEP 26 — Summary of missing data NEPs and discussion</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0030-duck-array-protocol.html">NEP 30 — Duck typing for NumPy arrays - implementation</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0031-uarray.html">NEP 31 — Context-local and global overrides of the NumPy API</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0037-array-module.html">NEP 37 — A dispatch protocol for NumPy-like modules</a></li>
<li class="toctree-l2 current active"><a class="current reference internal" href="#">NEP 47 — Adopting the array API standard</a></li>
</ul>
</details></li>
<li class="toctree-l1 has-children"><a class="reference internal" href="rejected.html">Rejected and Withdrawn NEPs</a><details><summary><span class="toctree-toggle" role="presentation"><i class="fa-solid fa-chevron-down"></i></span></summary><ul>
<li class="toctree-l2"><a class="reference internal" href="nep-0016-abstract-array.html">NEP 16 — An abstract base class for identifying "duck arrays"</a></li>
<li class="toctree-l2"><a class="reference internal" href="nep-0017-split-out-maskedarray.html">NEP 17 — Split out masked arrays</a></li>
</ul>
</details></li>
</ul>
</div>
</nav></div>
</div>
<div class="sidebar-primary-items__end sidebar-primary__section">
<div class="sidebar-primary-item">
<div id="ethical-ad-placement"
class="flat"
data-ea-publisher="readthedocs"
data-ea-type="readthedocs-sidebar"
data-ea-manual="true">
</div></div>
</div>
</div>
<main id="main-content" class="bd-main" role="main">
<div class="bd-content">
<div class="bd-article-container">
<div class="bd-header-article d-print-none">
<div class="header-article-items header-article__inner">
<div class="header-article-items__start">
<div class="header-article-item">
<nav aria-label="Breadcrumb" class="d-print-none">
<ul class="bd-breadcrumbs">
<li class="breadcrumb-item breadcrumb-home">
<a href="content.html" class="nav-link" aria-label="Home">
<i class="fa-solid fa-home"></i>
</a>
</li>
<li class="breadcrumb-item"><a href="index.html" class="nav-link">Roadmap & NumPy enhancement proposals</a></li>
<li class="breadcrumb-item"><a href="deferred.html" class="nav-link">Deferred and Superseded NEPs</a></li>
<li class="breadcrumb-item active" aria-current="page"><span class="ellipsis">NEP 47 — Adopting the array API standard</span></li>
</ul>
</nav>
</div>
</div>
</div>
</div>
<div id="searchbox"></div>
<article class="bd-article">
<section id="nep-47-adopting-the-array-api-standard">
<span id="nep47"></span><h1>NEP 47 — Adopting the array API standard<a class="headerlink" href="#nep-47-adopting-the-array-api-standard" title="Link to this heading">#</a></h1>
<dl class="field-list simple">
<dt class="field-odd">Author<span class="colon">:</span></dt>
<dd class="field-odd"><p>Ralf Gommers <<a class="reference external" href="mailto:ralf.gommers%40gmail.com">ralf<span>.</span>gommers<span>@</span>gmail<span>.</span>com</a>></p>
</dd>
<dt class="field-even">Author<span class="colon">:</span></dt>
<dd class="field-even"><p>Stephan Hoyer <<a class="reference external" href="mailto:shoyer%40gmail.com">shoyer<span>@</span>gmail<span>.</span>com</a>></p>
</dd>
<dt class="field-odd">Author<span class="colon">:</span></dt>
<dd class="field-odd"><p>Aaron Meurer <<a class="reference external" href="mailto:asmeurer%40gmail.com">asmeurer<span>@</span>gmail<span>.</span>com</a>></p>
</dd>
<dt class="field-even">Status<span class="colon">:</span></dt>
<dd class="field-even"><p>Superseded</p>
</dd>
<dt class="field-odd">Replaced-By<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference internal" href="nep-0056-array-api-main-namespace.html#nep56"><span class="std std-ref">NEP 56 — Array API standard support in NumPy’s main namespace</span></a></p>
</dd>
<dt class="field-even">Type<span class="colon">:</span></dt>
<dd class="field-even"><p>Standards Track</p>
</dd>
<dt class="field-odd">Created<span class="colon">:</span></dt>
<dd class="field-odd"><p>2021-01-21</p>
</dd>
<dt class="field-even">Resolution<span class="colon">:</span></dt>
<dd class="field-even"><p><a class="reference external" href="https://mail.python.org/archives/list/numpy-discussion@python.org/message/Z6AA5CL47NHBNEPTFWYOTSUVSRDGHYPN/">https://mail.python.org/archives/list/numpy-discussion@python.org/message/Z6AA5CL47NHBNEPTFWYOTSUVSRDGHYPN/</a></p>
</dd>
</dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This NEP was implemented and released under an experimental label (it
emitted a warning on import) in NumPy 1.22.0-1.26.x. It was removed before
NumPy 2.0.0, which is when NumPy gained support for the array API standard
in its main namespace (see <a class="reference internal" href="nep-0056-array-api-main-namespace.html#nep56"><span class="std std-ref">NEP 56 — Array API standard support in NumPy’s main namespace</span></a>). The code for <code class="docutils literal notranslate"><span class="pre">numpy.array_api</span></code>
was moved to a standalone package: <a class="reference external" href="https://github.com/data-apis/array-api-strict">array-api-strict</a>. For a detailed overview
of the differences between the last version of the <code class="docutils literal notranslate"><span class="pre">numpy.array_api</span></code>
module with <code class="docutils literal notranslate"><span class="pre">numpy</span></code>, see <a class="reference external" href="https://numpy.org/doc/1.26/reference/array_api.html#table-of-differences-between-numpy-array-api-and-numpy">this table in the 1.26.x docs</a>.</p>
</div>
<section id="abstract">
<h2>Abstract<a class="headerlink" href="#abstract" title="Link to this heading">#</a></h2>
<p>We propose to adopt the <a class="reference external" href="https://data-apis.github.io/array-api/latest">Python array API standard</a>, developed by the
<a class="reference external" href="https://data-apis.org/">Consortium for Python Data API Standards</a>. Implementing this as a separate
new namespace in NumPy will allow authors of libraries which depend on NumPy
as well as end users to write code that is portable between NumPy and all
other array/tensor libraries that adopt this standard.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>We expect that this NEP will remain in a draft state for quite a while.
Given the large scope we don’t expect to propose it for acceptance any
time soon; instead, we want to solicit feedback on both the high-level
design and implementation, and learn what needs describing better in this
NEP or changing in either the implementation or the array API standard
itself.</p>
</div>
</section>
<section id="motivation-and-scope">
<h2>Motivation and scope<a class="headerlink" href="#motivation-and-scope" title="Link to this heading">#</a></h2>
<p>Python users have a wealth of choice for libraries and frameworks for
numerical computing, data science, machine learning, and deep learning. New
frameworks pushing forward the state of the art in these fields are appearing
every year. One unintended consequence of all this activity and creativity
has been fragmentation in multidimensional array (a.k.a. tensor) libraries -
which are the fundamental data structure for these fields. Choices include
NumPy, Tensorflow, PyTorch, Dask, JAX, CuPy, MXNet, and others.</p>
<p>The APIs of each of these libraries are largely similar, but with enough
differences that it’s quite difficult to write code that works with multiple
(or all) of these libraries. The array API standard aims to address that
issue, by specifying an API for the most common ways arrays are constructed
and used. The proposed API is quite similar to NumPy’s API, and deviates mainly
in places where (a) NumPy made design choices that are inherently not portable
to other implementations, and (b) where other libraries consistently deviated
from NumPy on purpose because NumPy’s design turned out to have issues or
unnecessary complexity.</p>
<p>For a longer discussion on the purpose of the array API standard we refer to
the <a class="reference external" href="https://data-apis.github.io/array-api/latest/purpose_and_scope.html">Purpose and Scope section of the array API standard</a>
and the two blog posts announcing the formation of the Consortium <a class="footnote-reference brackets" href="#id6" id="id1" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a> and
the release of the first draft version of the standard for community review <a class="footnote-reference brackets" href="#id7" id="id2" role="doc-noteref"><span class="fn-bracket">[</span>2<span class="fn-bracket">]</span></a>.</p>
<p>The scope of this NEP includes:</p>
<ul class="simple">
<li><p>Adopting the 2021 version of the array API standard</p></li>
<li><p>Adding a separate namespace, tentatively named <code class="docutils literal notranslate"><span class="pre">numpy.array_api</span></code></p></li>
<li><p>Changes needed/desired outside of the new namespace, for example new dunder
methods on the <code class="docutils literal notranslate"><span class="pre">ndarray</span></code> object</p></li>
<li><p>Implementation choices, and differences between functions in the new
namespace with those in the main <code class="docutils literal notranslate"><span class="pre">numpy</span></code> namespace</p></li>
<li><p>A new array object conforming to the array API standard</p></li>
<li><p>Maintenance effort and testing strategy</p></li>
<li><p>Impact on NumPy’s total exposed API surface and on other future and
under-discussion design choices</p></li>
<li><p>Relation to existing and proposed NumPy array protocols
(<code class="docutils literal notranslate"><span class="pre">__array_ufunc__</span></code>, <code class="docutils literal notranslate"><span class="pre">__array_function__</span></code>, <code class="docutils literal notranslate"><span class="pre">__array_module__</span></code>).</p></li>
<li><p>Required improvements to existing NumPy functionality</p></li>
</ul>
<p>Out of scope for this NEP are:</p>
<ul class="simple">
<li><p>Changes in the array API standard itself. Those are likely to come up
during review of this NEP, but should be upstreamed as needed and this NEP
subsequently updated.</p></li>
</ul>
</section>
<section id="usage-and-impact">
<h2>Usage and impact<a class="headerlink" href="#usage-and-impact" title="Link to this heading">#</a></h2>
<p><em>This section will be fleshed out later, for now we refer to the use cases given
in</em> <a class="reference external" href="https://data-apis.github.io/array-api/latest/use_cases.html">the array API standard Use Cases section</a></p>
<p>In addition to those use cases, the new namespace contains functionality that
is widely used and supported by many array libraries. As such, it is a good
set of functions to teach to newcomers to NumPy and recommend as “best
practice”. That contrasts with NumPy’s main namespace, which contains many
functions and objects that have been superseded or we consider mistakes - but
that we can’t remove because of backwards compatibility reasons.</p>
<p>The usage of the <code class="docutils literal notranslate"><span class="pre">numpy.array_api</span></code> namespace by downstream libraries is
intended to enable them to consume multiple kinds of arrays, <em>without having
to have a hard dependency on all of those array libraries</em>:</p>
<img alt="_images/nep-0047-library-dependencies.png" src="_images/nep-0047-library-dependencies.png" />
<section id="adoption-in-downstream-libraries">
<h3>Adoption in downstream libraries<a class="headerlink" href="#adoption-in-downstream-libraries" title="Link to this heading">#</a></h3>
<p>The prototype implementation of the <code class="docutils literal notranslate"><span class="pre">array_api</span></code> namespace will be used with
SciPy, scikit-learn, and other libraries of interest that depend on NumPy, in
order to get more experience with the design and find out if any important
parts are missing.</p>
<p>The pattern to support multiple array libraries is intended to be something
like:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">somefunc</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">):</span>
<span class="c1"># Retrieves standard namespace. Raises if x and y have different</span>
<span class="c1"># namespaces. See Appendix for possible get_namespace implementation</span>
<span class="n">xp</span> <span class="o">=</span> <span class="n">get_namespace</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">)</span>
<span class="n">out</span> <span class="o">=</span> <span class="n">xp</span><span class="o">.</span><span class="n">mean</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">axis</span><span class="o">=</span><span class="mi">0</span><span class="p">)</span> <span class="o">+</span> <span class="mi">2</span><span class="o">*</span><span class="n">xp</span><span class="o">.</span><span class="n">std</span><span class="p">(</span><span class="n">y</span><span class="p">,</span> <span class="n">axis</span><span class="o">=</span><span class="mi">0</span><span class="p">)</span>
<span class="k">return</span> <span class="n">out</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">get_namespace</span></code> call is effectively the library author opting in to
using the standard API namespace, and thereby explicitly supporting
all conforming array libraries.</p>
<section id="the-asarray-asanyarray-pattern">
<h4>The <code class="docutils literal notranslate"><span class="pre">asarray</span></code> / <code class="docutils literal notranslate"><span class="pre">asanyarray</span></code> pattern<a class="headerlink" href="#the-asarray-asanyarray-pattern" title="Link to this heading">#</a></h4>
<p>Many existing libraries use the same <code class="docutils literal notranslate"><span class="pre">asarray</span></code> (or <code class="docutils literal notranslate"><span class="pre">asanyarray</span></code>) pattern
as NumPy itself does; accepting any object that can be coerced into a <code class="docutils literal notranslate"><span class="pre">np.ndarray</span></code>.
We consider this design pattern problematic - keeping in mind the Zen of
Python, <em>“explicit is better than implicit”</em>, as well as the pattern being
historically problematic in the SciPy ecosystem for <code class="docutils literal notranslate"><span class="pre">ndarray</span></code> subclasses
and with over-eager object creation. All other array/tensor libraries are
more strict, and that works out fine in practice. We would advise authors of
new libraries to avoid the <code class="docutils literal notranslate"><span class="pre">asarray</span></code> pattern. Instead they should either
accept just NumPy arrays or, if they want to support multiple kinds of
arrays, check if the incoming array object supports the array API standard
by checking for <code class="docutils literal notranslate"><span class="pre">__array_namespace__</span></code> as shown in the example above.</p>
<p>Existing libraries can do such a check as well, and only call <code class="docutils literal notranslate"><span class="pre">asarray</span></code> if
the check fails. This is very similar to the <code class="docutils literal notranslate"><span class="pre">__duckarray__</span></code> idea in
<a class="reference internal" href="nep-0030-duck-array-protocol.html#nep30"><span class="std std-ref">NEP 30 — Duck typing for NumPy arrays - implementation</span></a>.</p>
</section>
</section>
<section id="adoption-in-application-code">
<span id="adoption-application-code"></span><h3>Adoption in application code<a class="headerlink" href="#adoption-in-application-code" title="Link to this heading">#</a></h3>
<p>The new namespace can be seen by end users as a cleaned up and slimmed down
version of NumPy’s main namespace. Encouraging end users to use this
namespace like:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">numpy.array_api</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="nn">xp</span>
<span class="n">x</span> <span class="o">=</span> <span class="n">xp</span><span class="o">.</span><span class="n">linspace</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">2</span><span class="o">*</span><span class="n">xp</span><span class="o">.</span><span class="n">pi</span><span class="p">,</span> <span class="n">num</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span>
<span class="n">y</span> <span class="o">=</span> <span class="n">xp</span><span class="o">.</span><span class="n">cos</span><span class="p">(</span><span class="n">x</span><span class="p">)</span>
</pre></div>
</div>
<p>seems perfectly reasonable, and potentially beneficial - users get offered only
one function for each purpose (the one we consider best-practice), and they
then write code that is more easily portable to other libraries.</p>
</section>
</section>
<section id="backward-compatibility">
<h2>Backward compatibility<a class="headerlink" href="#backward-compatibility" title="Link to this heading">#</a></h2>
<p>No deprecations or removals of existing NumPy APIs or other backwards
incompatible changes are proposed.</p>
</section>
<section id="high-level-design">
<h2>High-level design<a class="headerlink" href="#high-level-design" title="Link to this heading">#</a></h2>
<p>The array API standard consists of approximately 120 objects, all of which
have a direct NumPy equivalent. This figure shows what is included at a high level:</p>
<img alt="_images/nep-0047-scope-of-array-API.png" src="_images/nep-0047-scope-of-array-API.png" />
<p>The most important changes compared to what NumPy currently offers are:</p>
<ul>
<li><p>A new array object, <code class="docutils literal notranslate"><span class="pre">numpy.array_api.Array</span></code> which:</p>
<blockquote>
<div><ul class="simple">
<li><p>is a thin pure Python (non-subclass) wrapper around <code class="docutils literal notranslate"><span class="pre">np.ndarray</span></code>,</p></li>
<li><p>conforms to the casting rules and indexing behavior specified by the
standard,</p></li>
<li><p>does not have methods other than dunder methods,</p></li>
<li><p>does not support the full range of NumPy indexing behavior (see
<a class="reference internal" href="#indexing"><span class="std std-ref">Indexing</span></a> below),</p></li>
<li><p>does not have distinct scalar objects, only 0-D arrays,</p></li>
<li><p>cannot be constructed directly. Instead array construction functions
like <code class="docutils literal notranslate"><span class="pre">asarray()</span></code> should be used.</p></li>
</ul>
</div></blockquote>
</li>
<li><p>Functions in the <code class="docutils literal notranslate"><span class="pre">array_api</span></code> namespace:</p>
<blockquote>
<div><ul class="simple">
<li><p>do not accept <code class="docutils literal notranslate"><span class="pre">array_like</span></code> inputs, only <code class="docutils literal notranslate"><span class="pre">numpy.array_api</span></code> array
objects, with Python scalars only being supported in dunder operators on
the array object,</p></li>
<li><p>do not support <code class="docutils literal notranslate"><span class="pre">__array_ufunc__</span></code> and <code class="docutils literal notranslate"><span class="pre">__array_function__</span></code>,</p></li>
<li><p>use positional-only and keyword-only parameters in their signatures,</p></li>
<li><p>have inline type annotations,</p></li>
<li><p>may have minor changes to signatures and semantics of individual
functions compared to their equivalents already present in NumPy,</p></li>
<li><p>only support dtype literals, not format strings or other ways of
specifying dtypes,</p></li>
<li><p>generally may only support a restricted set of dtypes compared to their
NumPy counterparts.</p></li>
</ul>
</div></blockquote>
</li>
<li><p><a class="reference external" href="https://github.com/dmlc/dlpack">DLPack</a> support will be added to NumPy,</p></li>
<li><p>New syntax for “device support” will be added, through a <code class="docutils literal notranslate"><span class="pre">.device</span></code>
attribute on the new array object, and <code class="docutils literal notranslate"><span class="pre">device=</span></code> keywords in array creation
functions in the <code class="docutils literal notranslate"><span class="pre">array_api</span></code> namespace,</p></li>
<li><p>Casting rules will differ from those NumPy currently has. Output dtypes can
be derived from input dtypes (i.e. no value-based casting), and 0-D arrays
are treated like >=1-D arrays. Cross-kind casting (e.g., int to float) is
not allowed.</p></li>
<li><p>Not all dtypes NumPy has are part of the standard. Only boolean, signed and
unsigned integers, and floating-point dtypes up to <code class="docutils literal notranslate"><span class="pre">float64</span></code> are supported.
Complex dtypes are expected to be added in the next version of the standard.
Extended precision, string, void, object and datetime dtypes, as well as
structured dtypes, are not included.</p></li>
</ul>
<p>Improvements to existing NumPy functionality that are needed include:</p>
<ul class="simple">
<li><p>Add support for stacks of matrices to some functions in <code class="docutils literal notranslate"><span class="pre">numpy.linalg</span></code>
that are currently missing such support.</p></li>
<li><p>Add the <code class="docutils literal notranslate"><span class="pre">keepdims</span></code> keyword to <code class="docutils literal notranslate"><span class="pre">np.argmin</span></code> and <code class="docutils literal notranslate"><span class="pre">np.argmax</span></code>.</p></li>
<li><p>Add a “never copy” mode to <code class="docutils literal notranslate"><span class="pre">np.asarray</span></code>.</p></li>
<li><p>Add smallest_normal to <code class="docutils literal notranslate"><span class="pre">np.finfo()</span></code>.</p></li>
<li><p><a class="reference external" href="https://github.com/dmlc/dlpack">DLPack</a> support.</p></li>
</ul>
<p>Additionally, the <code class="docutils literal notranslate"><span class="pre">numpy.array_api</span></code> implementation was chosen to be a
<em>minimal</em> implementation of the array API standard. This means that it not
only conforms to all the requirements of the array API, but it explicitly does
not include any APIs or behaviors not explicitly required by it. The standard
itself does not require implementations to be so restrictive, but doing this
with the NumPy array API implementation will allow it to become a canonical
implementation of the array API standard. Anyone who wants to make use of the
array API standard can use the NumPy implementation and be sure that their
code is not making use of behaviors that will not be in other conforming
implementations.</p>
<p>In particular, this means</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">numpy.array_api</span></code> will only include those functions that are listed in the
standard. This also applies to methods on the <code class="docutils literal notranslate"><span class="pre">Array</span></code> object,</p></li>
<li><p>Functions will only accept input dtypes that are required by the standard
(e.g., transcendental functions like <code class="docutils literal notranslate"><span class="pre">cos</span></code> will not accept integer dtypes
because the standard only requires them to accept floating-point dtypes),</p></li>
<li><p>Type promotion will only occur for combinations of dtypes required by the
standard (see the <a class="reference internal" href="#dtypes-and-casting-rules"><span class="std std-ref">Dtypes and casting rules</span></a> section below),</p></li>
<li><p>Indexing is limited to a subset of possible index types (see <a class="reference internal" href="#indexing"><span class="std std-ref">Indexing</span></a>
below).</p></li>
</ul>
<section id="functions-in-the-array-api-namespace">
<h3>Functions in the <code class="docutils literal notranslate"><span class="pre">array_api</span></code> namespace<a class="headerlink" href="#functions-in-the-array-api-namespace" title="Link to this heading">#</a></h3>
<p>Let’s start with an example of a function implementation that shows the most
important differences with the equivalent function in the main namespace:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">matmul</span><span class="p">(</span><span class="n">x1</span><span class="p">:</span> <span class="n">Array</span><span class="p">,</span> <span class="n">x2</span><span class="p">:</span> <span class="n">Array</span><span class="p">,</span> <span class="o">/</span><span class="p">)</span> <span class="o">-></span> <span class="n">Array</span><span class="p">:</span>
<span class="w"> </span><span class="sd">"""</span>
<span class="sd"> Array API compatible wrapper for :py:func:`np.matmul <numpy.matmul>`.</span>
<span class="sd"> See its docstring for more information.</span>
<span class="sd"> """</span>
<span class="k">if</span> <span class="n">x1</span><span class="o">.</span><span class="n">dtype</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">_numeric_dtypes</span> <span class="ow">or</span> <span class="n">x2</span><span class="o">.</span><span class="n">dtype</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">_numeric_dtypes</span><span class="p">:</span>
<span class="k">raise</span> <span class="ne">TypeError</span><span class="p">(</span><span class="s2">"Only numeric dtypes are allowed in matmul"</span><span class="p">)</span>
<span class="c1"># Call result type here just to raise on disallowed type combinations</span>
<span class="n">_result_type</span><span class="p">(</span><span class="n">x1</span><span class="o">.</span><span class="n">dtype</span><span class="p">,</span> <span class="n">x2</span><span class="o">.</span><span class="n">dtype</span><span class="p">)</span>
<span class="k">return</span> <span class="n">Array</span><span class="o">.</span><span class="n">_new</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">matmul</span><span class="p">(</span><span class="n">x1</span><span class="o">.</span><span class="n">_array</span><span class="p">,</span> <span class="n">x2</span><span class="o">.</span><span class="n">_array</span><span class="p">))</span>
</pre></div>
</div>
<p>This function does not accept <code class="docutils literal notranslate"><span class="pre">array_like</span></code> inputs, only
<code class="docutils literal notranslate"><span class="pre">numpy.array_api.Array</span></code>. There are multiple reasons for this. Other array
libraries all work like this. Requiring the user to do coercion of Python
scalars, lists, generators, or other foreign objects explicitly results in a
cleaner design with less unexpected behavior. It is higher-performance—less
overhead from <code class="docutils literal notranslate"><span class="pre">asarray</span></code> calls. Static typing is easier. Subclasses will work
as expected. And the slight increase in verbosity because users have to
explicitly coerce to <code class="docutils literal notranslate"><span class="pre">ndarray</span></code> on rare occasions seems like a small price to
pay.</p>
<p>This function does not support <code class="docutils literal notranslate"><span class="pre">__array_ufunc__</span></code> nor <code class="docutils literal notranslate"><span class="pre">__array_function__</span></code>.
These protocols serve a similar purpose as the array API standard module itself,
but through a different mechanisms. Because only <code class="docutils literal notranslate"><span class="pre">Array</span></code> instances are accepted,
dispatching via one of these protocols isn’t useful anymore.</p>
<p>This function uses positional-only parameters in its signature. This makes
code more portable—writing, for instance, <code class="docutils literal notranslate"><span class="pre">max(a=a,</span> <span class="pre">...)</span></code> is no longer
valid, hence if other libraries call the first parameter <code class="docutils literal notranslate"><span class="pre">input</span></code> rather than
<code class="docutils literal notranslate"><span class="pre">a</span></code>, that is fine. Note that NumPy already uses positional-only arguments
for functions that are ufuncs. The rationale for keyword-only parameters (not
shown in the above example) is two-fold: clarity of end user code, and it
being easier to extend the signature in the future without worrying about the
order of keywords.</p>
<p>This function has inline type annotations. Inline annotations are far easier to
maintain than separate stub files. And because the types are simple, this will
not result in a large amount of clutter with type aliases or unions like in the
current stub files NumPy has.</p>
<p>This function only accepts numeric dtypes (i.e., not <code class="docutils literal notranslate"><span class="pre">bool</span></code>). It also does
not allow the input dtypes to be of different kinds (the internal
<code class="docutils literal notranslate"><span class="pre">_result_type()</span></code> function will raise <code class="docutils literal notranslate"><span class="pre">TypeError</span></code> on cross-kind type
combinations like <code class="docutils literal notranslate"><span class="pre">_result_type(int32,</span> <span class="pre">float64)</span></code>). This allows the
implementation to be minimal. Preventing combinations that work in NumPy but
are not required by the array API specification lets users of the submodule
know they are not relying on NumPy specific behavior that may not be present
in array API conforming implementations from other libraries.</p>
</section>
<section id="dlpack-support-for-zero-copy-data-interchange">
<h3>DLPack support for zero-copy data interchange<a class="headerlink" href="#dlpack-support-for-zero-copy-data-interchange" title="Link to this heading">#</a></h3>
<p>The ability to convert one kind of array into another kind is valuable, and
indeed necessary when downstream libraries want to support multiple kinds of
arrays. This requires a well-specified data exchange protocol. NumPy already
supports two of these, namely the buffer protocol (i.e., PEP 3118), and
the <code class="docutils literal notranslate"><span class="pre">__array_interface__</span></code> (Python side) / <code class="docutils literal notranslate"><span class="pre">__array_struct__</span></code> (C side)
protocol. Both work similarly, letting the “producer” describe how the data
is laid out in memory so the “consumer” can construct its own kind of array
with a view on that data.</p>
<p>DLPack works in a very similar way. The main reasons to prefer DLPack over
the options already present in NumPy are:</p>
<ol class="arabic simple">
<li><p>DLPack is the only protocol with device support (e.g., GPUs using CUDA or
ROCm drivers, or OpenCL devices). NumPy is CPU-only, but other array
libraries are not. Having one protocol per device isn’t tenable, hence
device support is a must.</p></li>
<li><p>Widespread support. DLPack has the widest adoption of all protocols. Only
NumPy is missing support, and the experiences of other libraries with it
are positive. This contrasts with the protocols NumPy does support, which
are used very little—when other libraries want to interoperate with
NumPy, they typically use the (more limited, and NumPy-specific)
<code class="docutils literal notranslate"><span class="pre">__array__</span></code> protocol.</p></li>
</ol>
<p>Adding support for DLPack to NumPy entails:</p>
<ul class="simple">
<li><p>Adding a <code class="docutils literal notranslate"><span class="pre">ndarray.__dlpack__()</span></code> method which returns a <code class="docutils literal notranslate"><span class="pre">dlpack</span></code> C
structure wrapped in a <code class="docutils literal notranslate"><span class="pre">PyCapsule</span></code>.</p></li>
<li><p>Adding a <code class="docutils literal notranslate"><span class="pre">np.from_dlpack(obj)</span></code> function, where <code class="docutils literal notranslate"><span class="pre">obj</span></code> supports
<code class="docutils literal notranslate"><span class="pre">__dlpack__()</span></code>, and returns an <code class="docutils literal notranslate"><span class="pre">ndarray</span></code>.</p></li>
</ul>
<p>DLPack is currently a ~200 LoC header, and is meant to be included directly, so
no external dependency is needed. Implementation should be straightforward.</p>
</section>
<section id="syntax-for-device-support">
<h3>Syntax for device support<a class="headerlink" href="#syntax-for-device-support" title="Link to this heading">#</a></h3>
<p>NumPy itself is CPU-only, so it clearly doesn’t have a need for device support.
However, other libraries (e.g. TensorFlow, PyTorch, JAX, MXNet) support
multiple types of devices: CPU, GPU, TPU, and more exotic hardware.
To write portable code on systems with multiple devices, it’s often necessary
to create new arrays on the same device as some other array, or to check that
two arrays live on the same device. Hence syntax for that is needed.</p>
<p>The array object will have a <code class="docutils literal notranslate"><span class="pre">.device</span></code> attribute which enables comparing
devices of different arrays (they only should compare equal if both arrays are
from the same library and it’s the same hardware device). Furthermore,
<code class="docutils literal notranslate"><span class="pre">device=</span></code> keywords in array creation functions are needed. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">empty</span><span class="p">(</span><span class="n">shape</span><span class="p">:</span> <span class="n">Union</span><span class="p">[</span><span class="nb">int</span><span class="p">,</span> <span class="n">Tuple</span><span class="p">[</span><span class="nb">int</span><span class="p">,</span> <span class="o">...</span><span class="p">]],</span> <span class="o">/</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span>
<span class="n">dtype</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="n">dtype</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
<span class="n">device</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="n">device</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">)</span> <span class="o">-></span> <span class="n">Array</span><span class="p">:</span>
<span class="w"> </span><span class="sd">"""</span>
<span class="sd"> Array API compatible wrapper for :py:func:`np.empty <numpy.empty>`.</span>
<span class="sd"> """</span>
<span class="k">if</span> <span class="n">device</span> <span class="ow">not</span> <span class="ow">in</span> <span class="p">[</span><span class="s2">"cpu"</span><span class="p">,</span> <span class="kc">None</span><span class="p">]:</span>
<span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Unsupported device </span><span class="si">{</span><span class="n">device</span><span class="si">!r}</span><span class="s2">"</span><span class="p">)</span>
<span class="k">return</span> <span class="n">Array</span><span class="o">.</span><span class="n">_new</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">empty</span><span class="p">(</span><span class="n">shape</span><span class="p">,</span> <span class="n">dtype</span><span class="o">=</span><span class="n">dtype</span><span class="p">))</span>
</pre></div>
</div>
<p>The implementation for NumPy is as simple as setting the device attribute to
the string <code class="docutils literal notranslate"><span class="pre">"cpu"</span></code> and raising an exception if array creation functions
encounter any other value.</p>
</section>
<section id="dtypes-and-casting-rules">
<span id="id3"></span><h3>Dtypes and casting rules<a class="headerlink" href="#dtypes-and-casting-rules" title="Link to this heading">#</a></h3>
<p>The supported dtypes in this namespace are boolean, 8/16/32/64-bit signed and
unsigned integer, and 32/64-bit floating-point dtypes. These will be added to
the namespace as dtype literals with the expected names (e.g., <code class="docutils literal notranslate"><span class="pre">bool</span></code>,
<code class="docutils literal notranslate"><span class="pre">uint16</span></code>, <code class="docutils literal notranslate"><span class="pre">float64</span></code>).</p>
<p>The most obvious omissions are the complex dtypes. The rationale for the lack
of complex support in the first version of the array API standard is that several
libraries (PyTorch, MXNet) are still in the process of adding support for
complex dtypes. The next version of the standard is expected to include <code class="docutils literal notranslate"><span class="pre">complex64</span></code>
and <code class="docutils literal notranslate"><span class="pre">complex128</span></code> (see <a class="reference external" href="https://github.com/data-apis/array-api/issues/102">this issue</a>
for more details).</p>
<p>Specifying dtypes to functions, e.g. via the <code class="docutils literal notranslate"><span class="pre">dtype=</span></code> keyword, is expected
to only use the dtype literals. Format strings, Python builtin dtypes, or
string representations of the dtype literals are not accepted. This will
improve readability and portability of code at little cost. Furthermore, no
behavior is expected of these dtype literals themselves other than basic
equality comparison. In particular, since the array API does not have scalar
objects, syntax like <code class="docutils literal notranslate"><span class="pre">float32(0.0)</span></code> is not allowed (a 0-D array can be
created with <code class="docutils literal notranslate"><span class="pre">asarray(0.0,</span> <span class="pre">dtype=float32)</span></code>).</p>
<p>Casting rules are only defined between different dtypes of the same kind
(i.e., boolean to boolean, integer to integer, or floating-point to
floating-point). This also means omitting integer-uint64 combinations that
would upcast to float64 in NumPy. The rationale for this is that mixed-kind
(e.g., integer to floating-point) casting behaviors differ between libraries.</p>
<img alt="_images/nep-0047-casting-rules-lattice.png" src="_images/nep-0047-casting-rules-lattice.png" />
<p><em>Type promotion diagram. Promotion between any two types is given by their
join on this lattice. Only the types of participating arrays matter, not their
values. Dashed lines indicate that behavior for Python scalars is undefined on
overflow. The Python scalars themselves are only allowed in operators on the
array object, not inside of functions. Boolean, integer and floating-point
dtypes are not connected, indicating mixed-kind promotion is undefined (for
the NumPy implementation, these raise an exception).</em></p>
<p>The most important difference between the casting rules in NumPy and in the
array API standard is how scalars and 0-dimensional arrays are handled. In the
standard, array scalars do not exist and 0-dimensional arrays follow the same
casting rules as higher-dimensional arrays. Furthermore, there is no
value-based casting in the standard. The result type of an operation can be
predicted entirely from its input arrays’ dtypes, regardless of their shapes
or values. Python scalars are only allowed in dunder operations (like
<code class="docutils literal notranslate"><span class="pre">__add__</span></code>), and only if they are of the same kind as the array dtype. They
always cast to the dtype of the array, regardless of value. Overflow behavior
is undefined.</p>
<p>See the <a class="reference external" href="https://data-apis.github.io/array-api/latest/API_specification/type_promotion.html">Type Promotion Rules section of the array API standard</a>
for more details.</p>
<p>In the implementation, this means</p>
<ul class="simple">
<li><p>Ensuring any operation that would produce an scalar object in NumPy is
converted to a 0-D array in the <code class="docutils literal notranslate"><span class="pre">Array</span></code> constructor,</p></li>
<li><p>Checking for combinations that would apply value-based casting and
ensuring they promote to the correct type. This can be achieved, e.g., by
manually broadcasting 0-D inputs (preventing them from participating in
value-based casting), or by explicitly passing the <code class="docutils literal notranslate"><span class="pre">signature</span></code> argument
to the underlying ufunc,</p></li>
<li><p>In dunder operator methods, manually converting Python scalar inputs to 0-D
arrays of the matching dtype if they are the same kind, and raising otherwise. For scalars out of
bounds of the given dtype (for which the behavior is undefined by the spec),
the behavior of <code class="docutils literal notranslate"><span class="pre">np.array(scalar,</span> <span class="pre">dtype=dtype)</span></code> is used (either cast or
raise OverflowError).</p></li>
</ul>
</section>
<section id="indexing">
<span id="id4"></span><h3>Indexing<a class="headerlink" href="#indexing" title="Link to this heading">#</a></h3>
<p>An indexing expression that would return a scalar with <code class="docutils literal notranslate"><span class="pre">ndarray</span></code>, e.g.
<code class="docutils literal notranslate"><span class="pre">arr_2d[0,</span> <span class="pre">0]</span></code>, will return a 0-D array with the new <code class="docutils literal notranslate"><span class="pre">Array</span></code> object. There are
several reasons for this: array scalars are largely considered a design mistake
which no other array library copied; it works better for non-CPU libraries
(typically arrays can live on the device, scalars live on the host); and it’s
simply a more consistent design. To get a Python scalar out of a 0-D array, one can
use the builtin for the type, e.g. <code class="docutils literal notranslate"><span class="pre">float(arr_0d)</span></code>.</p>
<p>The other <a class="reference external" href="https://data-apis.github.io/array-api/latest/API_specification/indexing.html">indexing modes in the standard</a>
do work largely the same as they do for <code class="docutils literal notranslate"><span class="pre">numpy.ndarray</span></code>. One noteworthy
difference is that clipping in slice indexing (e.g., <code class="docutils literal notranslate"><span class="pre">a[:n]</span></code> where <code class="docutils literal notranslate"><span class="pre">n</span></code> is
larger than the size of the first axis) is unspecified behavior, because
that kind of check can be expensive on accelerators.</p>
<p>The standard omits advanced indexing (indexing by an integer array), and boolean indexing is limited to a
single n-D boolean array. This is due to those indexing modes not being
suitable for all types of arrays or JIT compilation. Furthermore, some
advanced NumPy indexing semantics, such as the semantics for mixing advanced
and non-advanced indices in a single index, are considered design mistakes in
NumPy. The absence of these more advanced index types does not seem to be
problematic; if a user or library author wants to use them, they can do so
through zero-copy conversion to <code class="docutils literal notranslate"><span class="pre">numpy.ndarray</span></code>. This will signal correctly
to whomever reads the code that it is then NumPy-specific rather than portable
to all conforming array types.</p>
<p>Being a minimal implementation, <code class="docutils literal notranslate"><span class="pre">numpy.array_api</span></code> will explicitly disallow
slices with clipped bounds, advanced indexing, and boolean indices mixed with
other indices.</p>
</section>
<section id="the-array-object">
<h3>The array object<a class="headerlink" href="#the-array-object" title="Link to this heading">#</a></h3>
<p>The array object in the standard does not have methods other than dunder
methods. It also does not allow direct construction, preferring instead array
construction methods like <code class="docutils literal notranslate"><span class="pre">asarray</span></code>. The rationale for that is that not all
array libraries have methods on their array object (e.g., TensorFlow does
not). It also provides only a single way of doing something, rather than have
functions and methods that are effectively duplicate.</p>
<p>Mixing operations that may produce views (e.g., indexing, <code class="docutils literal notranslate"><span class="pre">nonzero</span></code>)
in combination with mutation (e.g., item or slice assignment) is
<a class="reference external" href="https://data-apis.github.io/array-api/latest/design_topics/copies_views_and_mutation.html">explicitly documented in the standard to not be supported</a>.
This cannot easily be prohibited in the array object itself; instead this will
be guidance to the user via documentation.</p>
<p>The standard current does not prescribe a name for the array object itself. We
propose to name it <code class="docutils literal notranslate"><span class="pre">Array</span></code>. This uses proper PEP 8 capitalization for a
class, and does not conflict with any existing NumPy class names. <a class="footnote-reference brackets" href="#id8" id="id5" role="doc-noteref"><span class="fn-bracket">[</span>3<span class="fn-bracket">]</span></a> Note
that the actual name of the array class does not actually matter that much as
it is not itself included in the top-level namespace, and cannot be directly
constructed.</p>
</section>
</section>
<section id="implementation">
<h2>Implementation<a class="headerlink" href="#implementation" title="Link to this heading">#</a></h2>
<p>A prototype of the <code class="docutils literal notranslate"><span class="pre">array_api</span></code> namespace can be found in
<a class="github reference external" href="https://github.com/numpy/numpy/pull/18585">numpy/numpy#18585</a>. The docstring in its
<code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> has several important notes about implementation details. The
code for the wrapper functions also contains <code class="docutils literal notranslate"><span class="pre">#</span> <span class="pre">Note:</span></code> comments everywhere
there is a difference with the NumPy API. The
implementation is entirely in pure Python, and consists primarily of wrapper
classes/functions that pass through to the corresponding NumPy functions after
applying input validation and any changed behavior. One important part that is not
implemented yet is <a class="reference external" href="https://github.com/dmlc/dlpack">DLPack</a> support, as its implementation in <code class="docutils literal notranslate"><span class="pre">np.ndarray</span></code> is
still in progress (<a class="github reference external" href="https://github.com/numpy/numpy/pull/19083">numpy/numpy#19083</a>).</p>
<p>The <code class="docutils literal notranslate"><span class="pre">numpy.array_api</span></code> module is considered experimental. This means that
importing it will issue a <code class="docutils literal notranslate"><span class="pre">UserWarning</span></code>. The alternative to this was naming
the module <code class="docutils literal notranslate"><span class="pre">numpy._array_api</span></code>, but the warning was chosen instead so that it
does not become necessary to rename the module in the future, potentially
breaking user code. The module also requires Python 3.8 or greater due to
extensive use of the positional-only argument syntax.</p>
<p>The experimental nature of the module also means that it is not yet mentioned
anywhere in the NumPy documentation, outside of its module docstring and this
NEP. Documentation for the implementation is itself a challenging problem.
Presently every docstring in the implementation simply references the
underlying NumPy function it implements. However, this is not ideal, as the
underlying NumPy function may have different behavior from the corresponding
function in the array API, for instance, additional keyword arguments that are
not present in the array API. It has been suggested that documentation may be
pulled directly from the spec itself, but support for this would require
making some technical changes to the way the spec is written, and so the
current implementation does not yet make any attempt to do this.</p>
<p>The array API specification is accompanied by an in-progress <a class="reference external" href="https://github.com/data-apis/array-api-tests">official test
suite</a>, which is designed to
test conformance of any library to the array API specification. The tests
included with the implementation will therefore be minimal, as the majority of
the behavior will be verified by this test suite. The tests in NumPy itself
for the <code class="docutils literal notranslate"><span class="pre">array_api</span></code> submodule will only include testing for behavior not
covered by the array API test suite, for instance, tests that the
implementation is minimal and properly rejects things like disallowed type
combinations. A CI job will be added to the array API test suite repository to
regularly test it against the NumPy implementation. The array API test suite
is designed to be vendored if libraries wish to do that, but this idea was
rejected for NumPy because the time taken by it is significant relative to the
existing NumPy test suite, and because the test suite is itself still
a work in progress.</p>
<section id="the-dtype-objects">
<h3>The dtype objects<a class="headerlink" href="#the-dtype-objects" title="Link to this heading">#</a></h3>
<p>We must be able to compare dtypes for equality, and expressions like these must
be possible:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">np</span><span class="o">.</span><span class="n">array_api</span><span class="o">.</span><span class="n">some_func</span><span class="p">(</span><span class="o">...</span><span class="p">,</span> <span class="n">dtype</span><span class="o">=</span><span class="n">x</span><span class="o">.</span><span class="n">dtype</span><span class="p">)</span>
</pre></div>
</div>
<p>The above implies it would be nice to have <code class="docutils literal notranslate"><span class="pre">np.array_api.float32</span> <span class="pre">==</span>
<span class="pre">np.array_api.ndarray(...).dtype</span></code>.</p>
<p>Dtypes should not be assumed to have a class hierarchy by users, however we are
free to implement it with a class hierarchy if that’s convenient. We considered
the following options to implement dtype objects:</p>