stack
==========

.. currentmodule:: treetensor.numpy

    
Documentation
------------------

.. autofunction:: stack

    
.. admonition:: Numpy Version Related
    :class: tip

    This documentation is based on 
    `numpy.stack <https://numpy.org/doc/1.24/reference/generated/numpy.stack.html>`_ 
    in `numpy v1.24.4 <https://numpy.org/doc/1.24/>`_.
    **Its arguments' arrangements depend on the version of numpy you installed**.
    
    If some arguments listed here are not working properly, please check your numpy's version 
    with the following command and find its documentation.
    
    .. code-block:: shell
        :linenos:
    
        python -c 'import numpy as np;print(np.__version__)'
    
    
    
    The arguments and keyword arguments supported in numpy v1.24.4 is listed below.
    
    

Description From Numpy v1.24
---------------------------------

.. currentmodule:: numpy

    
.. function:: Join a sequence of arrays along a new axis.


    The ``axis`` parameter specifies the index of the new axis in the
    dimensions of the result. For example, if ``axis=0`` it will be the first
    dimension and if ``axis=-1`` it will be the last dimension.

    .. versionadded:: 1.10.0

Parameters
~~~~~~~~~~
    arrays \: sequence of array_like
        Each array must have the same shape.

    axis \: int, optional
        The axis in the result array along which the input arrays are stacked.

    out \: ndarray, optional
        If provided, the destination to place the result. The shape must be
        correct, matching that of what stack would have returned if no
        out argument were specified.

    dtype \: str or dtype
        If provided, the destination array will have this dtype. Cannot be
        provided together with `out`.

        .. versionadded:: 1.24

    casting \: {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional
        Controls what kind of data casting may occur. Defaults to 'same_kind'.

        .. versionadded:: 1.24


Returns
~~~~~~~
    stacked \: ndarray
        The stacked array has one more dimension than the input arrays.

See Also
~~~~~~~~
    concatenate \: Join a sequence of arrays along an existing axis.
    block \: Assemble an nd-array from nested lists of blocks.
    split \: Split array into a list of multiple sub-arrays of equal size.

Examples
~~~~~~~~
    >>> arrays = [np.random.randn(3, 4) for _ in range(10)]
    >>> np.stack(arrays, axis=0).shape
    (10, 3, 4)

    >>> np.stack(arrays, axis=1).shape
    (3, 10, 4)

    >>> np.stack(arrays, axis=2).shape
    (3, 4, 10)

    >>> a = np.array([1, 2, 3])
    >>> b = np.array([4, 5, 6])
    >>> np.stack((a, b))
    array([[1, 2, 3],
           [4, 5, 6]])

    >>> np.stack((a, b), axis=-1)
    array([[1, 4],
           [2, 5],
           [3, 6]])