scipy 1.15.2__cp312-cp312-macosx_14_0_arm64.whl → 1.16.0__cp312-cp312-macosx_14_0_arm64.whl

scipy/sparse/__init__.py

@@ -32,6 +32,9 @@ SciPy 2-D sparse array package for numeric data.
    - Sparse arrays use array style *slicing* operations, returning scalars,
      1D, or 2D sparse arrays. If you need 2D results, use an appropriate index.
      E.g. ``A[:, i, None]`` or ``A[:, [i]]``.
+   - All index arrays for a given sparse array should be of same dtype.
+     For example, for CSR format, ``indices`` and ``indptr`` should have
+     the same dtype. For COO, each array in `coords` should have same dtype.
 
    The construction utilities (`eye`, `kron`, `random`, `diags`, etc.)
    have appropriate replacements (see :ref:`sparse-construction-functions`).
@@ -253,7 +256,7 @@ is the same:
 Now we can compute norm of the error with:
 
 >>> err = norm(x-x_)
->>> err < 1e-10
+>>> err < 1e-9
 True
 
 It should be small :)
@@ -296,6 +299,7 @@ sorted indices are required (e.g., when passing data to other libraries).
 # Nathan Bell, and Jake Vanderplas.
 
 import warnings as _warnings
+import importlib as _importlib
 
 from ._base import *
 from ._csr import *
@@ -311,8 +315,6 @@ from ._matrix import spmatrix
 from ._matrix_io import *
 from ._sputils import get_index_dtype, safely_cast_index_arrays
 
-# For backward compatibility with v0.19.
-from . import csgraph
 
 # Deprecated namespaces, to be removed in v2.0.0
 from . import (
@@ -320,12 +322,29 @@ from . import (
     lil, sparsetools, sputils
 )
 
-__all__ = [s for s in dir() if not s.startswith('_')]
+_submodules = ["csgraph", "linalg"]
+
+__all__ = [s for s in dir() if not s.startswith('_')] + _submodules
 
 # Filter PendingDeprecationWarning for np.matrix introduced with numpy 1.15
 msg = 'the matrix subclass is not the recommended way'
 _warnings.filterwarnings('ignore', message=msg)
 
+def __dir__():
+   return __all__
+
+
+def __getattr__(name):
+    if name in _submodules:
+        return _importlib.import_module(f'scipy.sparse.{name}')
+    else:
+        try:
+            return globals()[name]
+        except KeyError:
+            raise AttributeError(
+                f"Module 'scipy.sparse' has no attribute '{name}'"
+            )
+
 from scipy._lib._testutils import PytestTester
 test = PytestTester(__name__)
 del PytestTester

scipy/sparse/_base.py

@@ -1,10 +1,14 @@
 """Base class for sparse matrices"""
 
+from warnings import warn
+import math
 import numpy as np
+import operator
 
 from ._sputils import (asmatrix, check_reshape_kwargs, check_shape,
-                       get_sum_dtype, isdense, isscalarlike,
-                       matrix, validateaxis, getdtype)
+                       get_sum_dtype, isdense, isscalarlike, _todata,
+                       matrix, validateaxis, getdtype, is_pydata_spmatrix)
+from scipy._lib._sparse import SparseABC, issparse
 
 from ._matrix import spmatrix
 
