:mod:`heat.array_api._creation_functions`
=========================================
.. py:module:: heat.array_api._creation_functions


Module Contents
---------------


.. function:: arange(start: Union[int, float], /, stop: Optional[Union[int, float]] = None, step: Union[int, float] = 1, *, dtype: Optional[heat.array_api._typing.Dtype] = None, device: Optional[heat.array_api._typing.Device] = None) -> heat.array_api._array_object.Array

   Returns evenly spaced values within the half-open interval ``[start, stop)``
   as a one-dimensional array.

   :param start: 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``.
   :type start: Union[int, float]
   :param stop: The end of the interval. Default: ``None``.
   :type stop: Optional[Union[int, float]]
   :param step: 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``.
   :type step: Union[int, float]
   :param dtype: Output array data type. If ``dtype`` is ``None``, the output array data
                 type is inferred from ``start``, ``stop`` and ``step``.
   :type dtype: Optional[Dtype]
   :param device: Device on which to place the created array. Default: ``None``.
   :type device: Optional[Device]


.. function:: asarray(obj: Union[heat.array_api._array_object.Array, bool, int, float, heat.array_api._typing.NestedSequence[bool | int | float], heat.array_api._typing.SupportsBufferProtocol], /, *, dtype: Optional[heat.array_api._typing.Dtype] = None, device: Optional[heat.array_api._typing.Device] = None, copy: Optional[bool] = None) -> heat.array_api._array_object.Array

   Convert the input to an array.

   :param obj: Object to be converted to an array. May be a Python scalar,
               a (possibly nested) sequence of Python scalars, or an object
               supporting the Python buffer protocol. Default: ``None``.
   :type obj: Union[Array, bool, int, float, NestedSequence[bool | int | float], SupportsBufferProtocol]
   :param dtype: Output array data type. If ``dtype`` is ``None``, the output array data
                 type is inferred from the data type(s) in ``obj``.
   :type dtype: Optional[Dtype]
   :param device: Device on which to place the created array. If ``device`` is ``None`` and
                  ``x`` is an array, the output array device is inferred from ``x``.
                  Default: ``None``.
   :type device: Optional[Device]
   :param copy: Boolean indicating whether or not to copy the input.
   :type copy: Optional[bool]


.. function:: empty(shape: Union[int, Tuple[int, Ellipsis]], *, dtype: Optional[heat.array_api._typing.Dtype] = None, device: Optional[heat.array_api._typing.Device] = None) -> heat.array_api._array_object.Array

   Returns an uninitialized array having a specified shape.

   :param shape: Output array shape.
   :type shape: Union[int, Tuple[int, ...]]
   :param dtype: Output array data type. Default: ``None``.
   :type dtype: Optional[Dtype]
   :param device: Device on which to place the created array. Default: ``None``.
   :type device: Optional[Device]


.. function:: empty_like(x: heat.array_api._array_object.Array, /, *, dtype: Optional[heat.array_api._typing.Dtype] = None, device: Optional[heat.array_api._typing.Device] = None) -> heat.array_api._array_object.Array

   Returns an uninitialized array with the same ``shape`` as an input array ``x``.

   :param x: Input array from which to derive the output array shape.
   :type x: Array
   :param dtype: Output array data type. If ``dtype`` is ``None``, the output array data
                 type is inferred from x. Default: ``None``.
   :type dtype: Optional[Dtype]
   :param device: Device on which to place the created array. Default: ``None``.
   :type device: Optional[Device]


.. function:: eye(n_rows: int, n_cols: Optional[int] = None, /, *, k: int = 0, dtype: Optional[heat.array_api._typing.Dtype] = None, device: Optional[heat.array_api._typing.Device] = None) -> heat.array_api._array_object.Array

   Returns a two-dimensional array with ones on the ``k`` h diagonal and zeros elsewhere.

   :param n_rows: Number of rows in the output array.
   :type n_rows: int
   :param n_cols: 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``.
   :type n_cols: Optional[int]
   :param k: 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``.
   :type k: int
   :param dtype: Output array data type. Default: ``None``.
   :type dtype: Optional[Dtype]
   :param device: Device on which to place the created array. Default: ``None``.
   :type device: Optional[Device]


.. function:: from_dlpack(x: object, /) -> heat.array_api._array_object.Array

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

   :param x: Input (array) object.
   :type x: object


.. function:: full(shape: Union[int, Tuple[int, Ellipsis]], fill_value: Union[int, float], *, dtype: Optional[heat.array_api._typing.Dtype] = None, device: Optional[heat.array_api._typing.Device] = None) -> heat.array_api._array_object.Array

   Returns a new array having a specified ``shape`` and filled with ``fill_value``.

   :param shape: Output array shape.
   :type shape: Union[int, Tuple[int, ...]]
   :param fill_value: Fill value.
   :type fill_value: Union[int, float]
   :param dtype: Output array data type. If ``dtype`` is ``None``, the output array data
                 type is inferred from ``fill_value``. Default: ``None``.
   :type dtype: Optional[Dtype]
   :param device: Device on which to place the created array.
   :type device: Optional[Device]


