diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index da7b250b4..0c632a63c 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -41,7 +41,7 @@ This function cannot guarantee that the interval does not include the `stop` val - **device**: _Optional\[ <device> ]_ - - device to place the created array on, if given. Default: `None`. + - device on which to place the created array. Default: `None`. #### Returns @@ -72,7 +72,7 @@ Convert the input to an array. - **device**: _Optional\[ <device> ]_ - - device to place the created array on, if given. Default: `None`. + - device on which to place the created array. Default: `None`. - **copy**: _Optional\[ bool ]_ @@ -102,7 +102,7 @@ Returns an uninitialized array having a specified `shape`. - **device**: _Optional\[ <device> ]_ - - device to place the created array on, if given. Default: `None`. + - device on which to place the created array. Default: `None`. #### Returns @@ -127,7 +127,7 @@ Returns an uninitialized array with the same `shape` as an input array `x`. - **device**: _Optional\[ <device> ]_ - - device to place the created array on, if given. If `device` is `None`, the default device must be used, not `x.device`. Default: `None`. + - device on which to place the created array. If `device` is `None`, the default device must be used, not `x.device`. Default: `None`. #### Returns @@ -160,7 +160,7 @@ Returns a two-dimensional array with ones on the `k`th diagonal and zeros elsewh - **device**: _Optional\[ <device> ]_ - - device to place the created array on, if given. Default: `None`. + - device on which to place the created array. Default: `None`. #### Returns @@ -210,7 +210,7 @@ Returns a new array having a specified `shape` and filled with `fill_value`. - **device**: _Optional\[ <device> ]_ - - device to place the created array on, if given. Default: `None`. + - device on which to place the created array. Default: `None`. #### Returns @@ -239,7 +239,7 @@ Returns a new array filled with `fill_value` and having the same `shape` as an i - **device**: _Optional\[ <device> ]_ - - device to place the created array on, if given. If `device` is `None`, the default device must be used, not `x.device`. Default: `None`. + - device on which to place the created array. If `device` is `None`, the default device must be used, not `x.device`. Default: `None`. #### Returns @@ -277,7 +277,7 @@ Returns evenly spaced numbers over a specified interval. - **device**: _Optional\[ <device> ]_ - - device to place the created array on, if given. Default: `None`. + - device on which to place the created array. Default: `None`. - **endpoint**: _bool_ @@ -337,7 +337,7 @@ Returns a new array having a specified `shape` and filled with ones. - **device**: _Optional\[ <device> ]_ - - device to place the created array on, if given. Default: `None`. + - device on which to place the created array. Default: `None`. #### Returns @@ -362,7 +362,7 @@ Returns a new array filled with ones and having the same `shape` as an input arr - **device**: _Optional\[ <device> ]_ - - device to place the created array on, if given. If `device` is `None`, the default device must be used, not `x.device`. Default: `None`. + - device on which to place the created array. If `device` is `None`, the default device must be used, not `x.device`. Default: `None`. #### Returns @@ -370,6 +370,64 @@ Returns a new array filled with ones and having the same `shape` as an input arr - an array having the same shape as `x` and filled with ones. +(function-tril)= +### tril(x, /, *, k=0) + +Returns the lower triangular part of a matrix (or a stack of matrices) `x`. + +```{note} +The lower triangular part of the matrix is defined as the elements on and below the specified diagonal `k`. +``` + +#### Parameters + +- **x**: _<array>_ + + - input array having shape `(..., M, N)` and whose innermost two dimensions form `MxN` matrices. + +- **k**: _int_ + + - 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`. + + ```{note} + The main diagonal is defined as the set of indices `{(i, i)}` for `i` on the interval `[0, min(M, N) - 1]`. + ``` + +#### Returns + +- **out**: _<array>_ + + - 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`. + +(function-triu)= +### triu(x, /, *, k=0) + +Returns the upper triangular part of a matrix (or a stack of matrices) `x`. + +```{note} +The upper triangular part of the matrix is defined as the elements on and above the specified diagonal `k`. +``` + +#### Parameters + +- **x**: _<array>_ + + - input array having shape `(..., M, N)` and whose innermost two dimensions form `MxN` matrices. + +- **k**: _int_ + + - 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`. + + ```{note} + The main diagonal is defined as the set of indices `{(i, i)}` for `i` on the interval `[0, min(M, N) - 1]`. + ``` + +#### Returns + +- **out**: _<array>_ + + - 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`. + (function-zeros)= ### zeros(shape, *, dtype=None, device=None) @@ -387,7 +445,7 @@ Returns a new array having a specified `shape` and filled with zeros. - **device**: _Optional\[ <device> ]_ - - device to place the created array on, if given. Default: `None`. + - device on which to place the created array. Default: `None`. #### Returns @@ -412,7 +470,7 @@ Returns a new array filled with zeros and having the same `shape` as an input ar - **device**: _Optional\[ <device> ]_ - - device to place the created array on, if given. If `device` is `None`, the default device must be used, not `x.device`. Default: `None`. + - device on which to place the created array. If `device` is `None`, the default device must be used, not `x.device`. Default: `None`. #### Returns