Skip to content

Commit 4e402cc

Browse files
kgrytekgryte
authored
docs: add changelog for v2024.12 specification revision
PR-URL: #903 Reviewed-by: Evgeni Burovski
1 parent c91c82c commit 4e402cc

12 files changed

+358
-2
lines changed

‎CHANGELOG.md

+166
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,172 @@
44
55
This changelog is organized by specification version and notes all changes with respect to the previous version. Within the section for a specific version (e.g., v2022.12), separate sections are used for (a) changes to existing APIs and requirements, (b) new APIs and new requirements, and (c) errata.
66

7+
## v2024.12
8+
9+
### Updates
10+
11+
> Updates to existing APIs and requirements.
12+
13+
#### Normative
14+
15+
- Clarify that conforming implementations may support additional arguments beyond those described in the Array API specification ([gh-870](https://github.com/data-apis/array-api/pull/870))
16+
- Clarify accuracy requirements for operations involving complex numbers ([gh-882](https://github.com/data-apis/array-api/pull/882))
17+
- Clarify expected results for in-place operations in conforming array libraries which do not support array mutation ([gh-895](https://github.com/data-apis/array-api/pull/895))
18+
19+
#### APIs
20+
21+
- `__dlpack__`: clarify the expected behavior of the `copy` keyword argument when `copy=True` ([gh-906](https://github.com/data-apis/array-api/pull/906))
22+
- `__eq__`: clarify that cross-kind comparisons are unspecified ([gh-822](https://github.com/data-apis/array-api/pull/822))
23+
- `__ge__`: clarify that cross-kind comparisons are unspecified ([gh-822](https://github.com/data-apis/array-api/pull/822))
24+
- `__getitem__`: clarify that iteration is defined for one-dimensional arrays ([gh-821](https://github.com/data-apis/array-api/pull/821))
25+
- `__gt__`: clarify that cross-kind comparisons are unspecified ([gh-822](https://github.com/data-apis/array-api/pull/822))
26+
- `__le__`: clarify that cross-kind comparisons are unspecified ([gh-822](https://github.com/data-apis/array-api/pull/822))
27+
- `__lt__`: clarify that cross-kind comparisons are unspecified ([gh-822](https://github.com/data-apis/array-api/pull/822))
28+
- `__ne__`: clarify that cross-kind comparisons are unspecified ([gh-822](https://github.com/data-apis/array-api/pull/822))
29+
- `asarray`: clarify the expected behavior of the `copy` keyword argument when `copy=True` ([gh-906](https://github.com/data-apis/array-api/pull/906))
30+
- `astype`: clarify the expected behavior of the `copy` keyword argument when `copy=True` ([gh-906](https://github.com/data-apis/array-api/pull/906))
31+
- `clip`: specify behavior when one of the operands is `NaN` ([gh-813](https://github.com/data-apis/array-api/pull/813); backported to v2023.12 revision of the Array API specification)
32+
- `clip`: clarify behavior when arguments have different data types ([gh-896](https://github.com/data-apis/array-api/pull/896))
33+
- `conj`: add support for real-valued arrays ([gh-884](https://github.com/data-apis/array-api/pull/884))
34+
- `cumulative_sum`: clarify that behavior when providing a zero-dimensional array is unspecified ([gh-851](https://github.com/data-apis/array-api/pull/851))
35+
- `equal`: clarify that cross-kind comparisons are unspecified ([gh-822](https://github.com/data-apis/array-api/pull/822))
36+
- `greater`: clarify that cross-kind comparisons are unspecified ([gh-822](https://github.com/data-apis/array-api/pull/822))
37+
- `greater_equal`: clarify that cross-kind comparisons are unspecified ([gh-822](https://github.com/data-apis/array-api/pull/822))
38+
- `less`: clarify that cross-kind comparisons are unspecified ([gh-822](https://github.com/data-apis/array-api/pull/822))
39+
- `less_equal`: clarify that cross-kind comparisons are unspecified ([gh-822](https://github.com/data-apis/array-api/pull/822))
40+
- `mean`: add support for complex floating-point data types ([gh-850](https://github.com/data-apis/array-api/pull/850))
41+
- `not_equal`: clarify that cross-kind comparisons are unspecified ([gh-822](https://github.com/data-apis/array-api/pull/822))
42+
- `real`: add support for real-valued arrays ([gh-884](https://github.com/data-apis/array-api/pull/884))
43+
- `reshape`: clarify the expected behavior of the `copy` keyword argument when `copy=True` ([gh-906](https://github.com/data-apis/array-api/pull/906))
44+
- `sqrt`: clarify that results must be correctly rounded according to IEEE 754 ([gh-882](https://github.com/data-apis/array-api/pull/882))
45+
- `take`: clarify that behavior when provided a zero-dimensional input array is unspecified ([gh-876](https://github.com/data-apis/array-api/pull/876))
46+
- `take`: clarify support for negative indices ([gh-894](https://github.com/data-apis/array-api/pull/894))
47+
48+
##### Scalar Argument Support
49+
50+
The following APIs were updated to support both scalar and array arguments for one or more arguments:
51+
52+
- `add` ([gh-862](https://github.com/data-apis/array-api/pull/862))
53+
- `atan2` ([gh-862](https://github.com/data-apis/array-api/pull/862))
54+
- `bitwise_and` ([gh-862](https://github.com/data-apis/array-api/pull/862))
55+
- `bitwise_left_shift` ([gh-862](https://github.com/data-apis/array-api/pull/862))
56+
- `bitwise_or` ([gh-862](https://github.com/data-apis/array-api/pull/862))
57+
- `bitwise_right_shift` ([gh-862](https://github.com/data-apis/array-api/pull/862))
58+
- `bitwise_xor` ([gh-862](https://github.com/data-apis/array-api/pull/862))
59+
- `copysign` ([gh-862](https://github.com/data-apis/array-api/pull/862))
60+
- `divide` ([gh-862](https://github.com/data-apis/array-api/pull/862))
61+
- `equal` ([gh-862](https://github.com/data-apis/array-api/pull/862))
62+
- `floor_divide` ([gh-862](https://github.com/data-apis/array-api/pull/862))
63+
- `greater` ([gh-862](https://github.com/data-apis/array-api/pull/862))
64+
- `greater_equal` ([gh-862](https://github.com/data-apis/array-api/pull/862))
65+
- `hypot` ([gh-862](https://github.com/data-apis/array-api/pull/862))
66+
- `less` ([gh-862](https://github.com/data-apis/array-api/pull/862))
67+
- `less_equal` ([gh-862](https://github.com/data-apis/array-api/pull/862))
68+
- `logaddexp` ([gh-862](https://github.com/data-apis/array-api/pull/862))
69+
- `logical_and` ([gh-862](https://github.com/data-apis/array-api/pull/862))
70+
- `logical_or` ([gh-862](https://github.com/data-apis/array-api/pull/862))
71+
- `logical_xor` ([gh-862](https://github.com/data-apis/array-api/pull/862))
72+
- `maximum` ([gh-862](https://github.com/data-apis/array-api/pull/862))
73+
- `minimum` ([gh-862](https://github.com/data-apis/array-api/pull/862))
74+
- `multiply` ([gh-862](https://github.com/data-apis/array-api/pull/862))
75+
- `nextafter` ([gh-862](https://github.com/data-apis/array-api/pull/862))
76+
- `not_equal` ([gh-862](https://github.com/data-apis/array-api/pull/862))
77+
- `pow` ([gh-862](https://github.com/data-apis/array-api/pull/862))
78+
- `remainder` ([gh-862](https://github.com/data-apis/array-api/pull/862))
79+
- `result_type` ([gh-873](https://github.com/data-apis/array-api/pull/873))
80+
- `subtract` ([gh-862](https://github.com/data-apis/array-api/pull/862))
81+
- `where` ([gh-860](https://github.com/data-apis/array-api/pull/860))
82+
83+
#### Extensions
84+
85+
> Updates to APIs and requirements included as part of specification extensions.
86+
87+
- `fft.fftfreq`: add `dtype` keyword argument ([gh-885](https://github.com/data-apis/array-api/pull/885))
88+
- `fft.rfftfreq`: add `dtype` keyword argument ([gh-885](https://github.com/data-apis/array-api/pull/885))
89+
90+
* * *
91+
92+
### Additions
93+
94+
> New APIs and requirements added to the specification.
95+
96+
#### Normative
97+
98+
- Add support for integer array indexing ([gh-900](https://github.com/data-apis/array-api/pull/900))
99+
100+
#### APIs
101+
102+
The following APIs were added to the specification:
103+
104+
- `count_nonzero`: count the number of array elements which are non-zero ([gh-803](https://github.com/data-apis/array-api/pull/803))
105+
- `cumulative_prod`: calculate the cumulative product ([gh-793](https://github.com/data-apis/array-api/pull/793))
106+
- `diff`: calculate the n-th discrete forward difference along a specified axis ([gh-791](https://github.com/data-apis/array-api/pull/791), [gh-881](https://github.com/data-apis/array-api/pull/881))
107+
- `nextafter`: return the next representable floating-point value for each element in an array ([gh-792](https://github.com/data-apis/array-api/pull/792))
108+
- `reciprocal`: return the reciprocal for each element in an array ([gh-802](https://github.com/data-apis/array-api/pull/802))
109+
- `take_along_axis`: return elements from an array at locations specified by one-dimensional indices along an axis ([gh-816](https://github.com/data-apis/array-api/pull/816))
110+
111+
#### Inspection APIs
112+
113+
The following inspection APIs were added to the specification:
114+
115+
- `max dimensions`: return the maximum number of supported dimensions ([gh-763](https://github.com/data-apis/array-api/pull/763) and [gh-809](https://github.com/data-apis/array-api/pull/809))
116+
117+
* * *
118+
119+
### Breaking Changes
120+
121+
The following is a list of breaking changes relative to the previous version of the specification:
122+
123+
#### Normative
124+
125+
- An operation involving a Python `complex` scalar and a real-valued floating-point arrays must be equivalent to an operation involving a zero-dimensional array having a complex floating-point data type and a real-valued floating-point array ([gh-871](https://github.com/data-apis/array-api/pull/871))
126+
127+
#### APIs
128+
129+
- `can_cast`: application of type promotion rules must account for device context ([gh-889](https://github.com/data-apis/array-api/pull/889))
130+
- `result_type`: application of type promotion rules must account for device context ([gh-889](https://github.com/data-apis/array-api/pull/889))
131+
132+
* * *
133+
134+
### Errata
135+
136+
The following is a list of fixes and points of clarification with regard to the previous version of the specification:
137+
138+
- `__add__`: fix typing for `other` argument ([gh-https://github.com/data-apis/array-api/pull/905](https://github.com/data-apis/array-api/pull/905))
139+
- `__bool__`: fix typo in special case notes ([gh-785](https://github.com/data-apis/array-api/pull/785))
140+
- `__dlpack__`: resolve conflicting exception guidance ([gh-887](https://github.com/data-apis/array-api/pull/887))
141+
- `__eq__`: fix typing for `other` argument ([gh-https://github.com/data-apis/array-api/pull/905](https://github.com/data-apis/array-api/pull/905))
142+
- `__getitem__`: clarify required indexing semantics ([gh-821](https://github.com/data-apis/array-api/pull/821))
143+
- `__mul__`: fix typing for `other` argument ([gh-https://github.com/data-apis/array-api/pull/905](https://github.com/data-apis/array-api/pull/905))
144+
- `__ne__`: fix typing for `other` argument ([gh-https://github.com/data-apis/array-api/pull/905](https://github.com/data-apis/array-api/pull/905))
145+
- `__pow__`: fix typing for `other` argument ([gh-https://github.com/data-apis/array-api/pull/905](https://github.com/data-apis/array-api/pull/905))
146+
- `__setitem__`: clarify required indexing semantics ([gh-821](https://github.com/data-apis/array-api/pull/821))
147+
- `__setitem__`: fix typing for `value` argument ([gh-https://github.com/data-apis/array-api/pull/905](https://github.com/data-apis/array-api/pull/905))
148+
- `__sub__`: fix typing for `other` argument ([gh-https://github.com/data-apis/array-api/pull/905](https://github.com/data-apis/array-api/pull/905))
149+
- `__truediv__`: fix typing for `other` argument ([gh-https://github.com/data-apis/array-api/pull/905](https://github.com/data-apis/array-api/pull/905))
150+
- `broadcast_to`: clarify broadcast behavior ([gh-888](https://github.com/data-apis/array-api/pull/888))
151+
- `broadcast_to`: clarify required exception behavior ([gh-897](https://github.com/data-apis/array-api/pull/897))
152+
- `clip`: clarify that the operation is only defined when elements in `min` and `max` are inside the bounds of the input array data type ([gh-814](https://github.com/data-apis/array-api/pull/814))
153+
- `clip`: fix typo in parameter description ([gh-896](https://github.com/data-apis/array-api/pull/896))
154+
- `copysign`: fix formatting of special cases ([gh-806](https://github.com/data-apis/array-api/pull/806))
155+
- `fft.fft`: fix typo in function description ([gh-806](https://github.com/data-apis/array-api/pull/806))
156+
- `fft.ifft`: fix typo in function description ([gh-806](https://github.com/data-apis/array-api/pull/806))
157+
- `fft.fftn`: fix typo in function description ([gh-806](https://github.com/data-apis/array-api/pull/806))
158+
- `fft.ifftn`: fix typo in function description ([gh-806](https://github.com/data-apis/array-api/pull/806))
159+
- `fft.irfft`: fix typo in function description ([gh-806](https://github.com/data-apis/array-api/pull/806))
160+
- `fft.irfftn`: fix typo in function description ([gh-806](https://github.com/data-apis/array-api/pull/806))
161+
- `fft.hfft`: fix typo in function description ([gh-806](https://github.com/data-apis/array-api/pull/806))
162+
- `linalg.solve`: clarify broadcasting semantics and output shape ([gh-810](https://github.com/data-apis/array-api/pull/810))
163+
- `nonzero`: fix return type ([gh-803](https://github.com/data-apis/array-api/pull/803) and [gh-https://github.com/data-apis/array-api/pull/904](https://github.com/data-apis/array-api/pull/904))
164+
- `searchsorted`: fix incorrect boundary conditions ([gh-898](https://github.com/data-apis/array-api/pull/898))
165+
- `sign`: fix equation in function description ([gh-844](https://github.com/data-apis/array-api/pull/844))
166+
- `tile`: fix missing return type ([gh-798](https://github.com/data-apis/array-api/pull/798))
167+
- `unstack`: fix typo in function description ([gh-810](https://github.com/data-apis/array-api/pull/810))
168+
- `vecdot`: fix regression in default value for `axis` keyword argument ([gh-880](https://github.com/data-apis/array-api/pull/880))
169+
- `where`: clarify that the `condition` argument should have a boolean data type ([gh-868](https://github.com/data-apis/array-api/pull/868))
170+
171+
* * *
172+
7173
## v2023.12
8174

9175
### Updates

‎src/array_api_stubs/_draft/array_object.py

+24-1
Original file line numberDiff line numberDiff line change
@@ -460,10 +460,13 @@ def __dlpack__(
460460
Added BufferError.
461461
462462
.. versionchanged:: 2023.12
463-
Added the ``max_version``, ``dl_device``, and ``copy`` keywords.
463+
Added the ``max_version``, ``dl_device``, and ``copy`` keyword arguments.
464464
465465
.. versionchanged:: 2023.12
466466
Added recommendation for handling read-only arrays.
467+
468+
.. versionchanged:: 2024.12
469+
Resolved conflicting exception guidance.
467470
"""
468471

469472
def __dlpack_device__(self: array, /) -> Tuple[Enum, int]:
@@ -518,6 +521,9 @@ def __eq__(self: array, other: Union[int, float, complex, bool, array], /) -> ar
518521
519522
.. versionchanged:: 2022.12
520523
Added complex data type support.
524+
525+
.. versionchanged:: 2024.12
526+
Cross-kind comparisons are explicitly left unspecified.
521527
"""
522528

523529
def __float__(self: array, /) -> float:
@@ -604,6 +610,9 @@ def __ge__(self: array, other: Union[int, float, array], /) -> array:
604610
- Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.greater_equal`.
605611
- Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
606612
- 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`).
613+
614+
.. versionchanged:: 2024.12
615+
Cross-kind comparisons are explicitly left unspecified.
607616
"""
608617

609618
def __getitem__(
@@ -639,6 +648,8 @@ def __getitem__(
639648
- See :ref:`indexing` for details on supported indexing semantics.
640649
- 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.
641650
651+
.. versionchanged:: 2024.12
652+
Clarified that iteration is defined for one-dimensional arrays.
642653
"""
643654

644655
def __gt__(self: array, other: Union[int, float, array], /) -> array:
@@ -663,6 +674,9 @@ def __gt__(self: array, other: Union[int, float, array], /) -> array:
663674
- Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.greater`.
664675
- Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
665676
- 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`).
677+
678+
.. versionchanged:: 2024.12
679+
Cross-kind comparisons are explicitly left unspecified.
666680
"""
667681

668682
def __index__(self: array, /) -> int:
@@ -784,6 +798,9 @@ def __le__(self: array, other: Union[int, float, array], /) -> array:
784798
- Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.less_equal`.
785799
- Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
786800
- 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`).
801+
802+
.. versionchanged:: 2024.12
803+
Cross-kind comparisons are explicitly left unspecified.
787804
"""
788805

789806
def __lshift__(self: array, other: Union[int, array], /) -> array:
@@ -830,6 +847,9 @@ def __lt__(self: array, other: Union[int, float, array], /) -> array:
830847
- Element-wise results must equal the results returned by the equivalent element-wise function :func:`~array_api.less`.
831848
- Comparison of arrays without a corresponding promotable data type (see :ref:`type-promotion`) is undefined and thus implementation-dependent.
832849
- 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`).
850+
851+
.. versionchanged:: 2024.12
852+
Cross-kind comparisons are explicitly left unspecified.
833853
"""
834854

835855
def __matmul__(self: array, other: array, /) -> array:
@@ -955,6 +975,9 @@ def __ne__(self: array, other: Union[int, float, complex, bool, array], /) -> ar
955975
956976
.. versionchanged:: 2022.12
957977
Added complex data type support.
978+
979+
.. versionchanged:: 2024.12
980+
Cross-kind comparisons are explicitly left unspecified.
958981
"""
959982

960983
def __neg__(self: array, /) -> array:

0 commit comments

Comments
 (0)