8000 Merge branch 'main' into 217 · lezcano/array-api@093b226 · GitHub
[go: up one dir, main page]
Skip to content

Commit 093b226

Browse files
kgrytekgryte
authored
Merge branch 'main' into 217
2 parents 9fcf96e + 5593253 commit 093b226

File tree

11 files changed

+427
-244
lines changed

11 files changed

+427
-244
lines changed

‎.github/workflows/preview.yml

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
on: [status]
22
jobs:
33
circleci_artifacts_redirector_job:
4+
# Don't run Action on forks, and allow skipping CI
5+
if: "github.repository == 'data-apis/array-api'"
46
runs-on: ubuntu-latest
57
name: Run CircleCI artifacts redirector
68
steps:
@@ -14,4 +16,4 @@ jobs:
1416
job-title: Check the rendered docs here!
1517
- name: Array API preview
1618
run: |
17-
curl --fail ${{ steps.step1.outputs.url }} | grep $GITHUB_SHA
19+
curl --fail ${{ steps.step1.outputs.url }} | grep $GITHUB_SHA

‎spec/API_specification/array_object.md

Lines changed: 66 additions & 33 deletions
Large diffs are not rendered by default.

‎spec/API_specification/creation_functions.md

Lines changed: 80 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ This function cannot guarantee that the interval does not include the `stop` val
4141

4242
- **device**: _Optional\[ <device> ]_
4343

44-
- device to place the created array on, if given. Default: `None`.
44+
- device on which to place the created array. Default: `None`.
4545

4646
#### Returns
4747

@@ -57,7 +57,7 @@ Convert the input to an array.
5757

5858
#### Parameters
5959

60-
- **obj**: _Union\[ float, NestedSequence\[ bool | int | float ], SupportsDLPack, SupportsBufferProtocol ]_
60+
- **obj**: _Union\[ <array>, bool, int, float, NestedSequence\[ bool | int | float ], SupportsDLPack, SupportsBufferProtocol ]_
6161

6262
- Object to be converted to an array. Can be a Python scalar, a (possibly nested) sequence of Python scalars, or an object supporting DLPack or the Python buffer protocol.
6363

@@ -72,7 +72,7 @@ Convert the input to an array.
7272

7373
- **device**: _Optional\[ <devi A93C ce> ]_
7474

75-
- device to place the created array on, if given. Default: `None`.
75+
- device on which to place the created array. Default: `None`.
7676

7777
- **copy**: _Optional\[ bool ]_
7878

@@ -102,7 +102,7 @@ Returns an uninitialized array having a specified `shape`.
102102

103103
- **device**: _Optional\[ <device> ]_
104104

105-
- device to place the created array on, if given. Default: `None`.
105+
- device on which to place the created array. Default: `None`.
106106

107107
#### Returns
108108

@@ -127,7 +127,7 @@ Returns an uninitialized array with the same `shape` as an input array `x`.
127127

128128
- **device**: _Optional\[ <device> ]_
129129

130-
- device to place the created array on, if given. If `device` is `None`, the default device must be used, not `x.device`. Default: `None`.
130+
- device on which to place the created array. If `device` is `None`, the default device must be used, not `x.device`. Default: `None`.
131131

132132
#### Returns
133133

@@ -160,7 +160,7 @@ Returns a two-dimensional array with ones on the `k`th diagonal and zeros elsewh
160160

161161
- **device**: _Optional\[ <device> ]_
162162

163-
- device to place the created array on, if given. Default: `None`.
163+
- device on which to place the created array. Default: `None`.
164164

165165
#### Returns
166166

