maxframe 2.4.0rc1__cp312-cp312-win32.whl

maxframe/tensor/linalg/inv.py

@@ -0,0 +1,83 @@
+# 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 TensorOrder
+from ..datasource import tensor as astensor
+from ..operators import TensorHasInput, TensorOperatorMixin
+
+
+class TensorInv(TensorHasInput, TensorOperatorMixin):
+    _op_type_ = opcodes.INV
+
+    def __call__(self, a):
+        a = astensor(a)
+        return self.new_tensor([a], a.shape, order=TensorOrder.C_ORDER)
+
+
+def inv(a, sparse=None):
+    """
+    Compute the (multiplicative) inverse of a matrix.
+    Given a square matrix `a`, return the matrix `ainv` satisfying
+    ``dot(a, ainv) = dot(ainv, a) = eye(a.shape[0])``.
+
+    Parameters
+    ----------
+    a : (..., M, M) array_like
+        Matrix to be inverted.
+    sparse: bool, optional
+        Return sparse value or not.
+
+    Returns
+    -------
+    ainv : (..., M, M) ndarray or matrix
+        (Multiplicative) inverse of the matrix `a`.
+
+    Raises
+    ------
+    LinAlgError
+        If `a` is not square or inversion fails.
+
+    Examples
+    --------
+    >>> import maxframe.tensor as mt
+    >>> a = np.array([[1., 2.], [3., 4.]])
+    >>> ainv = mt.linalg.inv(a)
+    >>> mt.allclose(mt.dot(a, ainv), mt.eye(2)).execute()
+    True
+
+    >>> mt.allclose(mt.dot(ainv, a), mt.eye(2)).execute()
+    True
+
+    >>> ainv.execute()
+    array([[ -2. ,  1. ],
+           [ 1.5, -0.5]])
+    """
+
+    # TODO: using some parallel algorithm for matrix inversion.
+    a = astensor(a)
+    if a.ndim != 2:
+        raise LinAlgError(
+            f"{a.ndim}-dimensional array given. Tensor must be two-dimensional"
+        )
+    if a.shape[0] != a.shape[1]:
+        raise LinAlgError("Input must be square")
+
+    tiny_inv = np.linalg.inv(np.array([[1, 2], [2, 5]], dtype=a.dtype))
+    sparse = sparse if sparse is not None else a.issparse()
+    op = TensorInv(dtype=tiny_inv.dtype, sparse=sparse)
+    return op(a)

maxframe/tensor/linalg/lstsq.py

@@ -0,0 +1,100 @@
+# 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 ...core import ExecutableTuple
+from ...udf import builtin_function
+from .svd import svd
+
+
+@builtin_function
+def _cut_residuals(residuals, full_rank):
+    return residuals if full_rank else np.array([], dtype=residuals.dtype)
+
+
+def lstsq(a, b, rcond=None):
+    """
+    Return the least-squares solution to a linear matrix equation.
+
+    Computes the vector `x` that approximately solves the equation
+    ``a @ x = b``. The equation may be under-, well-, or over-determined
+    (i.e., the number of linearly independent rows of `a` can be less than,
+    equal to, or greater than its number of linearly independent columns).
+    If `a` is square and of full rank, then `x` (but for round-off error)
+    is the "exact" solution of the equation. Else, `x` minimizes the
+    Euclidean 2-norm :math:`||b - ax||`. If there are multiple minimizing
+    solutions, the one with the smallest 2-norm :math:`||x||` is returned.
+
+    Parameters
+    ----------
+    a : (M, N) array_like
+        "Coefficient" matrix.
+    b : {(M,), (M, K)} array_like
+        Ordinate or "dependent variable" values. If `b` is two-dimensional,
+        the least-squares solution is calculated for each of the `K` columns
+        of `b`.
+    rcond : float, optional
+        Cut-off ratio for small singular values of `a`.
+        For the purposes of rank determination, singular values are treated
+        as zero if they are smaller than `rcond` times the largest singular
+        value of `a`.
+        The default uses the machine precision times ``max(M, N)``.  Passing
+        ``-1`` will use machine precision.
+
+    Returns
+    -------
+    x : {(N,), (N, K)} ndarray
+        Least-squares solution. If `b` is two-dimensional,
+        the solutions are in the `K` columns of `x`.
+    residuals : {(1,), (K,), (0,)} ndarray
+        Sums of squared residuals: Squared Euclidean 2-norm for each column in
+        ``b - a @ x``.
+        If the rank of `a` is < N or M <= N, this is an empty array.
+        If `b` is 1-dimensional, this is a (1,) shape array.
+        Otherwise the shape is (K,).
+    rank : int
+        Rank of matrix `a`.
+    s : (min(M, N),) ndarray
+        Singular values of `a`.
+
+    Raises
+    ------
+    LinAlgError
+        If computation does not converge.
+
+    Notes
+    -----
+    If `b` is a matrix, then all array results are returned as matrices.
+    """
+    # fixme when has_unknown_shape(a)
+
+    rcond = rcond if rcond is not None and rcond < 1 else None
+    if rcond is None:
+        rcond = max(a.shape) * np.finfo(a.dtype).eps
+    elif rcond == -1:
+        rcond = np.finfo(np.float64).eps
+
+    u, s, vt = svd(a)
+    cutoff = (s > s.max() * rcond).astype(int)
+    # v^T diag(1.0 / s) u_1^T b
+    x = vt.T * (1.0 / s * cutoff) @ u.T[: a.shape[1], :] @ b
+    residuals = b - a.dot(x)
+    residuals = abs(residuals**2).sum(axis=0, keepdims=b.ndim == 1)
+
+    rank = cutoff.sum()
+    residuals = residuals.mf.apply_chunk(
+        _cut_residuals, dtype=residuals.dtype, full_rank=rank == min(a.shape)
+    )
+    return ExecutableTuple((x, residuals, rank, s))

