Skip to content

Commit 5593253

Browse files
kgrytekgryte
authored
Add specifications for returning upper (triu) and lower (tril) triangular matrices (#243)
* Add `triu` and `tril` specifications * Fix typo and remove `device` keyword * Add note about allocation * Fix missing backticks
1 parent d57a1f8 commit 5593253

File tree

1 file changed

+70
-12
lines changed

1 file changed

+70
-12
lines changed

‎spec/API_specification/creation_functions.md

+70-12
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

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

7373
- **device**: _Optional\[ <device> ]_
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

@@ -214,7 +214,7 @@ Returns a new array having a specified `shape` and filled with `fill_value`.
214214
215215
- **device**: _Optional\[ <device> ]_
216216
217-
- device to place the created array on, if given. Default: `None`.
217+
- device on which to place the created array. Default: `None`.
218218
219219
#### Returns
220220
@@ -247,7 +247,7 @@ Returns a new array filled with `fill_value` and having the same `shape` as an i
247247
248248
- **device**: _Optional\[ <device> ]_
249249
250-
- 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`.
251251
252252
#### Returns
253253
@@ -285,7 +285,7 @@ Returns evenly spaced numbers over a specified interval.
285285
286286
- **device**: _Optional\[ <device> ]_
287287
288-
- device to place the created array on, if given. Default: `None`.
288+
- device on which to place the created array. Default: `None`.
289289
290290
- **endpoint**: _bool_
291291
@@ -345,7 +345,7 @@ Returns a new array having a specified `shape` and filled with ones.
345345
346346
- **device**: _Optional\[ <device> ]_
347347
348-
- device to place the created array on, if given. Default: `None`.
348+
- device on which to place the created array. Default: `None`.
349349
350350
#### Returns
351351
@@ -370,14 +370,72 @@ Returns a new array filled with ones and having the same `shape` as an input arr
370370
371371
- **device**: _Optional\[ <device> ]_
372372
373-
- 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`.
374374
375375
#### Returns
376376
377377
- **out**: _<array>_
378378
379379
- an array having the same shape as `x` and filled with ones.
380380
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+
381439
(function-zeros)=
382440
### zeros(shape, *, dtype=None, device=None)
383441
@@ -395,7 +453,7 @@ Returns a new array having a specified `shape` and filled with zeros.
395453
396454
- **device**: _Optional\[ &lt;device&gt; ]_
397455
398-
- device to place the created array on, if given. Default: `None`.
456+
- device on which to place the created array. Default: `None`.
399457
400458
#### Returns
401459
@@ -420,7 +478,7 @@ Returns a new array filled with zeros and having the same `shape` as an input ar
420478
421479
- **device**: _Optional\[ &lt;device&gt; ]_
422480
423-
- 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`.
424482
425483
#### Returns
426484

0 commit comments

Comments
 (0)