@@ -206,11 +206,15 @@ Returns a new array having a specified `shape` and filled with `fill_value`.
206206
207207
- **dtype**: _Optional\[ <dtype> ]_
208208
209-
- output array data type. If `dtype` is `None`, the output array data type must be inferred from `fill_value`. If it's an `int`, the output array dtype must be the default integer dtype; if it's a `float`, then the output array dtype must be the default floating-point data type; if it's a `bool` then the output array must have boolean dtype. Default: `None`.
209+
- output array data type. If `dtype` is `None`, the output array data type must be inferred from `fill_value`. If the fill value is an `int`, the output array data type must be the default integer data type. If the fill value is a `float`, the output array data type must be the default floating-point data type. If the fill value is a `bool`, the output array must have boolean data type. Default: `None`.
210+
211+
```{note}
212+
If `dtype` is `None` and the `fill_value` exceeds the precision of the resolved default output array data type, behavior is left unspecified and, thus, implementation-defined.
213+
```
210214
211215
- **device**: _Optional\[ <device> ]_
212216
213-
- device to place the created array on, if given. Default: `None`.
217+
- device on which to place the created array. Default: `None`.
214218
215219
#### Returns
216220
@@ -237,9 +241,13 @@ Returns a new array filled with `fill_value` and having the same `shape` as an i
237241
238242
- output array data type. If `dtype` is `None`, the output array data type must be inferred from `fill_value` (see {ref}`function-full`). Default: `None`.
239243
244+
```{note}
245+
If `dtype` is `None` and the `fill_value` exceeds the precision of the resolved default output array data type, behavior is left unspecified and, thus, implementation-defined.
246+
```
247+
240248
- **device**: _Optional\[ <device> ]_
241249
242-
- device to place the created array on, if given. If `device` is `None`, the default device must be used, not `x.device`. Default: `None`.
250+
- device on which to place the created array. If `device` is `None`, the default device must be used, not `x.device`. Default: `None`.
243251
244252
#### Returns
245253
@@ -277,7 +285,7 @@ Returns evenly spaced numbers over a specified interval.
277285
278286
- **device**: _Optional\[ <device> ]_
279287
280-
- device to place the created array on, if given. Default: `None`.
288+
- device on which to place the created array. Default: `None`.
281289
282290
- **endpoint**: _bool_
283291
@@ -337,7 +345,7 @@ Returns a new array having a specified `shape` and filled with ones.
337345
338346
- **device**: _Optional\[ <device> ]_
339347
340-
- device to place the created array on, if given. Default: `None`.
348+
- device on which to place the created array. Default: `None`.
341349
342350
#### Returns
343351
@@ -362,14 +370,72 @@ Returns a new array filled with ones and having the same `shape` as an input arr
362370
363371
- **device**: _Optional\[ <device> ]_
364372
365-
- device to place the created array on, if given. If `device` is `None`, the default device must be used, not `x.device`. Default: `None`.
373+
- device on which to place the created array. If `device` is `None`, the default device must be used, not `x.device`. Default: `None`.
366374
367375
#### Returns
368376
369377
- **out**: _<array>_
370378
371379
- an array having the same shape as `x` and filled with ones.
372380
381+
(function-tril)=
382+
### tril(x, /, *, k=0)
383+
384+
Returns the lower triangular part of a matrix (or a stack of matrices) `x`.
385+
386+
```{note}
387+
The lower triangular part of the matrix is defined as the elements on and below the specified diagonal `k`.
388+
```
389+
390+
#### Parameters
391+
392+
- **x**: _<array>_
393+
394+
- input array having shape `(..., M, N)` and whose innermost two dimensions form `MxN` matrices.
395+
396+
- **k**: _int_
397+
398+
- diagonal above which to zero elements. If `k = 0`, the diagonal is the main diagonal. If `k < 0`, the diagonal is below the main diagonal. If `k > 0`, the diagonal is above the main diagonal. Default: `0`.
399+
400+
```{note}
401+
The main diagonal is defined as the set of indices `{(i, i)}` for `i` on the interval `[0, min(M, N) - 1]`.
402+
```
403+
404+
#### Returns
405+
406+
- **out**: _&lt;array&gt;_
407+
408+
- an array containing the lower triangular part(s). The returned array must have the same shape and data type as `x`. All elements above the specified diagonal `k` must be zeroed. The returned array should be allocated on the same device as `x`.
409+
410+
(function-triu)=
411+
### triu(x, /, *, k=0)
412+
413+
Returns the upper triangular part of a matrix (or a stack of matrices) `x`.
414+
415+
```{note}
416+
The upper triangular part of the matrix is defined as the elements on and above the specified diagonal `k`.
417+
```
418+
419+
#### Parameters
420+
421+
- **x**: _&lt;array&gt;_
422+
423+
- input array having shape `(..., M, N)` and whose innermost two dimensions form `MxN` matrices.
424+
425+
- **k**: _int_
426+
427+
- diagonal below which to zero elements. If `k = 0`, the diagonal is the main diagonal. If `k < 0`, the diagonal is below the main diagonal. If `k > 0`, the diagonal is above the main diagonal. Default: `0`.
428+
429+
```{note}
430+
The main diagonal is defined as the set of indices `{(i, i)}` for `i` on the interval `[0, min(M, N) - 1]`.
431+
```
432+
433+
#### Returns
434+
435+
- **out**: _&lt;array&gt;_
436+
437+
- an array containing the upper triangular part(s). The returned array must have the same shape and data type as `x`. All elements below the specified diagonal `k` must be zeroed. The returned array should be allocated on the same device as `x`.
438+
373439
(function-zeros)=
374440
### zeros(shape, *, dtype=None, device=None)
375441
@@ -387,7 +453,7 @@ Returns a new array having a specified `shape` and filled with zeros.
387453
388454
- **device**: _Optional\[ &lt;device&gt; ]_
389455
390-
- device to place the created array on, if given. Default: `None`.
456+
- device on which to place the created array. Default: `None`.
391457
392458
#### Returns
393459
@@ -412,7 +478,7 @@ Returns a new array filled with zeros and having the same `shape` as an input ar
412478
413479
- **device**: _Optional\[ &lt;device&gt; ]_
414480
415-
- device to place the created array on, if given. If `device` is `None`, the default device must be used, not `x.device`. Default: `None`.
481+
- device on which to place the created array. If `device` is `None`, the default device must be used, not `x.device`. Default: `None`.
416482
417483
#### Returns
418484

