maxframe 1.3.1__cp38-cp38-macosx_10_9_universal2.whl → 2.0.0b1__cp38-cp38-macosx_10_9_universal2.whl

maxframe/tensor/linalg/svd.py

@@ -0,0 +1,167 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import numpy as np
+from numpy.linalg import LinAlgError
+
+from ... import opcodes
+from ...core import ExecutableTuple
+from ...serialization.serializables import StringField
+from ..core import TensorOrder
+from ..datasource import tensor as astensor
+from ..operators import TensorHasInput, TensorOperatorMixin
+
+
+class TensorSVD(TensorHasInput, TensorOperatorMixin):
+    _op_type_ = opcodes.SVD
+
+    method = StringField("method")
+
+    @property
+    def output_limit(self):
+        return 3
+
+    @classmethod
+    def _is_svd(cls):
+        return True
+
+    @staticmethod
+    def _calc_svd_shapes(a):
+        """
+        Calculate output shapes of singular value decomposition.
+        Follow the behavior of `numpy`:
+        if a's shape is (6, 18), U's shape is (6, 6), s's shape is (6,), V's shape is (6, 18)
+        if a's shape is (18, 6), U's shape is (18, 6), s's shape is (6,), V's shape is (6, 6)
+        :param a: input tensor
+        :return: (U.shape, s.shape, V.shape)
+        """
+        x, y = a.shape
+        if x > y:
+            return (x, y), (y,), (y, y)
+        else:
+            return (x, x), (x,), (x, y)
+
+    def __call__(self, a):
+        a = astensor(a)
+
+        if a.ndim != 2:
+            raise LinAlgError(
+                f"{a.ndim}-dimensional tensor given. Tensor must be two-dimensional"
+            )
+
+        tiny_U, tiny_s, tiny_V = np.linalg.svd(np.ones((1, 1), dtype=a.dtype))
+
+        # if a's shape is (6, 18), U's shape is (6, 6), s's shape is (6,), V's shape is (6, 18)
+        # if a's shape is (18, 6), U's shape is (18, 6), s's shape is (6,), V's shape is (6, 6)
+        U_shape, s_shape, V_shape = self._calc_svd_shapes(a)
+        U, s, V = self.new_tensors(
+            [a],
+            order=TensorOrder.C_ORDER,
+            kws=[
+                {"side": "U", "dtype": tiny_U.dtype, "shape": U_shape},
+                {"side": "s", "dtype": tiny_s.dtype, "shape": s_shape},
+                {"side": "V", "dtype": tiny_V.dtype, "shape": V_shape},
+            ],
+        )
+        return ExecutableTuple([U, s, V])
+
+
+def svd(a, method="tsqr"):
+    """
+    Singular Value Decomposition.
+
+    When `a` is a 2D tensor, it is factorized as ``u @ np.diag(s) @ vh
+    = (u * s) @ vh``, where `u` and `vh` are 2D unitary tensors and `s` is a 1D
+    tensor of `a`'s singular values. When `a` is higher-dimensional, SVD is
+    applied in stacked mode as explained below.
+
+    Parameters
+    ----------
+    a : (..., M, N) array_like
+        A real or complex tensor with ``a.ndim >= 2``.
+    method: {'tsqr'}, optional
+        method to calculate qr factorization, tsqr as default
+
+        TSQR is presented in:
+
+            A. Benson, D. Gleich, and J. Demmel.
+            Direct QR factorizations for tall-and-skinny matrices in
+            MapReduce architectures.
+            IEEE International Conference on Big Data, 2013.
+            http://arxiv.org/abs/1301.1071
+
+
+    Returns
+    -------
+    u : { (..., M, M), (..., M, K) } tensor
+        Unitary tensor(s). The first ``a.ndim - 2`` dimensions have the same
+        size as those of the input `a`. The size of the last two dimensions
+        depends on the value of `full_matrices`. Only returned when
+        `compute_uv` is True.
+    s : (..., K) tensor
+        Vector(s) with the singular values, within each vector sorted in
+        descending order. The first ``a.ndim - 2`` dimensions have the same
+        size as those of the input `a`.
+    vh : { (..., N, N), (..., K, N) } tensor
+        Unitary tensor(s). The first ``a.ndim - 2`` dimensions have the same
+        size as those of the input `a`. The size of the last two dimensions
+        depends on the value of `full_matrices`. Only returned when
+        `compute_uv` is True.
+
+    Raises
+    ------
+    LinAlgError
+        If SVD computation does not converge.
+
+    Notes
+    -----
+
+    SVD is usually described for the factorization of a 2D matrix :math:`A`.
+    The higher-dimensional case will be discussed below. In the 2D case, SVD is
+    written as :math:`A = U S V^H`, where :math:`A = a`, :math:`U= u`,
+    :math:`S= \\mathtt{np.diag}(s)` and :math:`V^H = vh`. The 1D tensor `s`
+    contains the singular values of `a` and `u` and `vh` are unitary. The rows
+    of `vh` are the eigenvectors of :math:`A^H A` and the columns of `u` are
+    the eigenvectors of :math:`A A^H`. In both cases the corresponding
+    (possibly non-zero) eigenvalues are given by ``s**2``.
+
+    If `a` has more than two dimensions, then broadcasting rules apply, as
+    explained in :ref:`routines.linalg-broadcasting`. This means that SVD is
+    working in "stacked" mode: it iterates over all indices of the first
+    ``a.ndim - 2`` dimensions and for each combination SVD is applied to the
+    last two indices. The matrix `a` can be reconstructed from the
+    decomposition with either ``(u * s[..., None, :]) @ vh`` or
+    ``u @ (s[..., None] * vh)``. (The ``@`` operator can be replaced by the
+    function ``mt.matmul`` for python versions below 3.5.)
+
+    Examples
+    --------
+    >>> import maxframe.tensor as mt
+    >>> a = mt.random.randn(9, 6) + 1j*mt.random.randn(9, 6)
+    >>> b = mt.random.randn(2, 7, 8, 3) + 1j*mt.random.randn(2, 7, 8, 3)
+
+    Reconstruction based on reduced SVD, 2D case:
+
+    >>> u, s, vh = mt.linalg.svd(a)
+    >>> u.shape, s.shape, vh.shape
+    ((9, 6), (6,), (6, 6))
+    >>> np.allclose(a, np.dot(u * s, vh))
+    True
+    >>> smat = np.diag(s)
+    >>> np.allclose(a, np.dot(u, np.dot(smat, vh)))
+    True
+
+    """
+    op = TensorSVD(method=method)
+    return op(a)

