creation_functions.md

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 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 arguments.

Objects in API

(function-arange)=

arange(start, /, stop=None, step=1, *, dtype=None, device=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.

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]). Must not be 0; may be negative, this results in an empty array if stop >= start. Default: 1.

• dtype: Optional[ <dtype> ]

  • output array data type. If dtype is None, the output array data type must be inferred from start, stop and step. If those are all integers, the output array dtype must be the default integer dtype; if one or more have type float, then the output array dtype must be the default floating-point data type. Default: None.

• device: Optional[ <device> ]

  • device to place the created array on, if given. 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) if stop - start and step have the same sign, and length 0 otherwise.

(function-asarray)=

asarray(obj, /, *, dtype=None, device=None, copy=None)

Convert the input to an array.

Parameters

• obj: Union[ <array>, bool, int, float, NestedSequence[ bool | int | float ], SupportsDLPack, SupportsBufferProtocol ]

  • 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.

  :::{tip} An object supporting DLPack has __dlpack__ and __dlpack_device__ methods. An object supporting the buffer protocol can be turned into a memoryview through memoryview(obj). :::

• dtype: Optional[ <dtype> ]

  • output array data type. If dtype is None, the output array data type must be inferred from the data type(s) in obj. If all input values are Python scalars, then if they're all bool the output dtype will be bool; if they're a mix of bools and int the output dtype will be the default integer data type; if they contain floats the output dtype will be the default floating-point data type. Default: None.

• device: Optional[ <device> ]

  • device to place the created array on, if given. Default: None.

• copy: Optional[ bool ]

  • Whether or not to make a copy of the input. If True, always copies. If False, never copies for input which supports DLPack or the buffer protocol, and raises ValueError in case that would be necessary. If None, reuses existing memory buffer if possible, copies otherwise. Default: None.

Returns

• out: <array>

  • An array containing the data from obj.

(function-empty)=

empty(shape, *, dtype=None, device=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. If dtype is None, the output array data type must be the default floating-point data type. Default: None.

• device: Optional[ <device> ]

  • device to place the created array on, if given. Default: None.

Returns

• out: <array>

  • an array containing uninitialized data.

(function-empty_like)=

empty_like(x, /, *, dtype=None, device=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.

• 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.

Returns

• out: <array>

  • an array having the same shape as x and containing uninitialized data.

(function-eye)=

eye(n_rows, n_cols=None, /, *, k=0, dtype=None, device=None)

Returns a two-dimensional array with ones on the kth diagonal and zeros elsewhere.

Parameters

• n_rows: int

  • number of rows in the output array.

• n_cols: Optional[ int ]

  • number of columns in the output array. If None, the default number of columns in the output array is equal to n_rows. 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. If dtype is None, the output array data type must be the default floating-point data type. Default: None.

• device: Optional[ <device> ]

  • device to place the created array on, if given. Default: None.

Returns

• out: <array>

  • an array where all elements are equal to zero, except for the kth diagonal, whose values are equal to one.

(function-from_dlpack)=

from_dlpack(x, /)

Returns a new array containing the data from another (array) object with a __dlpack__ method.

Parameters

• x: object

  • input (array) object.

Returns

• out: <array>

  • an array containing the data in x.

    The returned array may be either a copy or a view. See {ref}`data-interchange` for details.
    

(function-full)=

full(shape, fill_value, *, dtype=None, device=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. 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.

• device: Optional[ <device> ]

  • device to place the created array on, if given. Default: None.

Returns

• out: <array>

  • an array where every element is equal to fill_value.

(function-full_like)=

full_like(x, /, fill_value, *, dtype=None, device=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 fill_value (see {ref}function-full). Default: None.

• 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.

Returns

• out: <array>

  • an array having the same shape as x and where every element is equal to fill_value.

(function-linspace)=

linspace(start, stop, /, num, *, dtype=None, device=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.

    
    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. If dtype is None, the output array data type must be the default floating-point data type. Default: None.

• device: Optional[ <device> ]

  • device to place the created array on, if given. Default: None.

• endpoint: bool

  • boolean indicating whether to include stop in the interval. Default: True.

Returns

• out: <array>

  • a one-dimensional array containing evenly spaced values.

(function-meshgrid)=

meshgrid(*arrays, indexing='xy')

Returns coordinate matrices from coordinate vectors.

Parameters

• arrays: Sequence[ <array> ]

  • one-dimensional arrays representing grid coordinates. Must have a numeric data type.

• indexing: str

  • Cartesian 'xy' or matrix 'ij' indexing of output. If provided zero or one one-dimensional vector(s) (i.e., the zero- and one-dimensional cases, respectively), the indexing keyword has no effect and should be ignored. Default: 'xy'.

Returns

• out: List[ <array>, ... ]

  • list of N arrays, where N is the number of provided one-dimensional input arrays. Each returned array must have rank N. For N one-dimensional arrays having lengths Ni = len(xi),

    • if matrix indexing ij, then each returned array must have the shape (N1, N2, N3, ..., Nn).

    • if Cartesian indexing xy, then each returned array must have shape (N2, N1, N3, ..., Nn).

    Accordingly, for the two-dimensional case with input one-dimensional arrays of length M and N, if matrix indexing ij, then each returned array must have shape (M, N), and, if Cartesian indexing xy, then each returned array must have shape (N, M).

    Similarly, for the three-dimensional case with input one-dimensional arrays of length M, N, and P, if matrix indexing ij, then each returned array must have shape (M, N, P), and, if Cartesian indexing xy, then each returned array must have shape (N, M, P).

    The returned arrays must have a numeric data type determined by {ref}type-promotion.

(function-ones)=

ones(shape, *, dtype=None, device=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. If dtype is None, the output array data type must be the default floating-point data type. Default: None.

• device: Optional[ <device> ]

  • device to place the created array on, if given. Default: None.

Returns

• out: <array>

  • an array containing ones.

(function-ones_like)=

ones_like(x, /, *, dtype=None, device=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.

• 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.

Returns

• out: <array>

  • an array having the same shape as x and filled with ones.

(function-zeros)=

zeros(shape, *, dtype=None, device=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. If dtype is None, the output array data type must be the default floating-point data type. Default: None.

• device: Optional[ <device> ]

  • device to place the created array on, if given. Default: None.

Returns

• out: <array>

  • an array containing zeros.

(function-zeros_like)=

zeros_like(x, /, *, dtype=None, device=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.

• 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.

Returns

• out: <array>

  • an array having the same shape as x and filled with zeros.