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


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


.. function:: concat(arrays: Union[Tuple[heat.array_api._array_object.Array, Ellipsis], List[heat.array_api._array_object.Array]], /, *, axis: Optional[int] = 0) -> heat.array_api._array_object.Array

   Joins a sequence of arrays along an existing axis.

   :param arrays: Input arrays to join. The arrays must have the same shape,
                  except in the dimension specified by ``axis``.
   :type arrays: Union[Tuple[Array, ...], List[Array]]
   :param axis: Axis along which the arrays will be joined. If ``axis`` is ``None``,
                arrays are flattened before concatenation. Default: ``0``.
   :type axis: Optional[int]


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

   Expands the shape of an array by inserting a new axis (dimension) of
   size one at the position specified by ``axis``.

   :param x: Input array.
   :type x: Array
   :param axis: Axis position (zero-based). If ``x`` has rank (i.e, number of dimensions) ``N``,
                a valid ``axis`` must reside on the closed-interval ``[-N-1, N]``.
   :type axis: int


.. function:: flip(x: heat.array_api._array_object.Array, /, *, axis: Optional[Union[int, Tuple[int, Ellipsis]]] = None) -> heat.array_api._array_object.Array

   Reverses the order of elements in an array along the given ``axis``. The
   shape of the array is preserved.

   :param x: Input array.
   :type x: Array
   :param axis: Axis (or axes) along which to flip. If ``axis`` is ``None``, the function
                flips all input array axes.
   :type axis: Optional[Union[int, Tuple[int, ...]]]


.. function:: permute_dims(x: heat.array_api._array_object.Array, /, axes: Tuple[int, Ellipsis]) -> heat.array_api._array_object.Array

   Permutes the axes (dimensions) of an array ``x``.

   :param x: Input array.
   :type x: Array
   :param axes: Tuple containing a permutation of ``(0, 1, ..., N-1)`` where ``N`` is the
                number of axes (dimensions) of ``x``.
   :type axes: Tuple[int, ...]


.. function:: reshape(x: heat.array_api._array_object.Array, /, shape: Tuple[int, Ellipsis], *, copy: Optional[bool] = None) -> heat.array_api._array_object.Array

   Reshapes an array without changing its data.

   :param x: Input array to reshape.
   :type x: Array
   :param shape: A new shape compatible with the original shape. One shape dimension
                 is allowed to be ``-1``. When a shape dimension is ``-1``, the
                 corresponding output array shape dimension is inferred from the length
                 of the array and the remaining dimensions.
   :type shape: Tuple[int, ...]
   :param copy: Boolean indicating whether or not to copy the input array.
   :type copy: Optional[bool]


.. function:: roll(x: heat.array_api._array_object.Array, /, shift: Union[int, Tuple[int, Ellipsis]], *, axis: Optional[Union[int, Tuple[int, Ellipsis]]] = None) -> heat.array_api._array_object.Array

   Rolls array elements along a specified axis. Array elements that roll
   beyond the last position are re-introduced at the first position.
   Array elements that roll beyond the first position are re-introduced
   at the last position.

   :param x: Input array.
   :type x: Array
   :param shift: Number of places by which the elements are shifted. If ``shift`` is a
                 tuple, then ``axis`` must be a tuple of the same size, and each of the
                 given axes is shifted by the corresponding element in ``shift``.
                 If ``shift`` is an ``int`` and ``axis`` a tuple, then the same ``shift``
                 is used for all specified axes.
   :type shift: Union[int, Tuple[int, ...]]
   :param axis: Axis (or axes) along which elements to shift. If ``axis`` is ``None``,
                the array is flattened, shifted, and then restored to its original shape.
                Default: ``None``.
   :type axis: Optional[Union[int, Tuple[int, ...]]]


.. function:: squeeze(x: heat.array_api._array_object.Array, /, axis: Union[int, Tuple[int, Ellipsis]]) -> heat.array_api._array_object.Array

   Removes singleton dimensions (axes) from ``x``.

   :param x: Input array.
   :type x: Array
   :param axis: Axis (or axes) to squeeze.
   :type axis: Union[int, Tuple[int, ...]]

   :raises `ValueError``, if an axis is selected with shape entry greater than one:


.. function:: stack(arrays: Union[Tuple[heat.array_api._array_object.Array, Ellipsis], List[heat.array_api._array_object.Array]], /, *, axis: int = 0) -> heat.array_api._array_object.Array

   Joins a sequence of arrays along a new axis.

   :param arrays: Input arrays to join. Each array must have the same shape.
   :type arrays: Union[Tuple[array, ...], List[array]]
   :param axis: Axis along which the arrays will be joined.
   :type axis: int