maxframe/tensor/linalg/tensordot.py

@@ -0,0 +1,213 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from collections.abc import Iterable
+from typing import List
+
+import numpy as np
+
+from ... import opcodes
+from ...core import EntityData
+from ...serialization.serializables import FieldTypes, KeyField, TupleField
+from ..core import TensorOrder
+from ..datasource import tensor as astensor
+from ..operators import TensorOperator, TensorOperatorMixin
+
+
+class TensorTensorDot(TensorOperator, TensorOperatorMixin):
+    _op_type_ = opcodes.TENSORDOT
+
+    a = KeyField("a")
+    b = KeyField("b")
+    a_axes = TupleField("a_axes", FieldTypes.int32)
+    b_axes = TupleField("b_axes", FieldTypes.int32)
+
+    @classmethod
+    def _set_inputs(cls, op: "TensorTensorDot", inputs: List[EntityData]):
+        super()._set_inputs(op, inputs)
+        op.a = op._inputs[0]
+        op.b = op._inputs[1]
+
+    def __call__(self, a, b):
+        shape = tuple(
+            s for i, s in enumerate(a.shape) if i not in set(self.a_axes)
+        ) + tuple(s for i, s in enumerate(b.shape) if i not in set(self.b_axes))
+        return self.new_tensor([a, b], shape, order=TensorOrder.C_ORDER)
+
+
+def tensordot(a, b, axes=2, sparse=None):
+    """
+    Compute tensor dot product along specified axes for tensors >= 1-D.
+
+    Given two tensors (arrays of dimension greater than or equal to one),
+    `a` and `b`, and an array_like object containing two array_like
+    objects, ``(a_axes, b_axes)``, sum the products of `a`'s and `b`'s
+    elements (components) over the axes specified by ``a_axes`` and
+    ``b_axes``. The third argument can be a single non-negative
+    integer_like scalar, ``N``; if it is such, then the last ``N``
+    dimensions of `a` and the first ``N`` dimensions of `b` are summed
+    over.
+
+    Parameters
+    ----------
+    a, b : array_like, len(shape) >= 1
+        Tensors to "dot".
+    axes : int or (2,) array_like
+        * integer_like
+          If an int N, sum over the last N axes of `a` and the first N axes
+          of `b` in order. The sizes of the corresponding axes must match.
+        * (2,) array_like
+          Or, a list of axes to be summed over, first sequence applying to `a`,
+          second to `b`. Both elements array_like must be of the same length.
+
+    See Also
+    --------
+    dot, einsum
+
+    Notes
+    -----
+    Three common use cases are:
+
+        * ``axes = 0`` : tensor product :math:`a\\otimes b`
+        * ``axes = 1`` : tensor dot product :math:`a\\cdot b`
+        * ``axes = 2`` : (default) tensor double contraction :math:`a:b`
+
+    When `axes` is integer_like, the sequence for evaluation will be: first
+    the -Nth axis in `a` and 0th axis in `b`, and the -1th axis in `a` and
+    Nth axis in `b` last.
+
+    When there is more than one axis to sum over - and they are not the last
+    (first) axes of `a` (`b`) - the argument `axes` should consist of
+    two sequences of the same length, with the first axis to sum over given
+    first in both sequences, the second axis second, and so forth.
+
+    Examples
+    --------
+    >>> import maxframe.tensor as mt
+
+    A "traditional" example:
+
+    >>> a = mt.arange(60.).reshape(3,4,5)
+    >>> b = mt.arange(24.).reshape(4,3,2)
+    >>> c = mt.tensordot(a,b, axes=([1,0],[0,1]))
+    >>> c.shape
+    (5, 2)
+
+    >>> r = c.execute()
+    >>> r
+    array([[ 4400.,  4730.],
+           [ 4532.,  4874.],
+           [ 4664.,  5018.],
+           [ 4796.,  5162.],
+           [ 4928.,  5306.]])
+
+    >>> # A slower but equivalent way of computing the same...
+    >>> ra = np.arange(60.).reshape(3,4,5)
+    >>> rb = np.arange(24.).reshape(4,3,2)
+    >>> d = np.zeros((5,2))
+    >>> for i in range(5):
+    ...   for j in range(2):
+    ...     for k in range(3):
+    ...       for n in range(4):
+    ...         d[i,j] += ra[k,n,i] * rb[n,k,j]
+    >>> r == d
+    array([[ True,  True],
+           [ True,  True],
+           [ True,  True],
+           [ True,  True],
+           [ True,  True]], dtype=bool)
+
+    An extended example taking advantage of the overloading of + and \\*:
+
+    >>> a = mt.array(range(1, 9))
+    >>> a.shape = (2, 2, 2)
+    >>> A = mt.array(('a', 'b', 'c', 'd'), dtype=object)
+    >>> A.shape = (2, 2)
+    >>> a.execute(); A.execute()
+    array([[[1, 2],
+            [3, 4]],
+           [[5, 6],
+            [7, 8]]])
+    array([[a, b],
+           [c, d]], dtype=object)
+
+    >>> mt.tensordot(a, A).execute() # third argument default is 2 for double-contraction
+    array([abbcccdddd, aaaaabbbbbbcccccccdddddddd], dtype=object)
+
+    >>> mt.tensordot(a, A, 1).execute()
+    array([[[acc, bdd],
+            [aaacccc, bbbdddd]],
+           [[aaaaacccccc, bbbbbdddddd],
+            [aaaaaaacccccccc, bbbbbbbdddddddd]]], dtype=object)
+
+    >>> mt.tensordot(a, A, 0).execute() # tensor product (result too long to incl.)
+    array([[[[[a, b],
+              [c, d]],
+              ...
+
+    >>> mt.tensordot(a, A, (0, 1)).execute()
+    array([[[abbbbb, cddddd],
+            [aabbbbbb, ccdddddd]],
+           [[aaabbbbbbb, cccddddddd],
+            [aaaabbbbbbbb, ccccdddddddd]]], dtype=object)
+
+    >>> mt.tensordot(a, A, (2, 1)).execute()
+    array([[[abb, cdd],
+            [aaabbbb, cccdddd]],
+           [[aaaaabbbbbb, cccccdddddd],
+            [aaaaaaabbbbbbbb, cccccccdddddddd]]], dtype=object)
+
+    >>> mt.tensordot(a, A, ((0, 1), (0, 1))).execute()
+    array([abbbcccccddddddd, aabbbbccccccdddddddd], dtype=object)
+
+    >>> mt.tensordot(a, A, ((2, 1), (1, 0))).execute()
+    array([acccbbdddd, aaaaacccccccbbbbbbdddddddd], dtype=object)
+    """
+    a = astensor(a)
+    b = astensor(b)
+
+    if isinstance(axes, Iterable):
+        a_axes, b_axes = axes
+    else:
+        a_axes = tuple(range(a.ndim - 1, a.ndim - axes - 1, -1))
+        b_axes = tuple(range(0, axes))
+
+    if isinstance(a_axes, Iterable):
+        a_axes = tuple(a_axes)
+    else:
+        a_axes = (a_axes,)
+    a_axes = tuple(axis if axis >= 0 else a.ndim + axis for axis in a_axes)
+    if isinstance(b_axes, Iterable):
+        b_axes = tuple(b_axes)
+    else:
+        b_axes = (b_axes,)
+    b_axes = tuple(axis if axis >= 0 else b.ndim + axis for axis in b_axes)
+
+    if (
+        a.shape
+        and b.shape
+        and not np.array_equal(
+            np.array(a.shape)[list(a_axes)], np.array(b.shape)[list(b_axes)]
+        )
+    ):
+        raise ValueError("shape-mismatch for sum")
+
+    sparse = sparse if sparse is not None else a.issparse() and b.issparse()
+    op = TensorTensorDot(
+        a_axes=a_axes,
+        b_axes=b_axes,
+        dtype=np.promote_types(a.dtype, b.dtype),
+        sparse=sparse,
+    )
+    return op(a, b)