@@ -13,6 +17,7 @@ __all__ = ['isspmatrix', 'issparse', 'sparray',
 
 
 class SparseWarning(Warning):
+    """General warning for :mod:`scipy.sparse`."""
     pass
 
 
@@ -21,6 +26,9 @@ class SparseFormatWarning(SparseWarning):
 
 
 class SparseEfficiencyWarning(SparseWarning):
+    """The warning emitted when the operation is
+    inefficient for sparse matrices.
+    """
     pass
 
 
@@ -58,7 +66,23 @@ _ufuncs_with_fixed_point_at_zero = frozenset([
 MAXPRINT = 50
 
 
-class _spbase:
+# helper dicts to manipulate comparison operators
+# We negate operators (with warning) when all implicit values would be True
+op_neg = {operator.eq: operator.ne, operator.ne: operator.eq,
+          operator.lt: operator.ge, operator.ge: operator.lt,
+          operator.gt: operator.le, operator.le: operator.gt}
+
+
+# We use symbolic version of operators in warning messages.
+op_sym = {operator.eq: '==', operator.ge: '>=', operator.le: '<=',
+          operator.ne: '!=', operator.gt: '>', operator.lt: '<'}
+
+
+# `_spbase` is a subclass of `SparseABC`.
+# This allows other submodules to check for instances of sparse subclasses
+# via `scipy._lib._sparse.issparse`, without introducing
+# an import dependency on `scipy.sparse`.
+class _spbase(SparseABC):
     """ This class provides a base class for all sparse arrays.  It
     cannot be instantiated.  Most of the work is provided by subclasses.
     """
@@ -133,7 +157,7 @@ class _spbase:
 
         Parameters
         ----------
-        shape : length-2 tuple of ints
+        shape : tuple of ints
             The new shape should be compatible with the original shape.
         order : {'C', 'F'}, optional
             Read the elements using this index order. 'C' means to read and
@@ -465,18 +489,94 @@ class _spbase:
     ####################################################################
 
     def multiply(self, other):
-        """Point-wise multiplication by another array/matrix."""
+        """Element-wise multiplication by another array/matrix."""
         if isscalarlike(other):
             return self._mul_scalar(other)
-        return self.tocsr().multiply(other)
+
+        if self.ndim < 3:
+            return self.tocsr()._multiply_2d_with_broadcasting(other)
+
+        if not (issparse(other) or isdense(other)):
+            # If it's a list or whatever, treat it like an array
+            other_a = np.asanyarray(other)
+            if other_a.ndim == 0 and other_a.dtype == np.object_:
+                # numpy creates a 0d object array if all else fails.
+                # Not interpretable as an array; return NotImplemented so
+                # other's __rmul__ can kick in if that's implemented.
+                return NotImplemented
+            # Allow custom sparse class indicated by attr sparse gh-6520
+            try:
+                other.shape
+            except AttributeError:
+                other = other_a
+
+        if self.shape != other.shape:
+            raise ValueError("inconsistent shapes: >2D multiply() does not yet "
+                             "support broadcasting")
+
+        # self is >2D so must be COO
+        if isdense(other):
+            data = np.multiply(self.data, other[self.coords])
+            result = self.copy()
+            result.data = data.view(np.ndarray).ravel()
+            return result
+
+        elif issparse(other):
+            csr_self = self.reshape(1, -1).tocsr()
+            csr_other = other.reshape(1, -1).tocsr()
+            return csr_self._binopt(csr_other, '_elmul_').reshape(self.shape)
+
+        else:
+            # Not scalar, dense or sparse. Return NotImplemented so that
+            # other's __rmul__ can kick in if that's implemented.
+            return NotImplemented
+
+    def _maximum_minimum(self, other, np_op):
+        if not (issparse(other) or isdense(other) or isscalarlike(other)):
+            # If it's a list or whatever, treat it like an array
+            other_a = np.asanyarray(other)
+            if other_a.ndim == 0 and other_a.dtype == np.object_:
+                # numpy creates a 0d object array if all else fails.
+                # We don't know how to handle it either.
+                raise NotImplementedError('maximum or minimum with an unrecognized '
+                                          'array type is not supported')
+            # Allow custom sparse class indicated by attr sparse gh-6520
+            try:
+                other.shape
+            except AttributeError:
+                other = other_a
+
+        if isscalarlike(other):
+            if np_op(0, other):
+                pos_neg = 'positive' if np_op == np.maximum else 'negative'
+                warn(f"Taking {np_op.__name__} with a {pos_neg} number results in a"
+                     " dense matrix.", SparseEfficiencyWarning, stacklevel=3)
+                return self.__class__(np_op(self.toarray(), other))
+            else:
+                csr_self = (self if self.ndim < 3 else self.reshape(1, -1)).tocsr()
+                result = csr_self._scalar_binopt(other, np_op)
+                return result if self.ndim < 3 else result.tocoo().reshape(self.shape)
+        elif isdense(other):
+            return np_op(self.todense(), other)
+        elif issparse(other):
+            if self.shape != other.shape:
+                raise ValueError(f"inconsistent shapes {self.shape=} {other.shape=}")
+            if self.ndim < 3:  # shape is same so other.ndim < 3
+                return self.tocsr()._binopt(other, f'_{np_op.__name__}_')
+            csr_self = self.reshape(1, -1).tocsr()
+            csr_other = other.reshape(1, -1).tocsr()
+            result = csr_self._binopt(csr_other, f'_{np_op.__name__}_')
+            return result.tocoo().reshape(self.shape)
+        else:
+            raise ValueError("Operands not compatible.")
 
     def maximum(self, other):
         """Element-wise maximum between this and another array/matrix."""
-        return self.tocsr().maximum(other)
+        return self._maximum_minimum(other, np.maximum)
 
     def minimum(self, other):
         """Element-wise minimum between this and another array/matrix."""
-        return self.tocsr().minimum(other)
+        return self._maximum_minimum(other, np.minimum)
 
     def dot(self, other):
         """Ordinary dot product
@@ -506,23 +606,96 @@ class _spbase:
         else:
             return self.tocsr()._broadcast_to(shape, copy)
 
+    def _comparison(self, other, op):
+        # We convert to CSR format and use methods _binopt or _scalar_binopt
+        # If ndim>2 we reshape to 2D, compare and then reshape back to nD
+        if not (issparse(other) or isdense(other) or isscalarlike(other)):
+            if is_pydata_spmatrix(other):
+                # cannot compare with pydata other, but it might compare with us.
+                return NotImplemented
+            # If it's a list or whatever, treat it like an array
+            other_a = np.asanyarray(other)
+            if other_a.ndim == 0 and other_a.dtype == np.object_:
+                # numpy creates a 0d object array if all else fails.
+                # Not interpretable as an array; return NotImplemented so
+                # other's dunder methods can kick in if implemented.
+                return NotImplemented
+            # Allow custom sparse class indicated by attr sparse gh-6520
+            try:
+                other.shape
+            except AttributeError:
+                other = other_a
+
+        if isscalarlike(other):
+            if not op(0, other):
+                if np.isnan(other):  # op is not `ne`, so results are all False.
+                    return self.__class__(self.shape, dtype=np.bool_)
+                else:
+                    csr_self = (self if self.ndim < 3 else self.reshape(1, -1)).tocsr()
+                    res = csr_self._scalar_binopt(other, op)
+                    return res if self.ndim < 3 else res.tocoo().reshape(self.shape)
+            else:
+                warn(f"Comparing a sparse matrix with {other} using {op_sym[op]} "
+                     f"is inefficient. Try using {op_sym[op_neg[op]]} instead.",
+                     SparseEfficiencyWarning, stacklevel=3)
+                if np.isnan(other):
+                    # op is `ne` cuz op(0, other) and isnan(other). Return all True.
+                    return self.__class__(np.ones(self.shape, dtype=np.bool_))
+
+                # op is eq, le, or ge. Use negated op and then negate.
+                csr_self = (self if self.ndim < 3 else self.reshape(1, -1)).tocsr()
+                inv = csr_self._scalar_binopt(other, op_neg[op])
+                all_true = csr_self.__class__(np.ones(csr_self.shape, dtype=np.bool_))
+                result = all_true - inv
+                return result if self.ndim < 3 else result.tocoo().reshape(self.shape)
+
+        elif isdense(other):
+            return op(self.todense(), other)
+
+        elif issparse(other):
+            # TODO sparse broadcasting
+            if self.shape != other.shape:
+                # eq and ne return True or False instead of an array when the shapes
+                # don't match. Numpy doesn't do this. Is this what we want?
+                if op in (operator.eq, operator.ne):
+                    return op is operator.ne
+                raise ValueError("inconsistent shape")
+
+            csr_self = (self if self.ndim < 3 else self.reshape(1, -1)).tocsr()
+            csr_other = (other if other.ndim < 3 else other.reshape(1, -1)).tocsr()
+            if not op(0, 0):
+                result = csr_self._binopt(csr_other, f'_{op.__name__}_')
+                return result if self.ndim < 3 else result.tocoo().reshape(self.shape)
+            else:
+                # result will not be sparse. Use negated op and then negate.
+                warn(f"Comparing two sparse matrices using {op_sym[op]} "
+                     f"is inefficient. Try using {op_sym[op_neg[op]]} instead.",
+                     SparseEfficiencyWarning, stacklevel=3)
+                inv = csr_self._binopt(csr_other, f'_{op_neg[op].__name__}_')
+                all_true = csr_self.__class__(np.ones(csr_self.shape, dtype=np.bool_))
+                result = all_true - inv
+                return result if self.ndim < 3 else result.tocoo().reshape(self.shape)
+        else:
+            # cannot compare with other, but it might compare with us.
+            return NotImplemented
+
     def __eq__(self, other):
-        return self.tocsr().__eq__(other)
+        return self._comparison(other, operator.eq)
 
     def __ne__(self, other):
-        return self.tocsr().__ne__(other)
+        return self._comparison(other, operator.ne)
 
     def __lt__(self, other):
-        return self.tocsr().__lt__(other)
+        return self._comparison(other, operator.lt)
 
     def __gt__(self, other):
-        return self.tocsr().__gt__(other)
+        return self._comparison(other, operator.gt)
 
     def __le__(self, other):
-        return self.tocsr().__le__(other)
+        return self._comparison(other, operator.le)
 
     def __ge__(self, other):
-        return self.tocsr().__ge__(other)
+        return self._comparison(other, operator.ge)
 
     def __abs__(self):
         return abs(self.tocsr())
@@ -637,12 +810,12 @@ class _spbase:
 
         # If it's a list or whatever, treat it like an array
         other_a = np.asanyarray(other)
-
         if other_a.ndim == 0 and other_a.dtype == np.object_:
+            # numpy creates a 0d object array if all else fails.
             # Not interpretable as an array; return NotImplemented so that
             # other's __rmatmul__ can kick in if that's implemented.
             return NotImplemented
-
+        # Allow custom sparse class indicated by attr sparse gh-6520
         try:
             other.shape
         except AttributeError:
@@ -742,6 +915,21 @@ class _spbase:
     ####################
 
     def _divide(self, other, true_divide=False, rdivide=False):
+        # Do we need to continue to support true_divide and divide?
+        if not (issparse(other) or isdense(other) or isscalarlike(other)):
+            # If it's a list or whatever, treat it like an array
+            other_a = np.asanyarray(other)
+            if other_a.ndim == 0 and other_a.dtype == np.object_:
+                # numpy creates a 0d object array if all else fails.
+                # Not interpretable as an array; return NotImplemented so that
+                # other's __rdiv__ can kick in if that's implemented.
+                return NotImplemented
+            # Allow custom sparse class indicated by attr sparse gh-6520
+            try:
+                other.shape
+            except AttributeError:
+                other = other_a
+
         if isscalarlike(other):
             if rdivide:
                 if true_divide:
@@ -777,12 +965,16 @@ class _spbase:
             if rdivide:
                 return other._divide(self, true_divide, rdivide=False)
 
-            self_csr = self.tocsr()
+            csr_self = (self if self.ndim < 3 else self.reshape(1, -1)).tocsr()
+            csr_other = (other if self.ndim < 3 else other.reshape(1, -1)).tocsr()
             if true_divide and np.can_cast(self.dtype, np.float64):
-                return self_csr.astype(np.float64)._divide_sparse(other)
+                result = csr_self.astype(np.float64)._divide_sparse(csr_other)
             else:
-                return self_csr._divide_sparse(other)
+                result = csr_self._divide_sparse(csr_other)
+            return result if self.ndim < 3 else result.reshape(self.shape)
         else:
+            # not scalar, dense or sparse. Return NotImplemented so
+            # other's __rdiv__ can kick in if that's implemented.
             return NotImplemented
 
     def __truediv__(self, other):
@@ -1133,57 +1325,44 @@ class _spbase:
         numpy.matrix.sum : NumPy's implementation of 'sum' for matrices
 
         """
-        validateaxis(axis)
+        axis = validateaxis(axis, ndim=self.ndim)
 
         # Mimic numpy's casting.
         res_dtype = get_sum_dtype(self.dtype)
 
-        if self.ndim == 1:
-            if axis not in (None, -1, 0):
-                raise ValueError("axis must be None, -1 or 0")
-            ret = (self @ np.ones(self.shape, dtype=res_dtype)).astype(dtype)
-
-            if out is not None:
-                if any(dim != 1 for dim in out.shape):
-                    raise ValueError("dimensions do not match")
-                out[...] = ret
-            return ret
-
-        # We use multiplication by a matrix of ones to achieve this.
-        # For some sparse array formats more efficient methods are
-        # possible -- these should override this function.
-        M, N = self.shape
-
+        # Note: all valid 1D axis values are canonically `None`.
         if axis is None:
-            # sum over rows and columns
-            return (
-                self @ self._ascontainer(np.ones((N, 1), dtype=res_dtype))
-            ).sum(dtype=dtype, out=out)
-
-        if axis < 0:
-            axis += 2
-
-        # axis = 0 or 1 now
-        if axis == 0:
-            # sum over columns
-            ret = self._ascontainer(
-                np.ones((1, M), dtype=res_dtype)
-            ) @ self
+            if self.nnz == 0:
+                return np.sum(self._ascontainer([0]), dtype=dtype or res_dtype, out=out)
+            return np.sum(self._ascontainer(_todata(self)), dtype=dtype, out=out)
+        elif isspmatrix(self):
+            # Ensure spmatrix sums stay 2D
+            new_shape = (1, self.shape[1]) if axis == (0,) else (self.shape[0], 1)
         else:
-            # sum over rows
-            ret = self @ self._ascontainer(
-                np.ones((N, 1), dtype=res_dtype)
-            )
+            new_shape = tuple(self.shape[i] for i in range(self.ndim) if i not in axis)
 
-        if out is not None:
-            if isinstance(self, sparray):
-                ret_shape = ret.shape[:axis] + ret.shape[axis + 1:]
-            else:
-                ret_shape = ret.shape
-            if out.shape != ret_shape:
-                raise ValueError("dimensions do not match")
+        if out is None:
+            # create out array with desired dtype
+            out = self._ascontainer(np.zeros(new_shape, dtype=dtype or res_dtype))
+        else:
+            if out.shape != new_shape:
+                raise ValueError("out dimensions do not match shape")
 
-        return ret.sum(axis=axis, dtype=dtype, out=out)
+        if self.ndim > 2:
+            return self._sum_nd(axis, res_dtype, out)
+
+        # We use multiplication by a matrix of ones to sum.
+        # For some sparse array formats more efficient methods are
+        # possible -- these should override this function.
+        if axis == (0,):
+            ones = self._ascontainer(np.ones((1, self.shape[0]), dtype=res_dtype))
+            # sets dtype while loading into out
+            out[...] = (ones @ self).reshape(new_shape)
+        else:  # axis == (1,)
+            ones = self._ascontainer(np.ones((self.shape[1], 1), dtype=res_dtype))
+            # sets dtype while loading into out
+            out[...] = (self @ ones).reshape(new_shape)
+        return out
 
     def mean(self, axis=None, dtype=None, out=None):
         """
@@ -1222,43 +1401,24 @@ class _spbase:
         numpy.matrix.mean : NumPy's implementation of 'mean' for matrices
 
         """
-        validateaxis(axis)
+        axis = validateaxis(axis, ndim=self.ndim)
 
-        res_dtype = self.dtype.type
         integral = (np.issubdtype(self.dtype, np.integer) or
                     np.issubdtype(self.dtype, np.bool_))
 
-        # output dtype
-        if dtype is None:
-            if integral:
-                res_dtype = np.float64
-        else:
-            res_dtype = np.dtype(dtype).type
-
         # intermediate dtype for summation
-        inter_dtype = np.float64 if integral else res_dtype
+        inter_dtype = np.float64 if integral else self.dtype
         inter_self = self.astype(inter_dtype)
 
-        if self.ndim == 1:
-            if axis not in (None, -1, 0):
-                raise ValueError("axis must be None, -1 or 0")
-            res = inter_self / self.shape[-1]
-            return res.sum(dtype=res_dtype, out=out)
-
         if axis is None:
-            return (inter_self / (self.shape[0] * self.shape[1]))\
-                .sum(dtype=res_dtype, out=out)
-
-        if axis < 0:
-            axis += 2
-
-        # axis = 0 or 1 now
-        if axis == 0:
-            return (inter_self * (1.0 / self.shape[0])).sum(
-                axis=0, dtype=res_dtype, out=out)
+            denom = math.prod(self.shape)
         else:
-            return (inter_self * (1.0 / self.shape[1])).sum(
-                axis=1, dtype=res_dtype, out=out)
+            denom = math.prod(self.shape[ax] for ax in axis)
+        res = (inter_self * (1.0 / denom)).sum(axis=axis, dtype=inter_dtype, out=out)
+        if dtype is not None and out is None:
+            return res.astype(dtype, copy=False)
+        return res
+
 
     def diagonal(self, k=0):
         """Returns the kth diagonal of the array/matrix.
@@ -1394,42 +1554,31 @@ class _spbase:
 class sparray:
     """A namespace class to separate sparray from spmatrix"""
 
+    @classmethod
+    def __class_getitem__(cls, arg, /):
+        """
+        Return a parametrized wrapper around the `~scipy.sparse.sparray` type.
 
-sparray.__doc__ = _spbase.__doc__
-
+        .. versionadded:: 1.16.0
 
-def issparse(x):
-    """Is `x` of a sparse array or sparse matrix type?
+        Returns
+        -------
+        alias : types.GenericAlias
+            A parametrized `~scipy.sparse.sparray` type.
 
-    Parameters
-    ----------
-    x
-        object to check for being a sparse array or sparse matrix
+        Examples
+        --------
+        >>> import numpy as np
+        >>> from scipy.sparse import coo_array
 
-    Returns
-    -------
-    bool
-        True if `x` is a sparse array or a sparse matrix, False otherwise
+        >>> coo_array[np.int8, tuple[int]]
+        scipy.sparse._coo.coo_array[numpy.int8, tuple[int]]
+        """
+        from types import GenericAlias
+        return GenericAlias(cls, arg)
 
-    Notes
-    -----
-    Use `isinstance(x, sp.sparse.sparray)` to check between an array or matrix.
-    Use `a.format` to check the sparse format, e.g. `a.format == 'csr'`.
 
-    Examples
-    --------
-    >>> import numpy as np
-    >>> from scipy.sparse import csr_array, csr_matrix, issparse
-    >>> issparse(csr_matrix([[5]]))
-    True
-    >>> issparse(csr_array([[5]]))
-    True
-    >>> issparse(np.array([[5]]))
-    False
-    >>> issparse(5)
-    False
-    """
-    return isinstance(x, _spbase)
+sparray.__doc__ = _spbase.__doc__
 
 
 def isspmatrix(x):

scipy/sparse/_bsr.py

@@ -172,8 +172,9 @@ class _bsr_base(_cs_matrix, _minmax_mixin):
 
         # check index pointer
         if (len(self.indptr) != M//R + 1):
-            raise ValueError("index pointer size (%d) should be (%d)" %
-                                (len(self.indptr), M//R + 1))
+            raise ValueError(
+                f"index pointer size ({len(self.indptr)}) should be ({M//R + 1})"
+            )
         if (self.indptr[0] != 0):
             raise ValueError("index pointer should start with 0")
 
@@ -190,8 +191,10 @@ class _bsr_base(_cs_matrix, _minmax_mixin):
             # check format validity (more expensive)
             if self.nnz > 0:
                 if self.indices.max() >= N//C:
-                    raise ValueError("column index values must be < %d (now max %d)"
-                                     % (N//C, self.indices.max()))
+                    raise ValueError(
+                        f"column index values must be < {N//C}"
+                        f" (now max {self.indices.max()})"
+                    )
                 if self.indices.min() < 0:
                     raise ValueError("column index values must be >= 0")
                 if np.diff(self.indptr).min() < 0: