diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md new file mode 100644 index 000000000..a1af2d353 --- /dev/null +++ b/spec/API_specification/creation_functions.md @@ -0,0 +1,270 @@ +# Creation Functions + +> Array API specification for creating arrays. + +A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions. + +- Positional parameters must be [positional-only](https://www.python.org/dev/peps/pep-0570/) parameters. Positional-only parameters have no externally-usable name. When a function accepting positional-only parameters is called, positional arguments are mapped to these parameters based solely on their order. +- Optional parameters must be [keyword-only](https://www.python.org/dev/peps/pep-3102/) arguments. + + + +### # arange(start, /, *, stop=None, step=1, dtype=None) + +Returns evenly spaced values within the half-open interval `[start, stop)` as a one-dimensional array. + +#### Parameters + +- **start**: _Union\[ int, float ]_ + + - if `stop` is specified, the start of interval (inclusive); otherwise, the end of the interval (exclusive). If `stop` is not specified, the default starting value is `0`. + +- **stop**: _Optional\[ Union\[ int, float ] ]_ + + - the end of the interval. Default: `None`. + + _Note: this function cannot guarantee that the interval does not include the `stop` value in those cases where `step` is not an integer and floating-point rounding errors affect the length of the output array._ + +- **step**: _Union\[ int, float ]_ + + - the distance between two adjacent elements (`out[i+1] - out[i]`). Default: `1`. + +- **dtype**: _Optional\[ _<dtype>_ ]_ + + - output array data type. Default: `None`. + +#### Returns + +- **out**: _<array>_ + + - a one-dimensional array containing evenly spaced values. The length of the output array must be `ceil((stop-start)/step)`. + +### # empty(shape, /, *, dtype=None) + +Returns an uninitialized array having a specified `shape`. + +#### Parameters + +- **shape**: _Union\[ int, Tuple\[ int, ... ] ]_ + + - output array shape. + +- **dtype**: _Optional\[ _<dtype>_ ]_ + + - output array data type. Default: `None`. + +#### Returns + +- **out**: _<array>_ + + - an array containing uninitialized data. + +### # empty_like(x, /, *, dtype=None) + +Returns an uninitialized array with the same `shape` as an input array `x`. + +#### Parameters + +- **x**: _<array>_ + + - input array from which to derive the output array shape. + +- **dtype**: _Optional\[ _<dtype>_ ]_ + + - output array data type. If `dtype` is `None`, the output array data type must be inferred from `x`. Default: `None`. + +#### Returns + +- **out**: _<array>_ + + - an array having the same shape as `x` and containing uninitialized data. + +### # eye(N, /, *, M=None, k=0, dtype=None) + +Returns a two-dimensional array with ones on the `k`th diagonal and zeros elsewhere. + +#### Parameters + +- **N**: _int_ + + - number of rows in the output array. + +- **M**: _Optional\[ int ]_ + + - number of columns in the output array. If `None`, the default number of columns in the output array is `N`. Default: `None`. + +- **k**: _Optional\[ int ]_ + + - index of the diagonal. A positive value refers to an upper diagonal, a negative value to a lower diagonal, and `0` to the main diagonal. Default: `0`. + +- **dtype**: _Optional\[ _<dtype>_ ]_ + + - output array data type. Default: `None`. + +#### Returns + +- **out**: _<array>_ + + - an array where all elements are equal to zero, except for the `k`th diagonal, whose values are equal to one. + +### # full(shape, fill_value, /, *, dtype=None) + +Returns a new array having a specified `shape` and filled with `fill_value`. + +#### Parameters + +- **shape**: _Union\[ int, Tuple\[ int, ... ] ]_ + + - output array shape. + +- **fill_value**: _Union\[ int, float ] ]_ + + - fill value. + +- **dtype**: _Optional\[ _<dtype>_ ]_ + + - output array data type. Default: `None`. + +#### Returns + +- **out**: _<array>_ + + - an array where every element is equal to `fill_value`. + +### # full_like(x, fill_value, /, *, dtype=None) + +Returns a new array filled with `fill_value` and having the same `shape` as an input array `x`. + +#### Parameters + +- **x**: _<array>_ + + - input array from which to derive the output array shape. + +- **fill_value**: _Union\[ int, float ] ]_ + + - fill value. + +- **dtype**: _Optional\[ _<dtype>_ ]_ + + - output array data type. If `dtype` is `None`, the output array data type must be inferred from `x`. Default: `None`. + +#### Returns + +- **out**: _<array>_ + + - an array having the same shape as `x` and where every element is equal to `fill_value`. + +### # linspace(start, stop, num, /, *, dtype=None, endpoint=True) + +Returns evenly spaced numbers over a specified interval. + +#### Parameters + +- **start**: _Union\[ int, float ]_ + + - the start of the interval. + +- **stop**: _Union\[ int, float ]_ + + - the end of the interval. If `endpoint` is `False`, the function must generate a sequence of `num+1` evenly spaced numbers starting with `start` and ending with `stop` and exclude the `stop` from the returned array such that the returned array consists of evenly spaced numbers over the half-open interval `[start, stop)`. If `endpoint` is `True`, the output array must consist of evenly spaced numbers over the closed interval `[start, stop]`. Default: `True`. + + _Note: that the step size changes when `endpoint` is `False`._ + +- **num**: _int_ + + - number of samples. Must be a non-negative integer value; otherwise, the function must raise an exception. + +- **dtype**: _Optional\[ _<dtype>_ ]_ + + - output array data type. Default: `None`. + +- **endpoint**: _Optional\[ bool ]_ + + - boolean indicating whether to include `stop` in the interval. Default: `True`. + +#### Returns + +- **out**: _<array>_ + + - a one-dimensional array containing evenly spaced values. + +### # ones(shape, /, *, dtype=None) + +Returns a new array having a specified `shape` and filled with ones. + +#### Parameters + +- **shape**: _Union\[ int, Tuple\[ int, ... ] ]_ + + - output array shape. + +- **dtype**: _Optional\[ _<dtype>_ ]_ + + - output array data type. Default: `None`. + +#### Returns + +- **out**: _<array>_ + + - an array containing ones. + +### # ones_like(x, /, *, dtype=None) + +Returns a new array filled with ones and having the same `shape` as an input array `x`. + +#### Parameters + +- **x**: _<array>_ + + - input array from which to derive the output array shape. + +- **dtype**: _Optional\[ _<dtype>_ ]_ + + - output array data type. If `dtype` is `None`, the output array data type must be inferred from `x`. Default: `None`. + +#### Returns + +- **out**: _<array>_ + + - an array having the same shape as `x` and filled with ones. + +### # zeros(shape, /, *, dtype=None) + +Returns a new array having a specified `shape` and filled with zeros. + +#### Parameters + +- **shape**: _Union\[ int, Tuple\[ int, ... ] ]_ + + - output array shape. + +- **dtype**: _Optional\[ _<dtype>_ ]_ + + - output array data type. Default: `None`. + +#### Returns + +- **out**: _<array>_ + + - an array containing zeros. + +### # zeros_like(x, /, *, dtype=None) + +Returns a new array filled with zeros and having the same `shape` as an input array `x`. + +#### Parameters + +- **x**: _<array>_ + + - input array from which to derive the output array shape. + +- **dtype**: _Optional\[ _<dtype>_ ]_ + + - output array data type. If `dtype` is `None`, the output array data type must be inferred from `x`. Default: `None`. + +#### Returns + +- **out**: _<array>_ + + - an array having the same shape as `x` and filled with zeros. diff --git a/spec/API_specification/index.rst b/spec/API_specification/index.rst index 86873453d..3c6e337d4 100644 --- a/spec/API_specification/index.rst +++ b/spec/API_specification/index.rst @@ -13,6 +13,7 @@ API specification casting broadcasting out_keyword + creation_functions elementwise_functions statistical_functions searching_functions