maxframe/tensor/linalg/lu.py

@@ -0,0 +1,115 @@
+# 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 ..datasource import tensor as astensor
+from ..operators import TensorHasInput, TensorOperatorMixin
+
+
+class TensorLU(TensorHasInput, TensorOperatorMixin):
+    _op_type_ = opcodes.LU
+
+    @property
+    def output_limit(self):
+        return 3
+
+    def __call__(self, a):
+        import scipy.linalg
+
+        a = astensor(a)
+        if a.ndim != 2:
+            raise LinAlgError(
+                f"{a.ndim}-dimensional array given. Tensor must be two-dimensional"
+            )
+
+        if a.shape[0] > a.shape[1]:
+            p_shape = (a.shape[0],) * 2
+            l_shape = a.shape
+            u_shape = (a.shape[1],) * 2
+        elif a.shape[0] < a.shape[1]:
+            p_shape = (a.shape[0],) * 2
+            l_shape = (a.shape[0],) * 2
+            u_shape = a.shape
+        else:
+            p_shape, l_shape, u_shape = (a.shape,) * 3
+
+        tiny_p, tiny_l, tiny_u = scipy.linalg.lu(
+            np.array([[1, 2], [2, 5]], dtype=a.dtype)
+        )
+
+        order = a.order
+        p, l, u = self.new_tensors(
+            [a],
+            kws=[
+                {"side": "p", "dtype": tiny_p.dtype, "shape": p_shape, "order": order},
+                {"side": "l", "dtype": tiny_l.dtype, "shape": l_shape, "order": order},
+                {"side": "u", "dtype": tiny_u.dtype, "shape": u_shape, "order": order},
+            ],
+        )
+        return ExecutableTuple([p, l, u])
+
+
+def lu(a):
+    """
+    LU decomposition
+
+    The decomposition is::
+        A = P L U
+    where P is a permutation matrix, L lower triangular with unit diagonal elements,
+    and U upper triangular.
+
+    Parameters
+    ----------
+    a : (M, N) array_like
+        Array to decompose
+
+    Returns
+    -------
+    p : (M, M) ndarray
+        Permutation matrix
+    l : (M, K) ndarray
+        Lower triangular or trapezoidal matrix with unit diagonal.
+        K = min(M, N)
+    u : (K, N) ndarray
+        Upper triangular or trapezoidal matrix
+
+    Examples
+    --------
+    >>> import maxframe.tensor as mt
+
+    >>> A = mt.array([[1,2],[2,3]])
+    >>> A.execute()
+    array([[ 1,  2],
+           [ 2,  3]])
+    >>> P, L, U = mt.linalg.lu(A)
+    >>> P.execute()
+    array([[ 0,  1],
+           [ 1,  0]])
+    >>> L.execute()
+    array([[ 1,  0],
+           [ 0.5,  1]])
+    >>> U.execute()
+    array([[ 2,  3],
+           [ 0,  0.5]])
+    >>> mt.dot(P.dot(L), U).execute() # verify that PL * U = A
+    array([[ 1,  2],
+           [ 2,  3]])
+
+    """
+    op = TensorLU(sparse=a.issparse())
+    return op(a)

maxframe/tensor/linalg/matmul.py

