python-graphblas 2023.12.0__py3-none-any.whl → 2024.2.0__py3-none-any.whl

graphblas/agg/__init__.py

@@ -73,7 +73,8 @@ Custom recipes (specific to SuiteSparse:GraphBLAS):
 #   - bxnor monoid: even bits
 #   - bnor monoid: odd bits
 """
-# All items are dynamically added by classes in core/agg.py
+
+# All items are dynamically added by classes in core/operator/agg.py
 # This module acts as a container of Aggregator instances
 _deprecated = {}
 

graphblas/binary/numpy.py

@@ -5,6 +5,7 @@ See list of numpy ufuncs supported by numpy here:
 https://numba.readthedocs.io/en/stable/reference/numpysupported.html#math-operations
 
 """
+
 import numpy as _np
 
 from .. import _STANDARD_OPERATOR_NAMES

graphblas/core/automethods.py

@@ -7,6 +7,7 @@ To automatically create the functions, run:
 $ python -m graphblas.core.automethods
 
 """
+
 from .. import config
 
 
@@ -281,10 +282,6 @@ def to_edgelist(self):
     return self._get_value("to_edgelist")
 
 
-def to_values(self):
-    return self._get_value("to_values")
-
-
 def value(self):
     return self._get_value("value")
 
@@ -398,7 +395,6 @@ def _main():
         "ss",
         "to_coo",
         "to_dense",
-        "to_values",
     }
     vector = {
         "_as_matrix",

graphblas/core/dtypes.py

@@ -375,8 +375,7 @@ def lookup_dtype(key, value=None):
 
 
 def unify(type1, type2, *, is_left_scalar=False, is_right_scalar=False):
-    """
-    Returns a type that can hold both type1 and type2.
+    """Returns a type that can hold both type1 and type2.
 
     For example:
     unify(INT32, INT64) -> INT64

graphblas/core/expr.py

@@ -147,13 +147,13 @@ class IndexerResolver:
         return self.indices[0]._py_index()
 
     def parse_indices(self, indices, shape):
-        """
-        Returns
+        """Returns
         -------
             [(rows, rowsize), (cols, colsize)] for Matrix
             [(idx, idx_size)] for Vector
 
         Within each tuple, if the index is of type int, the size will be None
+
         """
         if len(shape) == 1:
             if type(indices) is tuple:
@@ -312,8 +312,8 @@ class AmbiguousAssignOrExtract:
         Updater(self.parent, opts=opts)._setitem(self.resolved_indexes, expr, is_submask=False)
 
     def new(self, dtype=None, *, mask=None, input_mask=None, name=None, **opts):
-        """
-        Force extraction of the indexes into a new object
+        """Force extraction of the indexes into a new object.
+
         dtype and mask are the only controllable parameters.
         """
         if input_mask is not None:

graphblas/core/infix.py

@@ -236,7 +236,6 @@ class VectorInfixExpr(InfixExprBase):
     to_coo = wrapdoc(Vector.to_coo)(property(automethods.to_coo))
     to_dense = wrapdoc(Vector.to_dense)(property(automethods.to_dense))
     to_dict = wrapdoc(Vector.to_dict)(property(automethods.to_dict))
-    to_values = wrapdoc(Vector.to_values)(property(automethods.to_values))
     vxm = wrapdoc(Vector.vxm)(property(automethods.vxm))
     wait = wrapdoc(Vector.wait)(property(automethods.wait))
     # These raise exceptions
@@ -396,7 +395,6 @@ class MatrixInfixExpr(InfixExprBase):
     to_dense = wrapdoc(Matrix.to_dense)(property(automethods.to_dense))
     to_dicts = wrapdoc(Matrix.to_dicts)(property(automethods.to_dicts))
     to_edgelist = wrapdoc(Matrix.to_edgelist)(property(automethods.to_edgelist))
-    to_values = wrapdoc(Matrix.to_values)(property(automethods.to_values))
     wait = wrapdoc(Matrix.wait)(property(automethods.wait))
     # These raise exceptions
     __array__ = Matrix.__array__

graphblas/core/matrix.py

@@ -1,5 +1,4 @@
 import itertools
-import warnings
 from collections.abc import Sequence
 
 import numpy as np
@@ -178,6 +177,7 @@ class Matrix(BaseType):
         Number of columns.
     name : str, optional
         Name to give the Matrix. This will be displayed in the ``__repr__``.
+
     """
 
     __slots__ = "_nrows", "_ncols", "_parent", "ss"
