Repository navigation
Expand file tree
/
Copy patharray_object.py
More file actions
1281 lines (978 loc) · 56.3 KB
/
Copy patharray_object.py
File metadata and controls
1281 lines (978 loc) · 56.3 KB
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
from __future__ import annotations
__all__ = ["array"]
from ._types import (
array,
dtype as Dtype,
device as Device,
Optional,
Tuple,
Union,
Any,
PyCapsule,
Enum,
ellipsis,
)
class _array:
def __init__(self: array) -> None:
"""Initialize the attributes for the array object class."""
@property
def dtype(self: array) -> Dtype:
"""
Data type of the array elements.
Returns
-------
out: dtype
array data type.
"""
@property
def device(self: array) -> Device:
"""
Hardware device the array data resides on.
Returns
-------
out: device
a ``device`` object (see :ref:`device-support`).
"""
@property
def mT(self: array) -> array:
"""
Transpose of a matrix (or a stack of matrices).
If an array instance has fewer than two dimensions, an error should be raised.
Returns
-------
out: array
array whose last two dimensions (axes) are permuted in reverse order relative to original array (i.e., for an array instance having shape ``(..., M, N)``, the returned array must have shape ``(..., N, M)``). The returned array must have the same data type as the original array.
"""
@property
def ndim(self: array) -> int:
"""
Number of array dimensions (axes).
Returns
-------
out: int
number of array dimensions (axes).
"""
@property
def shape(self: array) -> Tuple[Optional[int], ...]:
"""
Array dimensions.
Returns
-------
out: Tuple[Optional[int], ...]
array dimensions. An array dimension must be ``None`` if and only if a dimension is unknown.
.. note::
For array libraries having graph-based computational models, array dimensions may be unknown due to data-dependent operations (e.g., boolean indexing; ``A[:, B > 0]``) and thus cannot be statically resolved without knowing array contents.
.. note::
The returned value should be a tuple; however, where warranted, an array library may choose to return a custom shape object. If an array library returns a custom shape object, the object must be immutable, must support indexing for dimension retrieval, and must behave similarly to a tuple.
"""
@property
def size(self: array) -> Optional[int]:
"""
Number of elements in an array.
.. note::
This must equal the product of the array's dimensions.
Returns
-------
out: Optional[int]
number of elements in an array. The returned value must be ``None`` if and only if one or more array dimensions are unknown.
.. note::
For array libraries having graph-based computational models, an array may have unknown dimensions due to data-dependent operations.
"""
@property
def T(self: array) -> array:
"""
Transpose of the array.
The array instance must be two-dimensional. If the array instance is not two-dimensional, an error should be raised.
Returns
-------
out: array
two-dimensional array whose first and last dimensions (axes) are permuted in reverse order relative to original array. The returned array must have the same data type as the original array.
.. note::
Limiting the transpose to two-dimensional arrays (matrices) deviates from the NumPy et al practice of reversing all axes for arrays having more than two-dimensions. This is intentional, as reversing all axes was found to be problematic (e.g., conflicting with the mathematical definition of a transpose which is limited to matrices; not operating on batches of matrices; et cetera). In order to reverse all axes, one is recommended to use the functional ``permute_dims`` interface found in this specification.
"""
@property
def __dlpack_c_exchange_api__(self: array) -> PyCapsule:
"""
Object containing the DLPack C-API exchange API struct.
An optional static array type attribute stored in ``type(array_instance).__dlpack_c_exchange_api__``
that can be used to retrieve the DLPack C-API exchange API struct in DLPack 1.3 or later to speed up
exchange of array data at the C extension level without going through Python-level exchange.
See :ref:`data-interchange` section for more details.
Returns
-------
out: PyCapsule
The PyCapsule object containing the DLPack C-API exchange API struct.
.. note::
This is a static global object shared across all the array instances of the same type.
It can be queried through the ``type(array_instance).__dlpack_c_exchange_api__`` attribute.
"""
def __abs__(self: array, /) -> array:
"""
Calculates the absolute value for each element of an array instance.
For real-valued input arrays, the element-wise result has the same magnitude as the respective element in ``x`` but has positive sign.
.. note::
For signed integer data types, the absolute value of the minimum representable integer is implementation-dependent.
Parameters
----------
self: array
array instance. Should have a numeric data type.
Returns
-------
out: array
an array containing the element-wise absolute value. If ``self`` has a real-valued data type, the returned array must have the same data type as ``self``. If ``self`` has a complex floating-point data type, the returned arrayed must have a real-valued floating-point data type whose precision matches the precision of ``self`` (e.g., if ``self`` is ``complex128``, then the returned array must have a ``float64`` data type).
Notes
-----
.. note::
Element-wise results, including special cases, must equal the results returned by the equivalent element-wise function :func:`~array_api.abs`.
.. versionchanged:: 2022.12
Added complex data type support.
"""
def __add__(self: array, other: Union[int, float, complex, array], /) -> array:
"""
Calculates the sum for each element of an array instance with the respective element of the array ``other``.
Parameters
----------
self: array
array instance (augend array). Should have a numeric data type.
other: Union[int, float, array]
addend array. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have a numeric data type.
Returns
-------
out: array
an array containing the element-wise sums. The returned array must have a data type determined by :ref:`type-promotion`.
Notes
-----
- Element-wise results, including special cases, must equal the results returned by the equivalent element-wise function :func:`~array_api.add`.
.. versionchanged:: 2022.12
Added complex data type support.
"""
def __and__(self: array, other: Union[int, bool, array], /) -> array:
"""
Evaluates ``self_i & other_i`` for each element of an array instance with the respective element of the array ``other``.
Parameters
----------
self: array
array instance. Should have an integer or boolean data type.
other: Union[int, bool, array]
other array. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have an integer or boolean data type.
Returns
-------
out: array
an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`.
Notes
-----
- Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.bitwise_and`.
"""
def __array_namespace__(
self: array, /, *, api_version: Optional[str] = None
) -> Any:
"""
Returns an object that has all the array API functions on it.
Parameters
----------
self: array
array instance.
api_version: Optional[str]
string representing the version of the array API specification to be returned, in ``'YYYY.MM'`` form, for example, ``'2020.10'``. If it is ``None``, it should return the namespace corresponding to latest version of the array API specification. If the given version is invalid or not implemented for the given module, an error should be raised. Default: ``None``.
Returns
-------
out: Any
an object representing the array API namespace. It should have every top-level function defined in the specification as an attribute.
"""
def __bool__(self: array, /) -> bool:
"""
Converts a zero-dimensional array to a Python ``bool`` object.
Parameters
----------
self: array
zero-dimensional array instance.
Returns
-------
out: bool
a Python ``bool`` object representing the single element of the array.
Notes
-----
**Special cases**
For real-valued floating-point operands,
- If ``self`` is ``NaN``, the result is ``True``.
- If ``self`` is either ``+infinity`` or ``-infinity``, the result is ``True``.
- If ``self`` is either ``+0`` or ``-0``, the result is ``False``.
For complex floating-point operands, special cases must be handled as if the operation is implemented as the logical OR of ``bool(real(self))`` and ``bool(imag(self))``.
**Lazy implementations**
The Python language requires the return value to be of type ``bool``. Lazy implementations are therefore not able to return any kind of lazy/delayed object here and should raise a ``ValueError`` instead.
.. versionchanged:: 2022.12
Added boolean and complex data type support.
.. versionchanged:: 2023.12
Allowed lazy implementations to error.
"""
def __complex__(self: array, /) -> complex:
"""
Converts a zero-dimensional array to a Python ``complex`` object.
Parameters
----------
self: array
zero-dimensional array instance.
Returns
-------
out: complex
a Python ``complex`` object representing the single element of the array instance.
Notes
-----
**Special cases**
For boolean operands,
- If ``self`` is ``True``, the result is ``1+0j``.
- If ``self`` is ``False``, the result is ``0+0j``.
For real-valued floating-point operands,
- If ``self`` is ``NaN``, the result is ``NaN + NaN j``.
- If ``self`` is ``+infinity``, the result is ``+infinity + 0j``.
- If ``self`` is ``-infinity``, the result is ``-infinity + 0j``.
- If ``self`` is a finite number, the result is ``self + 0j``.
**Lazy implementations**
The Python language requires the return value to be of type ``complex``. Lazy implementations are therefore not able to return any kind of lazy/delayed object here and should raise a ``ValueError`` instead.
.. versionadded:: 2022.12
.. versionchanged:: 2023.12
Allowed lazy implementations to error.
"""
def __dlpack__(
self: array,
/,
*,
stream: Optional[Union[int, Any]] = None,
max_version: Optional[tuple[int, int]] = None,
dl_device: Optional[tuple[Enum, int]] = None,
copy: Optional[bool] = None,
) -> PyCapsule:
"""
Exports the array for consumption by :func:`~array_api.from_dlpack` as a DLPack capsule.
Parameters
----------
self: array
array instance.
stream: Optional[Union[int, Any]]
for CUDA and ROCm, a Python integer representing a pointer to a stream, on devices that support streams. ``stream`` is provided by the consumer to the producer to instruct the producer to ensure that operations can safely be performed on the array (e.g., by inserting a dependency between streams via "wait for event"). The pointer must be an integer larger than or equal to ``-1`` (see below for allowed values on each platform). If ``stream`` is ``-1``, the value may be used by the consumer to signal "producer must not perform any synchronization". The ownership of the stream stays with the consumer. On CPU and other device types without streams, only ``None`` is accepted.
For other device types which do have a stream, queue, or similar synchronization/ordering mechanism, the most appropriate type to use for ``stream`` is not yet determined. E.g., for SYCL one may want to use an object containing an in-order ``cl::sycl::queue``. This is allowed when libraries agree on such a convention, and may be standardized in a future version of this API standard.
.. note::
Support for a ``stream`` value other than ``None`` is optional and implementation-dependent.
Device-specific values of ``stream`` for CUDA:
- ``None``: producer must assume the legacy default stream (default).
- ``1``: the legacy default stream.
- ``2``: the per-thread default stream.
- ``> 2``: stream number represented as a Python integer.
- ``0`` is disallowed due to its ambiguity: ``0`` could mean either ``None``, ``1``, or ``2``.
Device-specific values of ``stream`` for ROCm:
- ``None``: producer must assume the legacy default stream (default).
- ``0``: the default stream.
- ``> 2``: stream number represented as a Python integer.
- Using ``1`` and ``2`` is not supported.
.. note::
When ``dl_device`` is provided explicitly, ``stream`` must be a valid
construct for the specified device type. In particular, when ``kDLCPU``
is in use, ``stream`` must be ``None`` and a synchronization must be
performed to ensure data safety.
.. admonition:: Tip
:class: important
It is recommended that implementers explicitly handle streams. If
they use the legacy default stream, specifying ``1`` (CUDA) or ``0``
(ROCm) is preferred. ``None`` is a safe default for developers who do
not want to think about stream handling at all, potentially at the
cost of more synchronizations than necessary.
max_version: Optional[tuple[int, int]]
the maximum DLPack version that the *consumer* (i.e., the caller of
``__dlpack__``) supports, in the form of a 2-tuple ``(major, minor)``.
This method may return a capsule of version ``max_version`` (recommended
if it does support that), or of a different version.
This means the consumer must verify the version even when
`max_version` is passed.
dl_device: Optional[tuple[enum.Enum, int]]
the DLPack device type. Default is ``None``, meaning the exported capsule
should be on the same device as ``self`` is. When specified, the format
must be a 2-tuple, following that of the return value of :meth:`array.__dlpack_device__`.
If the device type cannot be handled by the producer, this function must
raise ``BufferError``.
The v2023.12 standard only mandates that a compliant library should offer a way for
``__dlpack__`` to return a capsule referencing an array whose underlying memory is
accessible to the Python interpreter (represented by the ``kDLCPU`` enumerator in DLPack).
If a copy must be made to enable this support but ``copy`` is set to ``False``, the
function must raise ``BufferError``.
Other device kinds will be considered for standardization in a future version of this
API standard.
copy: Optional[bool]
boolean indicating whether or not to copy the input. If ``True``, the
function must always copy (performed by the producer; see also :ref:`copy-keyword-argument`). If ``False``, the
function must never copy, and raise a ``BufferError`` in case a copy is
deemed necessary (e.g. if a cross-device data movement is requested, and
it is not possible without a copy). If ``None``, the function must reuse
the existing memory buffer if possible and copy otherwise. Default: ``None``.
When a copy happens, the ``DLPACK_FLAG_BITMASK_IS_COPIED`` flag must be set.
.. note::
If a copy happens, and if the consumer-provided ``stream`` and ``dl_device``
can be understood by the producer, the copy must be performed over ``stream``.
Returns
-------
capsule: PyCapsule
a DLPack capsule for the array. See :ref:`data-interchange` for details.
Raises
------
BufferError
Implementations should raise ``BufferError`` when the data cannot
be exported as DLPack (e.g., incompatible dtype or strides). Other
errors are raised when export fails for other reasons (e.g., incorrect
arguments passed or out of memory).
Notes
-----
The DLPack version scheme is SemVer, where the major DLPack versions
represent ABI breaks, and minor versions represent ABI-compatible additions
(e.g., new enum values for new data types or device types).
The ``max_version`` keyword was introduced in v2023.12, and goes
together with the ``DLManagedTensorVersioned`` struct added in DLPack
1.0. This keyword may not be used by consumers until a later time after
introduction, because producers may implement the support at a different
point in time.
It is recommended for the producer to use this logic in the implementation
of ``__dlpack__``:
.. code:: python
if max_version is None:
# Keep and use the DLPack 0.X implementation
# Note: from March 2025 onwards (but ideally as late as
# possible), it's okay to raise BufferError here
else:
# We get to produce `DLManagedTensorVersioned` now. Note that
# our_own_dlpack_version is the max version that the *producer*
# supports and fills in the `DLManagedTensorVersioned::version`
# field
if max_version >= our_own_dlpack_version:
# Consumer understands us, just return a Capsule with our max version
elif max_version[0] == our_own_dlpack_version[0]:
# major versions match, we should still be fine here -
# return our own max version
else:
# if we're at a higher major version internally, did we
# keep an implementation of the older major version around?
# For example, if the producer is on DLPack 1.x and the consumer
# is 0.y, can the producer still export a capsule containing
# DLManagedTensor and not DLManagedTensorVersioned?
# If so, use that. Else, the producer should raise a BufferError
# here to tell users that the consumer's max_version is too
# old to allow the data exchange to happen.
And this logic for the consumer in :func:`~array_api.from_dlpack`:
.. code:: python
try:
x.__dlpack__(max_version=(1, 0), ...)
# if it succeeds, store info from the capsule named "dltensor_versioned",
# and need to set the name to "used_dltensor_versioned" when we're done
except TypeError:
x.__dlpack__(...)
This logic is also applicable to handling of the new ``dl_device`` and ``copy``
keywords.
DLPack 1.0 added a flag to indicate that the array is read-only
(``DLPACK_FLAG_BITMASK_READ_ONLY``). A consumer that does not support
read-only arrays should ignore this flag (this is preferred over
raising an exception; the user is then responsible for ensuring the
memory isn't modified).
.. versionchanged:: 2022.12
Added BufferError.
.. versionchanged:: 2023.12
Added the ``max_version``, ``dl_device``, and ``copy`` keyword arguments.
.. versionchanged:: 2023.12
Added recommendation for handling read-only arrays.
.. versionchanged:: 2024.12
Resolved conflicting exception guidance.
"""
def __dlpack_device__(self: array, /) -> Tuple[Enum, int]:
"""
Returns device type and device ID in DLPack format. Meant for use within :func:`~array_api.from_dlpack`.
Parameters
----------
self: array
array instance.
Returns
-------
device: Tuple[Enum, int]
a tuple ``(device_type, device_id)`` in DLPack format. Valid device type enum members are:
::
CPU = 1
CUDA = 2
CPU_PINNED = 3
OPENCL = 4
VULKAN = 7
METAL = 8
VPI = 9
ROCM = 10
CUDA_MANAGED = 13
ONE_API = 14
"""
def __eq__(self: array, other: Union[int, float, complex, bool, array], /) -> array:
r"""
Computes the truth value of ``self_i == other_i`` for each element of an array instance with the respective element of the array ``other``.
Parameters
----------
self: array
array instance. May have any data type.
other: Union[int, float, complex, bool, array]
other array. Must be compatible with ``self`` (see :ref:`broadcasting`). May have any data type.
Returns
-------
out: array
an array containing the element-wise results. The returned array must have a data type of ``bool``.
Notes
-----
- Element-wise results, including special cases, must equal the results returned by the equivalent element-wise function :func:`~array_api.equal`.
- Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
.. versionchanged:: 2022.12
Added complex data type support.
.. versionchanged:: 2024.12
Cross-kind comparisons are explicitly left unspecified.
"""
def __float__(self: array, /) -> float:
"""
Converts a zero-dimensional array to a Python ``float`` object.
.. note::
Casting integer values outside the representable bounds of Python's float type is not specified and is implementation-dependent.
Parameters
----------
self: array
zero-dimensional array instance. Should have a real-valued or boolean data type. If ``self`` has a complex floating-point data type, the function must raise a ``TypeError``.
Returns
-------
out: float
a Python ``float`` object representing the single element of the array instance.
Notes
-----
**Special cases**
For boolean operands,
- If ``self`` is ``True``, the result is ``1``.
- If ``self`` is ``False``, the result is ``0``.
**Lazy implementations**
The Python language requires the return value to be of type ``float``. Lazy implementations are therefore not able to return any kind of lazy/delayed object here and should raise a ``ValueError`` instead.
.. versionchanged:: 2022.12
Added boolean and complex data type support.
.. versionchanged:: 2023.12
Allowed lazy implementations to error.
"""
def __floordiv__(self: array, other: Union[int, float, array], /) -> array:
"""
Evaluates ``self_i // other_i`` for each element of an array instance with the respective element of the array ``other``.
.. note::
For input arrays which promote to an integer data type, the result of division by zero is unspecified and thus implementation-defined.
Parameters
----------
self: array
array instance. Should have a real-valued data type.
other: Union[int, float, array]
other array. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have a real-valued data type.
Returns
-------
out: array
an array containing the element-wise results. The returned array must have a data type determined by :ref:`type-promotion`.
.. note::
Element-wise results, including special cases, must equal the results returned by the equivalent element-wise function :func:`~array_api.floor_divide`.
"""
def __ge__(self: array, other: Union[int, float, array], /) -> array:
"""
Computes the truth value of ``self_i >= other_i`` for each element of an array instance with the respective element of the array ``other``.
Parameters
----------
self: array
array instance. Should have a real-valued data type.
other: Union[int, float, array]
other array. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have a real-valued data type.
Returns
-------
out: array
an array containing the element-wise results. The returned array must have a data type of ``bool``.
Notes
-----
- Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.greater_equal`.
- Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
- For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
.. versionchanged:: 2024.12
Cross-kind comparisons are explicitly left unspecified.
"""
def __getitem__(
self: array,
key: Union[
int,
slice,
ellipsis,
None,
Tuple[Union[int, slice, ellipsis, array, None], ...],
array,
],
/,
) -> array:
"""
Returns ``self[key]``.
Parameters
----------
self: array
array instance.
key: Union[int, slice, ellipsis, None, Tuple[Union[int, slice, ellipsis, array, None], ...], array]
index key.
Returns
-------
out: array
an array containing the accessed value(s). The returned array must have the same data type as ``self``.
Notes
-----
- See :ref:`indexing` for details on supported indexing semantics.
- When ``__getitem__`` is defined on an object, Python will automatically define iteration (i.e., the behavior from ``iter(x)``) as ``x[0]``, ``x[1]``, ..., ``x[N-1]``. This can also be implemented directly by defining ``__iter__``. Therefore, for a one-dimensional array ``x``, iteration should produce a sequence of zero-dimensional arrays ``x[0]``, ``x[1]``, ..., ``x[N-1]``, where ``N`` is the number of elements in the array. Iteration behavior for arrays having zero dimensions or more than one dimension is unspecified and thus implementation-defined.
.. note::
When ``key`` contains integer arrays on a device different from the device of ``self``, the
behavior is unspecified and thus implementation-defined.
.. versionchanged:: 2024.12
Clarified that iteration is defined for one-dimensional arrays.
"""
def __gt__(self: array, other: Union[int, float, array], /) -> array:
"""
Computes the truth value of ``self_i > other_i`` for each element of an array instance with the respective element of the array ``other``.
Parameters
----------
self: array
array instance. Should have a real-valued data type.
other: Union[int, float, array]
other array. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have a real-valued data type.
Returns
-------
out: array
an array containing the element-wise results. The returned array must have a data type of ``bool``.
Notes
-----
- Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.greater`.
- Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
- For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
.. versionchanged:: 2024.12
Cross-kind comparisons are explicitly left unspecified.
"""
def __index__(self: array, /) -> int:
"""
Converts a zero-dimensional integer array to a Python ``int`` object.
.. note::
This method is called to implement `operator.index() <https://docs.python.org/3/reference/datamodel.html#object.__index__>`_. See also `PEP 357 <https://www.python.org/dev/peps/pep-0357/>`_.
Parameters
----------
self: array
zero-dimensional array instance. Should have an integer data type. If ``self`` has a floating-point data type, the function must raise a ``TypeError``.
Returns
-------
out: int
a Python ``int`` object representing the single element of the array instance.
Notes
-----
**Lazy implementations**
The Python language requires the return value to be of type ``int``. Lazy implementations are therefore not able to return any kind of lazy/delayed object here and should raise a ``ValueError`` instead.
.. versionchanged:: 2023.12
Allowed lazy implementations to error.
"""
def __int__(self: array, /) -> int:
"""
Converts a zero-dimensional array to a Python ``int`` object.
Parameters
----------
self: array
zero-dimensional array instance. Should have a real-valued or boolean data type. If ``self`` has a complex floating-point data type, the function must raise a ``TypeError``.
Returns
-------
out: int
a Python ``int`` object representing the single element of the array instance.
Notes
-----
**Special cases**
For boolean operands,
- If ``self`` is ``True``, the result is ``1``.
- If ``self`` is ``False``, the result is ``0``.
For floating-point operands,
- If ``self`` is a finite number, the result is the integer part of ``self``.
- If ``self`` is ``-0``, the result is ``0``.
**Raises**
For floating-point operands,
- If ``self`` is either ``+infinity`` or ``-infinity``, raise ``OverflowError``.
- If ``self`` is ``NaN``, raise ``ValueError``.
Notes
-----
**Lazy implementations**
The Python language requires the return value to be of type ``int``. Lazy implementations are therefore not able to return any kind of lazy/delayed object here and should raise a ``ValueError`` instead.
.. versionchanged:: 2022.12
Added boolean and complex data type support.
.. versionchanged:: 2023.12
Allowed lazy implementations to error.
"""
def __invert__(self: array, /) -> array:
"""
Evaluates ``~self_i`` for each element of an array instance.
Parameters
----------
self: array
array instance. Should have an integer or boolean data type.
Returns
-------
out: array
an array containing the element-wise results. The returned array must have the same data type as `self`.
.. note::
Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.bitwise_invert`.
"""
def __le__(self: array, other: Union[int, float, array], /) -> array:
"""
Computes the truth value of ``self_i <= other_i`` for each element of an array instance with the respective element of the array ``other``.
Parameters
----------
self: array
array instance. Should have a real-valued data type.
other: Union[int, float, array]
other array. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have a real-valued data type.
Returns
-------
out: array
an array containing the element-wise results. The returned array must have a data type of ``bool``.
Notes
-----
- Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.less_equal`.
- Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
- For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
.. versionchanged:: 2024.12
Cross-kind comparisons are explicitly left unspecified.
"""
def __lshift__(self: array, other: Union[int, array], /) -> array:
"""
Evaluates ``self_i << other_i`` for each element of an array instance with the respective element of the array ``other``.
Parameters
----------
self: array
array instance. Should have an integer data type.
other: Union[int, array]
other array. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have an integer data type. Each element must be greater than or equal to ``0``.
Returns
-------
out: array
an array containing the element-wise results. The returned array must have the same data type as ``self``.
Notes
-----
- Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.bitwise_left_shift`.
"""
def __lt__(self: array, other: Union[int, float, array], /) -> array:
"""
Computes the truth value of ``self_i < other_i`` for each element of an array instance with the respective element of the array ``other``.
Parameters
----------
self: array
array instance. Should have a real-valued data type.
other: Union[int, float, array]
other array. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have a real-valued data type.
Returns
-------
out: array
an array containing the element-wise results. The returned array must have a data type of ``bool``.
Notes
-----
- Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.less`.
- Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
- For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
.. versionchanged:: 2024.12
Cross-kind comparisons are explicitly left unspecified.
"""
def __matmul__(self: array, other: array, /) -> array:
"""
Computes the matrix product.
.. note::
The ``matmul`` function must implement the same semantics as the built-in ``@`` operator (see `PEP 465 <https://www.python.org/dev/peps/pep-0465>`_).
Parameters
----------
self: array
array instance. Should have a numeric data type. Must have at least one dimension. If ``self`` is one-dimensional having shape ``(M,)`` and ``other`` has more than one dimension, ``self`` must be promoted to a two-dimensional array by prepending ``1`` to its dimensions (i.e., must have shape ``(1, M)``). After matrix multiplication, the prepended dimensions in the returned array must be removed. If ``self`` has more than one dimension (including after vector-to-matrix promotion), ``shape(self)[:-2]`` must be compatible with ``shape(other)[:-2]`` (after vector-to-matrix promotion) (see :ref:`broadcasting`). If ``self`` has shape ``(..., M, K)``, the innermost two dimensions form matrices on which to perform matrix multiplication.
other: array
other array. Should have a numeric data type. Must have at least one dimension. If ``other`` is one-dimensional having shape ``(N,)`` and ``self`` has more than one dimension, ``other`` must be promoted to a two-dimensional array by appending ``1`` to its dimensions (i.e., must have shape ``(N, 1)``). After matrix multiplication, the appended dimensions in the returned array must be removed. If ``other`` has more than one dimension (including after vector-to-matrix promotion), ``shape(other)[:-2]`` must be compatible with ``shape(self)[:-2]`` (after vector-to-matrix promotion) (see :ref:`broadcasting`). If ``other`` has shape ``(..., K, N)``, the innermost two dimensions form matrices on which to perform matrix multiplication.
.. note::
If either ``x1`` or ``x2`` has a complex floating-point data type, neither argument must be complex-conjugated or transposed. If conjugation and/or transposition is desired, these operations should be explicitly performed prior to computing the matrix product.
Returns
-------
out: array
- if both ``self`` and ``other`` are one-dimensional arrays having shape ``(N,)``, a zero-dimensional array containing the inner product as its only element.
- if ``self`` is a two-dimensional array having shape ``(M, K)`` and ``other`` is a two-dimensional array having shape ``(K, N)``, a two-dimensional array containing the `conventional matrix product <https://en.wikipedia.org/wiki/Matrix_multiplication>`_ and having shape ``(M, N)``.
- if ``self`` is a one-dimensional array having shape ``(K,)`` and ``other`` is an array having shape ``(..., K, N)``, an array having shape ``(..., N)`` (i.e., prepended dimensions during vector-to-matrix promotion must be removed) and containing the `conventional matrix product <https://en.wikipedia.org/wiki/Matrix_multiplication>`_.
- if ``self`` is an array having shape ``(..., M, K)`` and ``other`` is a one-dimensional array having shape ``(K,)``, an array having shape ``(..., M)`` (i.e., appended dimensions during vector-to-matrix promotion must be removed) and containing the `conventional matrix product <https://en.wikipedia.org/wiki/Matrix_multiplication>`_.
- if ``self`` is a two-dimensional array having shape ``(M, K)`` and ``other`` is an array having shape ``(..., K, N)``, an array having shape ``(..., M, N)`` and containing the `conventional matrix product <https://en.wikipedia.org/wiki/Matrix_multiplication>`_ for each stacked matrix.
- if ``self`` is an array having shape ``(..., M, K)`` and ``other`` is a two-dimensional array having shape ``(K, N)``, an array having shape ``(..., M, N)`` and containing the `conventional matrix product <https://en.wikipedia.org/wiki/Matrix_multiplication>`_ for each stacked matrix.
- if either ``self`` or ``other`` has more than two dimensions, an array having a shape determined by :ref:`broadcasting` ``shape(self)[:-2]`` against ``shape(other)[:-2]`` and containing the `conventional matrix product <https://en.wikipedia.org/wiki/Matrix_multiplication>`_ for each stacked matrix.
- The returned array must have a data type determined by :ref:`type-promotion`.
Notes
-----
.. note::
Results must equal the results returned by the equivalent function :func:`~array_api.matmul`.
**Raises**
- if either ``self`` or ``other`` is a zero-dimensional array.
- if ``self`` is a one-dimensional array having shape ``(K,)``, ``other`` is a one-dimensional array having shape ``(L,)``, and ``K != L``.
- if ``self`` is a one-dimensional array having shape ``(K,)``, ``other`` is an array having shape ``(..., L, N)``, and ``K != L``.
- if ``self`` is an array having shape ``(..., M, K)``, ``other`` is a one-dimensional array having shape ``(L,)``, and ``K != L``.
- if ``self`` is an array having shape ``(..., M, K)``, ``other`` is an array having shape ``(..., L, N)``, and ``K != L``.
.. versionchanged:: 2022.12
Added complex data type support.
"""
def __mod__(self: array, other: Union[int, float, array], /) -> array:
"""
Evaluates ``self_i % other_i`` for each element of an array instance with the respective element of the array ``other``.
Parameters
----------
self: array
array instance. Should have a real-valued data type.
other: Union[int, float, array]
other array. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have a real-valued data type.
Returns
-------
out: array
an array containing the element-wise results. Each element-wise result must have the same sign as the respective element ``other_i``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`.
Notes
-----
- Element-wise results, including special cases, must equal the results returned by the equivalent element-wise function :func:`~array_api.remainder`.
- For input arrays which promote to an integer data type, the result of division by zero is unspecified and thus implementation-defined.
"""
def __mul__(self: array, other: Union[int, float, complex, array], /) -> array:
r"""
Calculates the product for each element of an array instance with the respective element of the array ``other``.
.. note::
Floating-point multiplication is not always associative due to finite precision.
Parameters
----------
self: array
array instance. Should have a numeric data type.
other: Union[int, float, complex, array]
other array. Must be compatible with ``self`` (see :ref:`broadcasting`). Should have a numeric data type.
Returns
-------
out: array
an array containing the element-wise products. The returned array must have a data type determined by :ref:`type-promotion`.
Notes
-----
- Element-wise results, including special cases, must equal the results returned by the equivalent element-wise function :func:`~array_api.multiply`.
.. versionchanged:: 2022.12
Added complex data type support.
"""
def __ne__(self: array, other: Union[int, float, complex, bool, array], /) -> array:
"""
Computes the truth value of ``self_i != other_i`` for each element of an array instance with the respective element of the array ``other``.
Parameters
----------
self: array
array instance. May have any data type.
other: Union[int, float, complex, bool, array]
other array. Must be compatible with ``self`` (see :ref:`broadcasting`). May have any data type.
Returns
-------
out: array
an array containing the element-wise results. The returned array must have a data type of ``bool`` (i.e., must be a boolean array).
Notes
-----
- Element-wise results, including special cases, must equal the results returned by the equivalent element-wise function :func:`~array_api.not_equal`.
- Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.