@@ -0,0 +1,225 @@
+# 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 typing import List
+
+import numpy as np
+
+from ... import opcodes
+from ...core import EntityData
+from ...serialization.serializables import KeyField, StringField
+from ..core import Tensor, TensorOrder
+from ..datasource import tensor as astensor
+from ..operators import TensorOperator, TensorOperatorMixin
+from ..utils import broadcast_shape, check_order, check_out_param
+
+
+class TensorMatmul(TensorOperator, TensorOperatorMixin):
+    _op_type_ = opcodes.MATMUL
+
+    a = KeyField("a")
+    b = KeyField("b")
+    casting = StringField("casting", default="same_kind")
+    order = StringField("order", default="K")
+
+    def __init__(self, **kw):
+        super().__init__(**kw)
+        check_order(self.order)
+
+    @classmethod
+    def _set_inputs(cls, op: "TensorMatmul", inputs: List[EntityData]):
+        super()._set_inputs(op, inputs)
+        op.a = op._inputs[0]
+        op.b = op._inputs[1]
+
+    def _calc_order(self, a, b, out):
+        if out is not None:
+            return out.order
+
+        if self.order in "A":
+            if a.order == TensorOrder.C_ORDER or b.order == TensorOrder.C_ORDER:
+                return TensorOrder.C_ORDER
+            else:
+                return TensorOrder.F_ORDER
+        elif self.order in "CK":
+            return TensorOrder.C_ORDER
+        else:
+            return TensorOrder.F_ORDER
+
+    def __call__(self, a, b, out=None):
+        from ..misc import broadcast_to
+
+        if a.ndim == 0 or b.ndim == 0:
+            raise ValueError("Scalar operands are not allowed, use '*' instead")
+        if out is not None and not isinstance(out, Tensor):
+            raise TypeError(f"out must be a Tensor, got {type(out)} instead")
+
+        a_is_1d = False
+        if a.ndim == 1:
+            a_is_1d = True
+            a = a[np.newaxis, :]
+
+        b_is_1d = False
+        if b.ndim == 1:
+            b_is_1d = True
+            b = b[:, np.newaxis]
+
+        if a.ndim < b.ndim:
+            a = a[(b.ndim - a.ndim) * (np.newaxis,)]
+        elif a.ndim > b.ndim:
+            b = b[(a.ndim - b.ndim) * (np.newaxis,)]
+
+        if a.shape[-1] != b.shape[-2]:
+            raise ValueError(
+                f"shape {a.shape} and {b.shape} not aligned: "
+                f"{a.shape[-1]} (dim {a.ndim - 1}) != {b.shape[-2]} (dim {b.ndim - 2})"
+            )
+
+        shape = broadcast_shape(a.shape[:-2], b.shape[:-2]) + (a.shape[-2], b.shape[-1])
+        order = self._calc_order(a, b, out)
+        t = self.new_tensor([a, b], shape, order=order)
+
+        if a_is_1d:
+            t = t[..., 0, :]
+        if b_is_1d:
+            t = t[..., 0]
+
+        if out is not None:
+            check_out_param(out, t, self.casting)
+            t = broadcast_to(t, out.shape)
+            out.data = t.data
+            return out
+
+        return t
+
+
+def matmul(a, b, sparse=None, out=None, **kw):
+    """
+    Matrix product of two tensors.
+
+    The behavior depends on the arguments in the following way.
+
+    - If both arguments are 2-D they are multiplied like conventional
+      matrices.
+    - If either argument is N-D, N > 2, it is treated as a stack of
+      matrices residing in the last two indexes and broadcast accordingly.
+    - If the first argument is 1-D, it is promoted to a matrix by
+      prepending a 1 to its dimensions. After matrix multiplication
+      the prepended 1 is removed.
+    - If the second argument is 1-D, it is promoted to a matrix by
+      appending a 1 to its dimensions. After matrix multiplication
+      the appended 1 is removed.
+
+    Multiplication by a scalar is not allowed, use ``*`` instead. Note that
+    multiplying a stack of matrices with a vector will result in a stack of
+    vectors, but matmul will not recognize it as such.
+
+    ``matmul`` differs from ``dot`` in two important ways.
+
+    - Multiplication by scalars is not allowed.
+    - Stacks of matrices are broadcast together as if the matrices
+      were elements.
+
+    Parameters
+    ----------
+    a : array_like
+        First argument.
+    b : array_like
+        Second argument.
+    out : Tensor, optional
+        Output argument. This must have the exact kind that would be returned
+        if it was not used. In particular, it must have the right type,
+        and its dtype must be the dtype that would be returned
+        for `dot(a,b)`. This is a performance feature. Therefore, if these
+        conditions are not met, an exception is raised, instead of attempting
+        to be flexible.
+
+    Returns
+    -------
+    output : Tensor
+        Returns the dot product of `a` and `b`.  If `a` and `b` are both
+        1-D arrays then a scalar is returned; otherwise an array is
+        returned.  If `out` is given, then it is returned.
+
+    Raises
+    ------
+    ValueError
+        If the last dimension of `a` is not the same size as
+        the second-to-last dimension of `b`.
+
+        If scalar value is passed.
+
+    See Also
+    --------
+    vdot : Complex-conjugating dot product.
+    tensordot : Sum products over arbitrary axes.
+    dot : alternative matrix product with different broadcasting rules.
+
+    Notes
+    -----
+    The matmul function implements the semantics of the `@` operator introduced
+    in Python 3.5 following PEP465.
+
+    Examples
+    --------
+    For 2-D arrays it is the matrix product:
+
+    >>> import maxframe.tensor as mt
+
+    >>> a = [[1, 0], [0, 1]]
+    >>> b = [[4, 1], [2, 2]]
+    >>> mt.matmul(a, b).execute()
+    array([[4, 1],
+           [2, 2]])
+
+    For 2-D mixed with 1-D, the result is the usual.
+
+    >>> a = [[1, 0], [0, 1]]
+    >>> b = [1, 2]
+    >>> mt.matmul(a, b).execute()
+    array([1, 2])
+    >>> mt.matmul(b, a).execute()
+    array([1, 2])
+
+
+    Broadcasting is conventional for stacks of arrays
+
+    >>> a = mt.arange(2*2*4).reshape((2,2,4))
+    >>> b = mt.arange(2*2*4).reshape((2,4,2))
+    >>> mt.matmul(a,b).shape
+    (2, 2, 2)
+    >>> mt.matmul(a,b)[0,1,1].execute()
+    98
+    >>> mt.sum(a[0,1,:] * b[0,:,1]).execute()
+    98
+
+    Vector, vector returns the scalar inner product, but neither argument
+    is complex-conjugated:
+
+    >>> mt.matmul([2j, 3j], [2j, 3j]).execute()
+    (-13+0j)
+
+    Scalar multiplication raises an error.
+
+    >>> mt.matmul([1,2], 3)
+    Traceback (most recent call last):
+    ...
+    ValueError: Scalar operands are not allowed, use '*' instead
+    """
+    a = astensor(a)
+    b = astensor(b)
+
+    sparse = sparse if sparse is not None else a.issparse() and b.issparse()
+    op = TensorMatmul(dtype=np.promote_types(a.dtype, b.dtype), sparse=sparse, **kw)
+    return op(a, b, out=out)