@@ -297,6 +297,7 @@ class Matrix(BaseType):
         Examples
         --------
             >>> del M[1, 5]
+
         """
         del Updater(self, opts=opts)[keys]
 
@@ -311,6 +312,7 @@ class Matrix(BaseType):
         .. code-block:: python
 
             subM = M[[1, 3, 5], :].new()
+
         """
         resolved_indexes = IndexerResolver(self, keys)
         shape = resolved_indexes.shape
@@ -332,6 +334,7 @@ class Matrix(BaseType):
         .. code-block:: python
 
             M[0, 0:3] = 17
+
         """
         Updater(self, opts=opts)[keys] = expr
 
@@ -343,6 +346,7 @@ class Matrix(BaseType):
         .. code-block:: python
 
             (10, 15) in M
+
         """
         extractor = self[index]
         if not extractor._is_scalar:
@@ -382,6 +386,7 @@ class Matrix(BaseType):
         See Also
         --------
         :meth:`isclose` : For equality check of floating point dtypes
+
         """
         other = self._expect_type(
             other, (Matrix, TransposedMatrix), within="isequal", argname="other"
@@ -428,6 +433,7 @@ class Matrix(BaseType):
         -------
         bool
             Whether all values of the Matrix are close to the values in ``other``.
+
         """
         other = self._expect_type(
             other, (Matrix, TransposedMatrix), within="isclose", argname="other"
@@ -515,42 +521,6 @@ class Matrix(BaseType):
         self._nrows = nrows.value
         self._ncols = ncols.value
 
-    def to_values(self, dtype=None, *, rows=True, columns=True, values=True, sort=True):
-        """Extract the indices and values as a 3-tuple of numpy arrays
-        corresponding to the COO format of the Matrix.
-
-        .. deprecated:: 2022.11.0
-            ``Matrix.to_values`` will be removed in a future release.
-            Use ``Matrix.to_coo`` instead. Will be removed in version 2023.9.0 or later
-
-        Parameters
-        ----------
-        dtype :
-            Requested dtype for the output values array.
-        rows : bool, default=True
-            Whether to return rows; will return ``None`` for rows if ``False``
-        columns : bool, default=True
-            Whether to return columns; will return ``None`` for columns if ``False``
-        values : bool, default=True
-            Whether to return values; will return ``None`` for values if ``False``
-        sort : bool, default=True
-            Whether to require sorted indices.
-            If internally stored rowwise, the sorting will be first by rows, then by column.
-            If internally stored columnwise, the sorting will be first by column, then by row.
-
-        Returns
-        -------
-        np.ndarray[dtype=uint64] : Rows
-        np.ndarray[dtype=uint64] : Columns
-        np.ndarray : Values
-        """
-        warnings.warn(
-            "`Matrix.to_values(...)` is deprecated; please use `Matrix.to_coo(...)` instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return self.to_coo(dtype, rows=rows, columns=columns, values=values, sort=sort)
-
     def to_coo(self, dtype=None, *, rows=True, columns=True, values=True, sort=True):
         """Extract the indices and values as a 3-tuple of numpy arrays
         corresponding to the COO format of the Matrix.
@@ -581,6 +551,7 @@ class Matrix(BaseType):
         np.ndarray[dtype=uint64] : Rows
         np.ndarray[dtype=uint64] : Columns
         np.ndarray : Values
+
         """
         if sort and backend == "suitesparse":
             self.wait()  # sort in SS
@@ -647,6 +618,7 @@ class Matrix(BaseType):
         -------
         np.ndarray[dtype=uint64] : Edgelist
         np.ndarray : Values
+
         """
         rows, columns, values = self.to_coo(dtype, values=values, sort=sort)
         return (np.column_stack([rows, columns]), values)
@@ -727,6 +699,7 @@ class Matrix(BaseType):
         Returns
         -------
         Matrix
+
         """
         if dtype is not None or mask is not None or clear:
             if dtype is None:
@@ -758,6 +731,7 @@ class Matrix(BaseType):
         Returns
         -------
         :class:`~graphblas.Vector`
+
         """
         if backend == "suitesparse":
             from ..ss._core import diag
@@ -801,6 +775,7 @@ class Matrix(BaseType):
         Use wait to force completion of the Matrix.
 
         Has no effect in `blocking mode <../user_guide/init.html#graphblas-modes>`__.
+
         """
         how = how.lower()
         if how == "materialize":
@@ -827,6 +802,7 @@ class Matrix(BaseType):
         Returns
         -------
         Python scalar
+
         """
         expr = self[row, col]
         if expr._is_scalar:
@@ -837,61 +813,6 @@ class Matrix(BaseType):
             "Indices should get a single element, which will be extracted as a Python scalar."
         )
 
-    @classmethod
-    def from_values(
-        cls,
-        rows,
-        columns,
-        values,
-        dtype=None,
-        *,
-        nrows=None,
-        ncols=None,
-        dup_op=None,
-        name=None,
-    ):
-        """Create a new Matrix from row and column indices and values.
-
-        .. deprecated:: 2022.11.0
-            ``Matrix.from_values`` will be removed in a future release.
-            Use ``Matrix.from_coo`` instead. Will be removed in version 2023.9.0 or later
-
-        Parameters
-        ----------
-        rows : list or np.ndarray
-            Row indices.
-        columns : list or np.ndarray
-            Column indices.
-        values : list or np.ndarray or scalar
-            List of values. If a scalar is provided, all values will be set to this single value.
-        dtype :
-            Data type of the Matrix. If not provided, the values will be inspected
-            to choose an appropriate dtype.
-        nrows : int, optional
-            Number of rows in the Matrix. If not provided, ``nrows`` is computed
-            from the maximum row index found in ``rows``.
-        ncols : int, optional
-            Number of columns in the Matrix. If not provided, ``ncols`` is computed
-            from the maximum column index found in ``columns``.
-        dup_op : :class:`~graphblas.core.operator.BinaryOp`, optional
-            Function used to combine values if duplicate indices are found.
-            Leaving ``dup_op=None`` will raise an error if duplicates are found.
-        name : str, optional
-            Name to give the Matrix.
-
-        Returns
-        -------
-        Matrix
-        """
-        warnings.warn(
-            "`Matrix.from_values(...)` is deprecated; please use `Matrix.from_coo(...)` instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return cls.from_coo(
-            rows, columns, values, dtype, nrows=nrows, ncols=ncols, dup_op=dup_op, name=name
-        )
-
     @classmethod
     def from_coo(
         cls,
@@ -939,6 +860,7 @@ class Matrix(BaseType):
         Returns
         -------
         Matrix
+
         """
         rows = ints_to_numpy_buffer(rows, np.uint64, name="row indices")
         columns = ints_to_numpy_buffer(columns, np.uint64, name="column indices")
@@ -1018,6 +940,7 @@ class Matrix(BaseType):
         Returns
         -------
         Matrix
+
         """
         edgelist_values = None
         if isinstance(edgelist, np.ndarray):
@@ -1187,6 +1110,7 @@ class Matrix(BaseType):
         to_csr
         Matrix.ss.import_csr
         io.from_scipy_sparse
+
         """
         return cls._from_csx(_CSR_FORMAT, indptr, col_indices, values, dtype, ncols, nrows, name)
 
@@ -1234,6 +1158,7 @@ class Matrix(BaseType):
         to_csc
         Matrix.ss.import_csc
         io.from_scipy_sparse
+
         """
         return cls._from_csx(_CSC_FORMAT, indptr, row_indices, values, dtype, nrows, ncols, name)
 
@@ -1294,6 +1219,7 @@ class Matrix(BaseType):
         to_dcsr
         Matrix.ss.import_hypercsr
         io.from_scipy_sparse
+
         """
         if backend == "suitesparse":
             return cls.ss.import_hypercsr(
@@ -1378,6 +1304,7 @@ class Matrix(BaseType):
         to_dcsc
         Matrix.ss.import_hypercsc
         io.from_scipy_sparse
+
         """
         if backend == "suitesparse":
             return cls.ss.import_hypercsc(
@@ -1439,6 +1366,7 @@ class Matrix(BaseType):
         Returns
         -------
         Matrix
+
         """
         if type(value) is not Scalar:
             try:
@@ -1492,6 +1420,7 @@ class Matrix(BaseType):
         Returns
         -------
         Matrix
+
         """
         values, dtype = values_to_numpy_buffer(values, dtype, subarray_after=2)
         if values.ndim == 0:
@@ -1551,6 +1480,7 @@ class Matrix(BaseType):
         Returns
         -------
         np.ndarray
+
         """
         max_nvals = self._nrows * self._ncols
         if fill_value is None or self._nvals == max_nvals:
@@ -1626,6 +1556,7 @@ class Matrix(BaseType):
         Returns
         -------
         Matrix
+
         """
         order = get_order(order)
         if isinstance(nested_dicts, Sequence):
@@ -1735,6 +1666,7 @@ class Matrix(BaseType):
         from_csr
         Matrix.ss.export
         io.to_scipy_sparse
+
         """
         if backend == "suitesparse":
             info = self.ss.export("csr", sort=sort)
@@ -1766,6 +1698,7 @@ class Matrix(BaseType):
         from_csc
         Matrix.ss.export
         io.to_scipy_sparse
+
         """
         if backend == "suitesparse":
             info = self.ss.export("csc", sort=sort)
@@ -1800,6 +1733,7 @@ class Matrix(BaseType):
         from_dcsc
         Matrix.ss.export
         io.to_scipy_sparse
+
         """
         if backend == "suitesparse":
             info = self.ss.export("hypercsr", sort=sort)
@@ -1842,6 +1776,7 @@ class Matrix(BaseType):
         from_dcsc
         Matrix.ss.export
         io.to_scipy_sparse
+
         """
         if backend == "suitesparse":
             info = self.ss.export("hypercsc", sort=sort)
@@ -1879,6 +1814,7 @@ class Matrix(BaseType):
         Returns
         -------
         dict
+
         """
         order = get_order(order)
         if order == "rowwise":
@@ -1948,6 +1884,7 @@ class Matrix(BaseType):
 
             # Functional syntax
             C << monoid.max(A | B)
+
         """
         return self._ewise_add(other, op)
 
@@ -2038,6 +1975,7 @@ class Matrix(BaseType):
 
             # Functional syntax
             C << binary.gt(A & B)
+
         """
         return self._ewise_mult(other, op)
 
@@ -2132,6 +2070,7 @@ class Matrix(BaseType):
 
             # Functional syntax
             C << binary.div(A | B, left_default=1, right_default=1)
+
         """
         return self._ewise_union(other, op, left_default, right_default)
 
@@ -2285,6 +2224,7 @@ class Matrix(BaseType):
 
             # Functional syntax
             C << semiring.min_plus(A @ v)
+
         """
         return self._mxv(other, op)
 
@@ -2345,6 +2285,7 @@ class Matrix(BaseType):
 
             # Functional syntax
             C << semiring.min_plus(A @ B)
+
         """
         return self._mxm(other, op)
 
@@ -2409,6 +2350,7 @@ class Matrix(BaseType):
         .. code-block:: python
 
             C << A.kronecker(B, op=binary.times)
+
         """
         method_name = "kronecker"
         other = self._expect_type(
@@ -2465,6 +2407,7 @@ class Matrix(BaseType):
 
             # Functional syntax
             C << op.abs(A)
+
         """
         method_name = "apply"
         extra_message = (
@@ -2613,6 +2556,7 @@ class Matrix(BaseType):
 
             # Functional syntax
             C << select.value(A >= 1)
+
         """
         method_name = "select"
         if isinstance(op, str):
@@ -2707,6 +2651,7 @@ class Matrix(BaseType):
         .. code-block:: python
 
             w << A.reduce_rowwise(monoid.plus)
+
         """
         method_name = "reduce_rowwise"
         op = get_typed_op(op, self.dtype, kind="binary|aggregator")
@@ -2744,6 +2689,7 @@ class Matrix(BaseType):
         .. code-block:: python
 
             w << A.reduce_columnwise(monoid.plus)
+
         """
         method_name = "reduce_columnwise"
         op = get_typed_op(op, self.dtype, kind="binary|aggregator")
@@ -2762,8 +2708,7 @@ class Matrix(BaseType):
         )
 
     def reduce_scalar(self, op=monoid.plus, *, allow_empty=True):
-        """
-        Reduce all values in the Matrix into a single value using ``op``.
+        """Reduce all values in the Matrix into a single value using ``op``.
 
         See the `Reduce <../user_guide/operations.html#reduce>`__
         section in the User Guide for more details.
@@ -2785,6 +2730,7 @@ class Matrix(BaseType):
         .. code-block:: python
 
             total << A.reduce_scalar(monoid.plus)
+
         """
         method_name = "reduce_scalar"
         op = get_typed_op(op, self.dtype, kind="binary|aggregator")
@@ -2845,6 +2791,7 @@ class Matrix(BaseType):
         .. code-block:: python
 
             C = A.reposition(1, 2).new()
+
         """
         if nrows is None:
             nrows = self._nrows
@@ -2926,6 +2873,7 @@ class Matrix(BaseType):
             C = A.dup()
             for i in range(1, 4):
                 C << A @ C
+
         """
         method_name = "power"
         if self._nrows != self._ncols:
@@ -2970,6 +2918,7 @@ class Matrix(BaseType):
             If it is Matrix Mask, then only the diagonal is used as the mask.
         accum : Monoid or BinaryOp, optional
             Operator to use to combine existing diagonal values and new values.
+
         """
         if (K := maybe_integral(k)) is None:
             raise TypeError(f"k must be an integer; got bad type: {type(k)}")
@@ -3751,7 +3700,6 @@ class MatrixExpression(BaseExpression):
     to_dense = wrapdoc(Matrix.to_dense)(property(automethods.to_dense))
     to_dicts = wrapdoc(Matrix.to_dicts)(property(automethods.to_dicts))
     to_edgelist = wrapdoc(Matrix.to_edgelist)(property(automethods.to_edgelist))
-    to_values = wrapdoc(Matrix.to_values)(property(automethods.to_values))
     wait = wrapdoc(Matrix.wait)(property(automethods.wait))
     # These raise exceptions
     __array__ = Matrix.__array__
@@ -3852,7 +3800,6 @@ class MatrixIndexExpr(AmbiguousAssignOrExtract):
     to_dense = wrapdoc(Matrix.to_dense)(property(automethods.to_dense))
     to_dicts = wrapdoc(Matrix.to_dicts)(property(automethods.to_dicts))
     to_edgelist = wrapdoc(Matrix.to_edgelist)(property(automethods.to_edgelist))
-    to_values = wrapdoc(Matrix.to_values)(property(automethods.to_values))
     wait = wrapdoc(Matrix.wait)(property(automethods.wait))
     # These raise exceptions
     __array__ = Matrix.__array__
@@ -3927,13 +3874,6 @@ class TransposedMatrix:
         )
         return cols, rows, vals
 
-    @wrapdoc(Matrix.to_values)
-    def to_values(self, dtype=None, *, rows=True, columns=True, values=True, sort=True):
-        rows, cols, vals = self._matrix.to_values(
-            dtype, rows=rows, columns=columns, values=values, sort=sort
-        )
-        return cols, rows, vals
-
     @wrapdoc(Matrix.diag)
     def diag(self, k=0, dtype=None, *, name=None, **opts):
         return self._matrix.diag(-k, dtype, name=name, **opts)

graphblas/core/operator/base.py

@@ -405,7 +405,8 @@ class OpBase:
 
     @classmethod
     def _initialize(cls, include_in_ops=True):
-        """
+        """Initialize operators for this operator type.
+
         include_in_ops determines whether the operators are included in the
         ``gb.ops`` namespace in addition to the defined module.
         """

graphblas/core/operator/binary.py

@@ -663,6 +663,7 @@ class BinaryOp(OpBase):
         Returns
         -------
         BinaryOp or ParameterizedBinaryOp
+
         """
         cls._check_supports_udf("register_anonymous")
         if parameterized:
@@ -725,6 +726,7 @@ class BinaryOp(OpBase):
         >>>         return x == y or abs(x - y) <= max(rel_tol * max(abs(x), abs(y)), abs_tol)
         >>>     return inner
         >>> gb.binary.register_new("user_isclose", user_isclose, parameterized=True)
+
         """
         cls._check_supports_udf("register_new")
         module, funcname = cls._remove_nesting(name)

graphblas/core/operator/indexunary.py

@@ -285,6 +285,7 @@ class IndexUnaryOp(OpBase):
         Returns
         -------
         return IndexUnaryOp or ParameterizedIndexUnaryOp
+
         """
         cls._check_supports_udf("register_anonymous")
         if parameterized:
@@ -340,6 +341,7 @@ class IndexUnaryOp(OpBase):
         >>> gb.indexunary.register_new("row_mod", lambda x, i, j, thunk: i % max(thunk, 2))
         >>> dir(gb.indexunary)
         [..., 'row_mod', ...]
+
         """
         cls._check_supports_udf("register_new")
         module, funcname = cls._remove_nesting(name)

graphblas/core/operator/monoid.py

@@ -270,6 +270,7 @@ class Monoid(OpBase):
         Returns
         -------
         Monoid or ParameterizedMonoid
+
         """
         if type(binaryop) is ParameterizedBinaryOp:
             return ParameterizedMonoid(
@@ -309,6 +310,7 @@ class Monoid(OpBase):
         >>> gb.core.operator.Monoid.register_new("max_zero", gb.binary.max_zero, 0)
         >>> dir(gb.monoid)
         [..., 'max_zero', ...]
+
         """
         module, funcname = cls._remove_nesting(name)
         if lazy:

graphblas/core/operator/select.py

@@ -208,6 +208,7 @@ class SelectOp(OpBase):
         Returns
         -------
         SelectOp or ParameterizedSelectOp
+
         """
         cls._check_supports_udf("register_anonymous")
         if parameterized:
@@ -264,6 +265,7 @@ class SelectOp(OpBase):
         >>> gb.select.register_new("upper_left_triangle", lambda x, i, j, thunk: i + j <= thunk)
         >>> dir(gb.select)
         [..., 'upper_left_triangle', ...]
+
         """
         cls._check_supports_udf("register_new")
         iop = IndexUnaryOp.register_new(

graphblas/core/operator/semiring.py

@@ -287,6 +287,7 @@ class Semiring(OpBase):
         Returns
         -------
         Semiring or ParameterizedSemiring
+
         """
         if type(monoid) is ParameterizedMonoid or type(binaryop) is ParameterizedBinaryOp:
             return ParameterizedSemiring(name, monoid, binaryop, anonymous=True)
@@ -318,6 +319,7 @@ class Semiring(OpBase):
         >>> gb.core.operator.Semiring.register_new("max_max", gb.monoid.max, gb.binary.max)
         >>> dir(gb.semiring)
         [..., 'max_max', ...]
+
         """
         module, funcname = cls._remove_nesting(name)
         if lazy:

graphblas/core/operator/unary.py

@@ -304,6 +304,7 @@ class UnaryOp(OpBase):
         Returns
         -------
         UnaryOp or ParameterizedUnaryOp
+
         """
         cls._check_supports_udf("register_anonymous")
         if parameterized:
@@ -349,6 +350,7 @@ class UnaryOp(OpBase):
         >>> gb.core.operator.UnaryOp.register_new("plus_one", lambda x: x + 1)
         >>> dir(gb.unary)
         [..., 'plus_one', ...]
+
         """
         cls._check_supports_udf("register_new")
         module, funcname = cls._remove_nesting(name)

graphblas/core/operator/utils.py

@@ -170,6 +170,7 @@ def get_semiring(monoid, binaryop, name=None):
     semiring.register_anonymous
     semiring.register_new
     semiring.from_string
+
     """
     monoid, opclass = find_opclass(monoid)
     switched = False