maxframe/tensor/linalg/vdot.py

@@ -0,0 +1,73 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from ..datasource import tensor as astensor
+from .dot import dot
+
+
+def vdot(a, b):
+    """
+    Return the dot product of two vectors.
+
+    The vdot(`a`, `b`) function handles complex numbers differently than
+    dot(`a`, `b`).  If the first argument is complex the complex conjugate
+    of the first argument is used for the calculation of the dot product.
+
+    Note that `vdot` handles multidimensional tensors differently than `dot`:
+    it does *not* perform a matrix product, but flattens input arguments
+    to 1-D vectors first. Consequently, it should only be used for vectors.
+
+    Parameters
+    ----------
+    a : array_like
+        If `a` is complex the complex conjugate is taken before calculation
+        of the dot product.
+    b : array_like
+        Second argument to the dot product.
+
+    Returns
+    -------
+    output : Tensor
+        Dot product of `a` and `b`.  Can be an int, float, or
+        complex depending on the types of `a` and `b`.
+
+    See Also
+    --------
+    dot : Return the dot product without using the complex conjugate of the
+          first argument.
+
+    Examples
+    --------
+    >>> import maxframe.tensor as mt
+
+    >>> a = mt.array([1+2j,3+4j])
+    >>> b = mt.array([5+6j,7+8j])
+    >>> mt.vdot(a, b).execute()
+    (70-8j)
+    >>> mt.vdot(b, a).execute()
+    (70+8j)
+
+    Note that higher-dimensional arrays are flattened!
+
+    >>> a = mt.array([[1, 4], [5, 6]])
+    >>> b = mt.array([[4, 1], [2, 2]])
+    >>> mt.vdot(a, b).execute()
+    30
+    >>> mt.vdot(b, a).execute()
+    30
+    >>> 1*4 + 4*1 + 5*2 + 6*2
+    30
+    """
+    a, b = astensor(a), astensor(b)
+    return dot(a.conj().ravel(), b.ravel())

