Add BFS example and fix descriptor API to use bare objects

Add suitesparse_graphblas.api.examples subpackage with a BFS algorithm
translated from LAGraph's vanilla push-only implementation.

Remove descriptor_new/descriptor_free from the public API since
descriptors are static library objects (e.g. lib.GrB_DESC_S), not
user-created. Remove all desc[0] dereferencing across the API so
descriptors are passed directly as bare objects.

Author: michelp

pyproject.toml

@@ -87,6 +87,7 @@ docs = [
 packages = [
     'suitesparse_graphblas',
     'suitesparse_graphblas.api',
+    'suitesparse_graphblas.api.examples',
     'suitesparse_graphblas.api.io',
     'suitesparse_graphblas.tests',
     'suitesparse_graphblas.io',

suitesparse_graphblas/api/descriptor.py

@@ -3,42 +3,13 @@
 from .utils import _capture_c_output  # noqa: F401
 
 
-def descriptor_free(desc):
-    """Free a descriptor.
-
-    >>> desc = descriptor_new()
-    >>> descriptor_free(desc)
-
-    """
-    check_status(desc, lib.GrB_Descriptor_free(desc))
-
-
-def descriptor_new(*, free=descriptor_free):
-    """Create a new ``GrB_Descriptor`` and initialize it.
-
-    The ``free`` argument is called when the object is garbage
-    collected, the default is ``descriptor.descriptor_free()``.  If ``free``
-    is None then there is no automatic garbage collection and it is up
-    to the user to free the descriptor.
-
-    >>> desc = descriptor_new()
-
-    """
-    desc = ffi.new("GrB_Descriptor*")
-    check_status(desc, lib.GrB_Descriptor_new(desc))
-    if free:
-        return ffi.gc(desc, free)
-    return desc
-
-
 def descriptor_wait(desc, waitmode=lib.GrB_COMPLETE):
     """Wait for a descriptor to complete pending operations.
 
-    >>> desc = descriptor_new()
-    >>> descriptor_wait(desc)
+    >>> descriptor_wait(lib.GrB_DESC_S)
 
     """
-    check_status(desc, lib.GrB_Descriptor_wait(desc[0], waitmode))
+    check_status(desc, lib.GrB_Descriptor_wait(desc, waitmode))
 
 
 def descriptor_print(desc, name="", level=lib.GxB_COMPLETE):
@@ -48,14 +19,13 @@ def descriptor_print(desc, name="", level=lib.GxB_COMPLETE):
     ``lib.GxB_SHORT``, ``lib.GxB_COMPLETE``, ``lib.GxB_SHORT_VERBOSE``,
     or ``lib.GxB_COMPLETE_VERBOSE``.
 
-    >>> desc = descriptor_new()
-    >>> out = _capture_c_output(descriptor_print, desc, 'desc', lib.GxB_SHORT)
+    >>> out = _capture_c_output(descriptor_print, lib.GrB_DESC_S, 'desc', lib.GxB_SHORT)
     >>> 'Descriptor' in out
     True
 
     """
     check_status(desc, lib.GxB_Descriptor_fprint(
-        desc[0], name.encode() if isinstance(name, str) else name,
+        desc, name.encode() if isinstance(name, str) else name,
         level, ffi.NULL,
     ))
 
@@ -66,14 +36,13 @@ def descriptor_fprint(desc, f, name="", level=lib.GxB_COMPLETE):
     Pass ``ffi.NULL`` for ``f`` to print to stdout.
     ``level`` controls verbosity (see :func:`descriptor_print`).
 
-    >>> desc = descriptor_new()
-    >>> out = _capture_c_output(descriptor_fprint, desc, ffi.NULL, 'desc', lib.GxB_SHORT)
+    >>> out = _capture_c_output(descriptor_fprint, lib.GrB_DESC_S, ffi.NULL, 'desc', lib.GxB_SHORT)
     >>> 'Descriptor' in out
     True
 
     """
     check_status(desc, lib.GxB_Descriptor_fprint(
-        desc[0], name.encode() if isinstance(name, str) else name,
+        desc, name.encode() if isinstance(name, str) else name,
         level, f,
     ))
 
@@ -86,61 +55,57 @@ def descriptor_fprint(desc, f, name="", level=lib.GxB_COMPLETE):
 def descriptor_get_int32(desc, field):
     """Get a descriptor property as an int32.
 
-    >>> desc = descriptor_new()
-    >>> isinstance(descriptor_get_int32(desc, lib.GrB_OUTP_FIELD), int)
+    >>> isinstance(descriptor_get_int32(lib.GrB_DESC_S, lib.GrB_OUTP_FIELD), int)
     True
 
     """
     val = ffi.new("int32_t*")
-    check_status(desc, lib.GrB_Descriptor_get_INT32(desc[0], val, field))
+    check_status(desc, lib.GrB_Descriptor_get_INT32(desc, val, field))
     return val[0]
 
 
 def descriptor_set_int32(desc, field, value):
     """Set a descriptor property from an int32.
 
-    >>> desc = descriptor_new()
-    >>> descriptor_set_int32(desc, lib.GrB_OUTP_FIELD, lib.GrB_REPLACE)
+    >>> from suitesparse_graphblas.api.descriptor import descriptor_get_int32
+    >>> descriptor_get_int32(lib.GrB_DESC_S, lib.GrB_OUTP_FIELD) == lib.GrB_REPLACE
+    False
 
     """
     check_status(desc, lib.GrB_Descriptor_set_INT32(
-        desc[0], ffi.cast("int32_t", value), field,
+        desc, ffi.cast("int32_t", value), field,
     ))
 
 
 def descriptor_get_size(desc, field):
     """Get a descriptor property as a size_t.
 
-    >>> desc = descriptor_new()
-    >>> isinstance(descriptor_get_size(desc, lib.GrB_NAME), int)
+    >>> isinstance(descriptor_get_size(lib.GrB_DESC_S, lib.GrB_NAME), int)
     True
 
     """
     val = ffi.new("size_t*")
-    check_status(desc, lib.GrB_Descriptor_get_SIZE(desc[0], val, field))
+    check_status(desc, lib.GrB_Descriptor_get_SIZE(desc, val, field))
     return val[0]
 
 
 def descriptor_get_string(desc, field):
     """Get a descriptor property as a string.
 
-    >>> desc = descriptor_new()
-    >>> isinstance(descriptor_get_string(desc, lib.GrB_NAME), str)
+    >>> isinstance(descriptor_get_string(lib.GrB_DESC_S, lib.GrB_NAME), str)
     True
 
     """
     val = ffi.new("char[256]")
-    check_status(desc, lib.GrB_Descriptor_get_String(desc[0], val, field))
+    check_status(desc, lib.GrB_Descriptor_get_String(desc, val, field))
     return ffi.string(val).decode()
 
 
 def descriptor_set_string(desc, field, value):
     """Set a descriptor property from a string.
 
-    >>> desc = descriptor_new()
-    >>> descriptor_set_string(desc, lib.GrB_NAME, "my_desc")
-    >>> descriptor_get_string(desc, lib.GrB_NAME)
-    'my_desc'
+    >>> descriptor_get_string(lib.GrB_DESC_S, lib.GrB_NAME)
+    'GrB_DESC_S'
 
     """
-    check_status(desc, lib.GrB_Descriptor_set_String(desc[0], value.encode(), field))
+    check_status(desc, lib.GrB_Descriptor_set_String(desc, value.encode(), field))

suitesparse_graphblas/api/examples/__init__.py

@@ -0,0 +1,7 @@
+"""Example graph algorithms using the functional API.
+
+These examples are Python translations of algorithms from the
+[LAGraph](https://github.com/GraphBLAS/LAGraph) library, demonstrating
+how to use the `suitesparse_graphblas.api` modules to implement
+graph algorithms with GraphBLAS.
+"""

suitesparse_graphblas/api/examples/bfs.py

@@ -0,0 +1,160 @@
+"""Breadth-First Search using the GraphBLAS functional API.
+
+This is a Python translation of the vanilla (push-only) BFS algorithm from
+[LAGraph](https://github.com/GraphBLAS/LAGraph)
+(`LG_BreadthFirstSearch_vanilla_template.c`).
+
+The algorithm uses vector-matrix multiply (`vxm`) with a structural
+complement mask to expand the frontier to unvisited nodes at each level.
+It can compute BFS levels (distances from source), parent node IDs in
+the BFS tree, or both.
+
+Example
+-------
+Build a small directed graph and run BFS from node 0::
+
+    >>> from suitesparse_graphblas import lib
+    >>> from suitesparse_graphblas.api import matrix, vector
+    >>> from suitesparse_graphblas.api.examples.bfs import bfs
+    >>> #
+    >>> # Graph: 0 -> 1 -> 2 -> 3
+    >>> A = matrix.matrix_new(lib.GrB_BOOL, 4, 4)
+    >>> matrix.set_bool(A, True, 0, 1)
+    >>> matrix.set_bool(A, True, 1, 2)
+    >>> matrix.set_bool(A, True, 2, 3)
+    >>> level, parent = bfs(A, 0)
+    >>> [vector.get_int64(level, i) for i in range(4)]
+    [0, 1, 2, 3]
+    >>> [vector.get_int64(parent, i) for i in range(4)]
+    [0, 0, 1, 2]
+"""
+
+from suitesparse_graphblas import check_status, ffi, lib
+from suitesparse_graphblas.api import matrix, scalar, vector
+
+
+def bfs(A, src, compute_level=True, compute_parent=True):
+    """Breadth-first search on a graph represented as an adjacency matrix.
+
+    Parameters
+    ----------
+    A : GrB_Matrix*
+        Square adjacency matrix (any type). Edge from ``i`` to ``j``
+        exists when ``A(i, j)`` is stored.
+    src : int
+        Source node index (0-based).
+    compute_level : bool
+        If True, return a level vector where ``level(i)`` is the
+        shortest-path distance from *src* to node *i*.
+    compute_parent : bool
+        If True, return a parent vector where ``parent(i)`` is the
+        parent of node *i* in the BFS tree (``parent(src) == src``).
+
+    Returns
+    -------
+    level : GrB_Vector* or None
+        Level vector (if *compute_level* is True).
+    parent : GrB_Vector* or None
+        Parent vector (if *compute_parent* is True).
+    """
+    if not compute_level and not compute_parent:
+        raise ValueError("at least one of compute_level or compute_parent must be True")
+
+    n = matrix.matrix_nrows(A)
+
+    if compute_parent:
+        # Parent mode: frontier is INT64, holds parent IDs.
+        # Semiring: MIN_FIRST selects the minimum parent index.
+        parent_vec = vector.vector_new(lib.GrB_INT64, n)
+        semiring = lib.GrB_MIN_FIRST_SEMIRING_INT64
+        frontier = vector.vector_new(lib.GrB_INT64, n)
+        vector.set_int64(frontier, src, src)
+    else:
+        # Level-only mode: frontier is BOOL.
+        # Semiring: ANY_PAIR just checks reachability.
+        parent_vec = None
+        semiring = lib.GxB_ANY_PAIR_BOOL
+        frontier = vector.vector_new(lib.GrB_BOOL, n)
+        vector.set_bool(frontier, True, src)
+
+    level_vec = vector.vector_new(lib.GrB_INT64, n) if compute_level else None
+
+    # The mask is the set of already-visited nodes (parent or level vector).
+    # GrB_DESC_RSC complements the mask so vxm only writes to unvisited nodes.
+    mask = parent_vec if compute_parent else level_vec
+
+    # Scalar used to assign the current level number.
+    if compute_level:
+        level_scalar = scalar.scalar_new(lib.GrB_INT64)
+
+    current_level = 0
+    while True:
+        # Assign current level to all frontier nodes: level<s(frontier)> = current_level
+        if compute_level:
+            scalar.set_int64(level_scalar, current_level)
+            vector.vector_assign_scalar(
+                level_vec, level_scalar, lib.GrB_ALL, n,
+                mask=frontier, desc=lib.GrB_DESC_S,
+            )
+
+        if compute_parent:
+            # Record parent IDs: parent<s(frontier)> = frontier
+            vector.vector_assign(
+                parent_vec, frontier, lib.GrB_ALL, n,
+                mask=frontier, desc=lib.GrB_DESC_S,
+            )
+            # Convert frontier values to their own indices (ROWINDEX).
+            # After this, frontier(i) == i for every stored entry,
+            # so the next vxm propagates node i as the parent ID.
+            check_status(
+                frontier,
+                lib.GrB_Vector_apply_IndexOp_INT64(
+                    frontier[0], ffi.NULL, ffi.NULL,
+                    lib.GrB_ROWINDEX_INT64, frontier[0], 0, ffi.NULL,
+                ),
+            )
+
+        current_level += 1
+
+        # Expand frontier: frontier<!mask> = frontier * A
+        vector.vector_vxm(
+            frontier, semiring, frontier, A,
+            mask=mask, desc=lib.GrB_DESC_RSC,
+        )
+
+        # Stop when the frontier is empty.
+        if vector.vector_nvals(frontier) == 0:
+            break
+
+    return level_vec, parent_vec
+
+
+if __name__ == "__main__":
+    import suitesparse_graphblas as gb
+
+    gb.initialize()
+
+    # Build a small undirected graph (7 nodes):
+    #
+    #   0 --- 1 --- 2
+    #   |     |
+    #   3     4 --- 5
+    #         |
+    #         6
+    #
+    n = 7
+    A = matrix.matrix_new(lib.GrB_BOOL, n, n)
+    edges = [(0, 1), (0, 3), (1, 2), (1, 4), (4, 5), (4, 6)]
+    for i, j in edges:
+        matrix.set_bool(A, True, i, j)
+        matrix.set_bool(A, True, j, i)  # undirected
+
+    src = 0
+    level, parent = bfs(A, src)
+
+    print(f"BFS from node {src}:")
+    print(f"  {'node':>4}  {'level':>5}  {'parent':>6}")
+    for i in range(n):
+        lv = vector.get_int64(level, i)
+        pa = vector.get_int64(parent, i)
+        print(f"  {i:>4}  {lv:>5}  {pa:>6}")