maxframe/tensor/linalg/matrix_norm.py

@@ -0,0 +1,75 @@
+# 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 .norm import norm
+
+
+def matrix_norm(x, *, keepdims=False, ord="fro"):
+    """
+    Computes the matrix norm of a matrix (or a stack of matrices) ``x``.
+
+    This function is Array API compatible.
+
+    Parameters
+    ----------
+    x : array_like
+        Input array having shape (..., M, N) and whose two innermost
+        dimensions form ``MxN`` matrices.
+    keepdims : bool, optional
+        If this is set to True, the axes which are normed over are left in
+        the result as dimensions with size one. Default: False.
+    ord : {1, -1, 2, -2, inf, -inf, 'fro', 'nuc'}, optional
+        The order of the norm. For details see the table under ``Notes``
+        in `numpy.linalg.norm`.
+
+    See Also
+    --------
+    numpy.linalg.norm : Generic norm function
+
+    Examples
+    --------
+    >>> import maxframe.tensor as mt
+    >>> from maxframe.tensor import linalg as LA
+    >>> a = mt.arange(9) - 4
+    >>> a.execute()
+    array([-4, -3, -2, ...,  2,  3,  4])
+    >>> b = a.reshape((3, 3))
+    >>> b.execute()
+    array([[-4, -3, -2],
+           [-1,  0,  1],
+           [ 2,  3,  4]])
+
+    >>> LA.matrix_norm(b).execute()
+    7.745966692414834
+    >>> LA.matrix_norm(b, ord='fro').execute()
+    7.745966692414834
+    >>> LA.matrix_norm(b, ord=np.inf).execute()
+    9.0
+    >>> LA.matrix_norm(b, ord=-np.inf).execute()
+    2.0
+
+    >>> LA.matrix_norm(b, ord=1).execute()
+    7.0
+    >>> LA.matrix_norm(b, ord=-1).execute()
+    6.0
+    >>> LA.matrix_norm(b, ord=2).execute()
+    7.3484692283495345
+    >>> LA.matrix_norm(b, ord=-2).execute()
+    1.8570331885190563e-016 # may vary
+
+    """
+    from ..datasource.array import asarray
+
+    x = asarray(x)
+    return norm(x, axis=(-2, -1), keepdims=keepdims, ord=ord)