maxframe/tensor/merge/__init__.py

@@ -12,6 +12,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from .append import append
+from .column_stack import column_stack
 from .concatenate import concatenate
+from .dstack import dstack
+from .hstack import hstack
 from .stack import stack
 from .vstack import vstack

maxframe/tensor/merge/append.py

@@ -0,0 +1,74 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from ..datasource.array import asarray
+from ..misc.ravel import ravel
+from .concatenate import concatenate
+
+
+def append(arr, values, axis=None):
+    """
+    Append values to the end of an array.
+
+    Parameters
+    ----------
+    arr : array_like
+        Values are appended to a copy of this array.
+    values : array_like
+        These values are appended to a copy of `arr`.  It must be of the
+        correct shape (the same shape as `arr`, excluding `axis`).  If
+        `axis` is not specified, `values` can be any shape and will be
+        flattened before use.
+    axis : int, optional
+        The axis along which `values` are appended.  If `axis` is not
+        given, both `arr` and `values` are flattened before use.
+
+    Returns
+    -------
+    append : Tensor
+        A copy of `arr` with `values` appended to `axis`.  Note that
+        `append` does not occur in-place: a new array is allocated and
+        filled.  If `axis` is None, `out` is a flattened array.
+
+    See Also
+    --------
+    insert : Insert elements into an array.
+    delete : Delete elements from an array.
+
+    Examples
+    --------
+    >>> import maxframe.tensor as mt
+
+    >>> mt.append([1, 2, 3], [[4, 5, 6], [7, 8, 9]]).execute()
+    array([1, 2, 3, ..., 7, 8, 9])
+
+    When `axis` is specified, `values` must have the correct shape.
+
+    >>> mt.append([[1, 2, 3], [4, 5, 6]], [[7, 8, 9]], axis=0).execute()
+    array([[1, 2, 3],
+           [4, 5, 6],
+           [7, 8, 9]])
+    >>> mt.append([[1, 2, 3], [4, 5, 6]], [7, 8, 9], axis=0)
+    Traceback (most recent call last):
+        ...
+    ValueError: all the input tensors must have same number of dimensions
+
+    """
+    arr = asarray(arr)
+    if axis is None:
+        if arr.ndim != 1:
+            arr = arr.ravel()
+        values = ravel(values)
+        axis = arr.ndim - 1
+    return concatenate((arr, values), axis=axis)