.. function:: full_like(x: heat.array_api._array_object.Array, /, fill_value: Union[int, float], *, dtype: Optional[heat.array_api._typing.Dtype] = None, device: Optional[heat.array_api._typing.Device] = None) -> heat.array_api._array_object.Array

   Returns a new array filled with ``fill_value`` and having the same ``shape``
   as an input array ``x``.

   :param x: Input array from which to derive the output array shape.
   :type x: Array
   :param fill_value: Fill value.
   :type fill_value: Union[int, float]
   :param dtype: Output array data type. If ``dtype`` is ``None``, the output array data
                 type is inferred from x. Default: ``None``.
   :type dtype: Optional[Dtype]
   :param device: Device on which to place the created array. Default: ``None``.
   :type device: Optional[Device]


.. function:: linspace(start: Union[int, float], stop: Union[int, float], /, num: int, *, dtype: Optional[heat.array_api._typing.Dtype] = None, device: Optional[heat.array_api._typing.Device] = None, endpoint: bool = True) -> heat.array_api._array_object.Array

   Returns evenly spaced numbers over a specified interval.

   :param start: The start of the interval.
   :type start: Union[int, float]
   :param stop: The end of the interval.
   :type stop: Union[int, float]
   :param num: Number of samples.
   :type num: int
   :param dtype: Output array data type. Must be a floating-point data type. Default: ``None``.
   :type dtype: Optional[Dtype]
   :param device: Device on which to place the created array. Default: ``None``.
   :type device: Optional[Device]
   :param endpoint: Boolean indicating whether to include ``stop`` in the interval. Default: ``True``.
   :type endpoint: bool


.. function:: meshgrid(*arrays: heat.array_api._array_object.Array, indexing: str = 'xy') -> List[heat.array_api._array_object.Array]

   Returns coordinate matrices from coordinate vectors.

   :param arrays: An arbitrary number of one-dimensional arrays representing grid coordinates.
                  Each array must have the same numeric data type.
   :type arrays: Array
   :param indexing: 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 is ignored.
                    Default: ``'xy'``.
   :type indexing: str


.. function:: ones(shape: Union[int, Tuple[int, Ellipsis]], *, dtype: Optional[heat.array_api._typing.Dtype] = None, device: Optional[heat.array_api._typing.Device] = None) -> heat.array_api._array_object.Array

   Returns a new array having a specified ``shape`` and filled with ones.

   :param shape: Output array shape.
   :type shape: Union[int, Tuple[int, ...]]
   :param dtype: Output array data type. Default: ``None``.
   :type dtype: Optional[Dtype]
   :param device: Device on which to place the created array.
   :type device: Optional[Device]


.. function:: ones_like(x: heat.array_api._array_object.Array, /, *, dtype: Optional[heat.array_api._typing.Dtype] = None, device: Optional[heat.array_api._typing.Device] = None) -> heat.array_api._array_object.Array

   Returns a new array filled with ones and having the same shape as an input array ``x``.

   :param x: Input array from which to derive the output array shape.
   :type x: Array
   :param dtype: Output array data type. If ``dtype`` is ``None``, the output array data
                 type is inferred from x. Default: ``None``.
   :type dtype: Optional[Dtype]
   :param device: Device on which to place the created array. Default: ``None``.
   :type device: Optional[Device]


.. function:: tril(x: heat.array_api._array_object.Array, /, *, k: int = 0) -> heat.array_api._array_object.Array

   Returns the lower triangular part of a matrix (or a stack of matrices) ``x``.

   :param x: Input array having shape ``(..., M, N)`` and whose innermost two dimensions
             form ``MxN`` matrices.
   :type x: Array
   :param k: 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``.
   :type k: int


.. function:: triu(x: heat.array_api._array_object.Array, /, *, k: int = 0) -> heat.array_api._array_object.Array

   Returns the upper triangular part of a matrix (or a stack of matrices) ``x``.

   :param x: Input array having shape ``(..., M, N)`` and whose innermost two dimensions
             form ``MxN`` matrices.
   :type x: Array
   :param k: 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``.
   :type k: int


.. function:: zeros(shape: Union[int, Tuple[int, Ellipsis]], *, dtype: Optional[heat.array_api._typing.Dtype] = None, device: Optional[heat.array_api._typing.Device] = None) -> heat.array_api._array_object.Array

   Returns a new array having a specified ``shape`` and filled with zeros.

   :param shape: Output array shape.
   :type shape: Union[int, Tuple[int, ...]]
   :param dtype: Output array data type. Default: ``None``.
   :type dtype: Optional[Dtype]
   :param device: Device on which to place the created array.
   :type device: Optional[Device]


.. function:: zeros_like(x: heat.array_api._array_object.Array, /, *, dtype: Optional[heat.array_api._typing.Dtype] = None, device: Optional[heat.array_api._typing.Device] = None) -> heat.array_api._array_object.Array

   Returns a new array filled with zeros and having the same shape as an input array x.

   :param x: Input array from which to derive the output array shape.
   :type x: Array
   :param dtype: Output array data type. If ``dtype`` is ``None``, the output array data
                 type is inferred from x. Default: ``None``.
   :type dtype: Optional[Dtype]
   :param device: Device on which to place the created array. Default: ``None``.
   :type device: Optional[Device]