‎spec/API_specification/elementwise_functions.md

Lines changed: 24 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -944,8 +944,9 @@ each element `x1_i` of the input array `x1` with the respective element `x2_i` o
944944

945945
For floating-point operands,
946946

947-
- If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`.
948-
- If either `x1_i` or `x2_i` is `+infinity`, the result is `+infinity`.
947+
- If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`.
948+
- If `x1_i` is `+infinity` and `x2_i` is not `NaN`, the result is `+infinity`.
949+
- If `x1_i` is not `NaN` and `x2_i` is `+infinity`, the result is `+infinity`.
949950

950951
#### Parameters
951952

@@ -967,7 +968,11 @@ For floating-point operands,
967968
(function-logical_and)=
968969
### logical_and(x1, x2, /)
969970

970-
Computes the logical AND for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. Zeros are considered the equivalent of `False`, while non-zeros are considered the equivalent of `True`.
971+
Computes the logical AND for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`.
972+
973+
```{note}
974+
While this specification recommends that this function only accept input arrays having a boolean data type, specification-compliant array libraries may choose to accept input arrays having numeric data types. If non-boolean data types are supported, zeros must be considered the equivalent of `False`, while non-zeros must be considered the equivalent of `True`.
975+
```
971976

972977
#### Parameters
973978

@@ -988,7 +993,11 @@ Computes the logical AND for each element `x1_i` of the input array `x1` with th
988993
(function-logical_not)=
989994
### logical_not(x, /)
990995

991-
Computes the logical NOT for each element `x_i` of the input array `x`. Zeros are considered the equivalent of `False`, while non-zeros are considered the equivalent of `True`.
996+
Computes the logical NOT for each element `x_i` of the input array `x`.
997+
998+
```{note}
999+
While this specification recommends that this function only accept input arrays having a boolean data type, specification-compliant array libraries may choose to accept input arrays having numeric data types. If non-boolean data types are supported, zeros must be considered the equivalent of `False`, while non-zeros must be considered the equivalent of `True`.
1000+
```
9921001

9931002
#### Parameters
9941003

@@ -1005,7 +1014,11 @@ Computes the logical NOT for each element `x_i` of the input array `x`. Zeros ar
10051014
(function-logical_or)=
10061015
### logical_or(x1, x2, /)
10071016

1008-
Computes the logical OR for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. Zeros are considered the equivalent of `False`, while non-zeros are considered the equivalent of `True`.
1017+
Computes the logical OR for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`.
1018+
1019+
```{note}
1020+
While this specification recommends that this function only accept input arrays having a boolean data type, specification-compliant array libraries may choose to accept input arrays having numeric data types. If non-boolean data types are supported, zeros must be considered the equivalent of `False`, while non-zeros must be considered the equivalent of `True`.
1021+
```
10091022

10101023
#### Parameters
10111024

@@ -1026,7 +1039,11 @@ Computes the logical OR for each element `x1_i` of the input array `x1` with the
10261039
(function-logical_xor)=
10271040
### logical_xor(x1, x2, /)
10281041

1029-
Computes the logical XOR for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`. Zeros are considered the equivalent of `False`, while non-zeros are considered the equivalent of `True`.
1042+
Computes the logical XOR for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`.
1043+
1044+
```{note}
1045+
While this specification recommends that this function only accept input arrays having a boolean data type, specification-compliant array libraries may choose to accept input arrays having numeric data types. If non-boolean data types are supported, zeros must be considered the equivalent of `False`, while non-zeros must be considered the equivalent of `True`.
1046+
```
10301047

10311048
#### Parameters
10321049