maxframe/tensor/merge/column_stack.py

@@ -0,0 +1,63 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from ..datasource import tensor as astensor
+from .concatenate import concatenate
+
+
+def column_stack(tup):
+    """
+    Stack 1-D tensors as columns into a 2-D tensor.
+
+    Take a sequence of 1-D tensors and stack them as columns
+    to make a single 2-D tensor. 2-D tensors are stacked as-is,
+    just like with `hstack`.  1-D tensors are turned into 2-D columns
+    first.
+
+    Parameters
+    ----------
+    tup : sequence of 1-D or 2-D tensors.
+        Tensors to stack. All of them must have the same first dimension.
+
+    Returns
+    -------
+    stacked : 2-D tensor
+        The tensor formed by stacking the given tensors.
+
+    See Also
+    --------
+    stack, hstack, vstack, concatenate
+
+    Examples
+    --------
+    >>> import maxframe.tensor as mt
+
+    >>> a = mt.array((1,2,3))
+    >>> b = mt.array((2,3,4))
+    >>> mt.column_stack((a,b)).execute()
+    array([[1, 2],
+           [2, 3],
+           [3, 4]])
+
+    """
+    from ..datasource import array
+
+    arrays = []
+    for a in tup:
+        a = astensor(a)
+        if a.ndim < 2:
+            a = array(a, ndmin=2).T
+        arrays.append(a)
+
+    return concatenate(arrays, 1)

maxframe/tensor/merge/concatenate.py

@@ -24,7 +24,7 @@ from ..utils import validate_axis
 class TensorConcatenate(TensorOperator, TensorOperatorMixin):
     _op_type_ = opcodes.CONCATENATE
 
-    axis = Int32Field("axis", default=0)
+    axis = Int32Field("axis", default=None)
 
     def __call__(self, tensors):
         axis = self.axis
@@ -93,8 +93,9 @@ def concatenate(tensors, axis=0):
 
 def _concatenate(tensors, axis=0):
     dtype = np.result_type(*(t.dtype for t in tensors))
+    sparse = all(t.issparse() for t in tensors)
 
-    op = TensorConcatenate(axis=axis, dtype=dtype)
+    op = TensorConcatenate(axis=axis, dtype=dtype, sparse=sparse)
     return op(tensors)
 
 

maxframe/tensor/merge/dstack.py

@@ -0,0 +1,71 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from ..misc import atleast_3d
+from .concatenate import concatenate
+
+
+def dstack(tup):
+    """
+    Stack tensors in sequence depth wise (along third axis).
+
+    This is equivalent to concatenation along the third axis after 2-D tensors
+    of shape `(M,N)` have been reshaped to `(M,N,1)` and 1-D arrays of shape
+    `(N,)` have been reshaped to `(1,N,1)`. Rebuilds arrays divided by
+    `dsplit`.
+
+    This function makes most sense for arrays with up to 3 dimensions. For
+    instance, for pixel-data with a height (first axis), width (second axis),
+    and r/g/b channels (third axis). The functions `concatenate`, `stack` and
+    `block` provide more general stacking and concatenation operations.
+
+    Parameters
+    ----------
+    tup : sequence of tensors
+        The tensors must have the same shape along all but the third axis.
+        1-D or 2-D arrays must have the same shape.
+
+    Returns
+    -------
+    stacked : Tensor
+        The array formed by stacking the given tensors, will be at least 3-D.
+
+    See Also
+    --------
+    stack : Join a sequence of tensors along a new axis.
+    vstack : Stack along first axis.
+    hstack : Stack along second axis.
+    concatenate : Join a sequence of arrays along an existing axis.
+    dsplit : Split tensor along third axis.
+
+    Examples
+    --------
+    >>> import maxframe.tensor as mt
+
+    >>> a = mt.array((1,2,3))
+    >>> b = mt.array((2,3,4))
+    >>> mt.dstack((a,b)).execute()
+    array([[[1, 2],
+            [2, 3],
+            [3, 4]]])
+
+    >>> a = mt.array([[1],[2],[3]])
+    >>> b = mt.array([[2],[3],[4]])
+    >>> mt.dstack((a,b)).execute()
+    array([[[1, 2]],
+           [[2, 3]],
+           [[3, 4]]])
+
+    """
+    return concatenate([atleast_3d(t) for t in tup], axis=2)