@@ -1208,7 +1225,7 @@ Returns the remainder of division for each element `x1_i` of the input array `x1
12081225

12091226
- **out**: _&lt;array&gt;_
12101227

1211-
- an array containing the element-wise results. Each element-wise result must have the same sign as the respective element `x2_i`. The returned array must have a floating-point data type determined by {ref}`type-promotion`.
1228+
- an array containing the element-wise results. Each element-wise result must have the same sign as the respective element `x2_i`. The returned array must have a data type determined by {ref}`type-promotion`.
12121229

12131230
(function-round)=
12141231
### round(x, /)

‎spec/API_specification/linear_algebra_functions.md

Lines changed: 17 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,23 @@ The `matmul` function must implement the same semantics as the built-in `@` oper
6060
- if `x1` is a one-dimensional array having shape `(N)`, `x2` is a one-dimensional array having shape `(M)`, and `N != M`.
6161
- if `x1` is an array having shape `(..., M, K)`, `x2` is an array having shape `(..., L, N)`, and `K != L`.
6262

63+
(function-matrix-transpose)=
64+
### matrix_transpose(x, /)
65+
66+
Transposes a matrix (or a stack of matrices) `x`.
67+
68+
#### Parameters
69+
70+
- **x**: _&lt;array&gt;_
71+
72+
- input array having shape `(..., M, N)` and whose innermost two dimensions form `MxN` matrices.
73+
74+
#### Returns
75+
76+
- **out**: _&lt;array&gt;_
77+
78+
- an array containing the transpose for each matrix and having shape `(..., N, M)`. The returned array must have the same data type as `x`.
79+
6380
(function-tensordot)=
6481
### tensordot(x1, x2, /, *, axes=2)
6582

@@ -93,27 +110,6 @@ Returns a tensor contraction of `x1` and `x2` over specific axes.
93110

94111
- an array containing the tensor contraction whose shape consists of the non-contracted axes (dimensions) of the first array `x1`, followed by the non-contracted axes (dimensions) of the second array `x2`. The returned array must have a data type determined by {ref}`type-promotion`.
95112

96-
(function-transpose)=
97-
### transpose(x, /, *, axes=None)
98-
99-
Transposes (or permutes the axes (dimensions)) of an array `x`.
100-
101-
#### Parameters
102-
103-
- **x**: _&lt;array&gt;_
104-
105-
- input array.
106-
107-
- **axes**: _Optional\[ Tuple\[ int, ... ] ]_
108-
109-
- tuple containing a permutation of `(0, 1, ..., N-1)` where `N` is the number of axes (dimensions) of `x`. If `None`, the axes (dimensions) must be permuted in reverse order (i.e., equivalent to setting `axes=(N-1, ..., 1, 0)`). Default: `None`.
110-
111-
#### Returns
112-
113-
- **out**: _&lt;array&gt;_
114-
115-
- an array containing the transpose. The returned array must have the same data type as `x`.
116-
117113
(function-vecdot)=
118114
### vecdot(x1, x2, /, *, axis=None)
119115

‎spec/API_specification/manipulation_functions.md

Lines changed: 23 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ Joins a sequence of arrays along an existing axis.
1919

2020
#### Parameters
2121

22-
- **arrays**: _Tuple\[ &lt;array&gt;, ... ]_
22+
- **arrays**: _Union\[Tuple\[ &lt;array&gt;, ... ], List\[ &lt;array&gt; ] ]_
2323

2424
- input arrays to join. The arrays must have the same shape, except in the dimension specified by `axis`.
2525

@@ -80,6 +80,27 @@ Reverses the order of elements in an array along the given axis. The shape of th
8080
8181
- an output array having the same data type and shape as `x` and whose elements, relative to `x`, are reordered.
8282
83+
(function-permute-dims)=
84+
### permute_dims(x, /, axes)
85+
86+
Permutes the axes (dimensions) of an array `x`.
87+
88+
#### Parameters
89+
90+
- **x**: _&lt;array&gt;_
91+
92+
- input array.
93+
94+
- **axes**: _Tuple\[ int, ... ]_
95+
96+
- tuple containing a permutation of `(0, 1, ..., N-1)` where `N` is the number of axes (dimensions) of `x`.
97+
98+
#### Returns
99+
100+
- **out**: _&lt;array&gt;_
101+
102+
- an array containing the axes permutation. The returned array must have the same data type as `x`.
103+
83104
(function-reshape)=
84105
### reshape(x, /, shape)
85106
@@ -154,7 +175,7 @@ Joins a sequence of arrays along a new axis.
154175
155176
#### Parameters
156177
157-
- **arrays**: _Tuple\[ &lt;array&gt;, ... ]_
178+
- **arrays**: _Union\[Tuple\[ &lt;array&gt;, ... ], List\[ &lt;array&gt; ] ]_
158179
159180
- input arrays to join. Each array must have the same shape.
160181

0 commit comments

Comments
 (0)
0