Add biadjacency matrix helpers

docs/source/api/algorithm_functions/other.rst

@@ -7,6 +7,7 @@ Other Algorithm Functions
    :toctree: ../../apiref
 
    rustworkx.adjacency_matrix
+   rustworkx.biadjacency_matrix
    rustworkx.transitivity
    rustworkx.core_number
    rustworkx.graph_line_graph

docs/source/api/pydigraph_api_functions.rst

@@ -19,6 +19,7 @@ the functions from the explicitly typed based on the data type.
    rustworkx.digraph_floyd_warshall_numpy
    rustworkx.digraph_floyd_warshall_successor_and_distance
    rustworkx.digraph_adjacency_matrix
+   rustworkx.digraph_biadjacency_matrix
    rustworkx.digraph_all_simple_paths
    rustworkx.digraph_all_pairs_all_simple_paths
    rustworkx.digraph_astar_shortest_path

docs/source/api/pygraph_api_functions.rst

@@ -19,6 +19,7 @@ typed API based on the data type.
    rustworkx.graph_floyd_warshall_numpy
    rustworkx.graph_floyd_warshall_successor_and_distance
    rustworkx.graph_adjacency_matrix
+   rustworkx.graph_biadjacency_matrix
    rustworkx.graph_all_simple_paths
    rustworkx.graph_all_pairs_all_simple_paths
    rustworkx.graph_astar_shortest_path

pyproject.toml

@@ -67,6 +67,7 @@ test = [
   "maturin>=1.9.0,<2.0",
   "testtools>=2.5.0",
   "networkx>=3.2",
+  "scipy>=1.11; python_version >= '3.11' and platform_system != 'Windows'",
   "stestr>=4.1",
 ]
 lint = [

releasenotes/notes/add-biadjacency-matrix-1412.yaml

@@ -0,0 +1,7 @@
+---
+features:
+  - |
+    Added :meth:`~rustworkx.PyGraph.from_biadjacency_matrix`,
+    :meth:`~rustworkx.PyDiGraph.from_biadjacency_matrix`, and
+    :func:`~rustworkx.biadjacency_matrix` for SciPy sparse biadjacency matrix
+    conversion.

rustworkx/__init__.py

@@ -260,6 +260,42 @@ def adjacency_matrix(graph, weight_fn=None, default_weight=1.0, null_value=0.0,
     raise TypeError(f"Invalid Input Type {type(graph)} for graph")
 
 
+@_rustworkx_dispatch
+def biadjacency_matrix(
+    graph,
+    row_order,
+    column_order,
+    weight_fn=None,
+    default_weight=1.0,
+    format="csr",
+    parallel_edge="sum",
+):
+    """Return the biadjacency matrix for a graph object as a SciPy sparse array.
+
+    :param graph: The graph used to generate the biadjacency matrix from. Can
+        be either a :class:`~rustworkx.PyGraph` or :class:`~rustworkx.PyDiGraph`.
+    :param list row_order: The node indices to use for the rows of the output
+        matrix.
+    :param list column_order: The node indices to use for the columns of the
+        output matrix.
+    :param callable weight_fn: A callable object which will be passed the edge
+        object and expected to return a ``float``.
+    :param float default_weight: If ``weight_fn`` is not used this can be
+        optionally used to specify a default weight to use for all edges.
+    :param str format: The SciPy sparse array format to return. Defaults to
+        ``"csr"``.
+    :param str parallel_edge: Optional argument that determines how the function
+        handles parallel edges. ``"min"``, ``"max"``, ``"avg"``, and ``"sum"``
+        are supported. The default is ``"sum"``.
+
+    :returns: The biadjacency matrix.
+    :rtype: scipy.sparse.sparray
+
+    :raises ImportError: If SciPy is not installed.
+    """
+    raise TypeError(f"Invalid Input Type {type(graph)} for graph")
+
+
 @_rustworkx_dispatch
 def all_simple_paths(graph, from_, to, min_depth=None, cutoff=None):
     """Return all simple paths between 2 nodes in a PyGraph object

rustworkx/__init__.pyi

@@ -100,6 +100,8 @@ from .rustworkx import graph_condensation as graph_condensation
 from .rustworkx import weakly_connected_components as weakly_connected_components
 from .rustworkx import digraph_adjacency_matrix as digraph_adjacency_matrix
 from .rustworkx import graph_adjacency_matrix as graph_adjacency_matrix
+from .rustworkx import digraph_biadjacency_matrix as digraph_biadjacency_matrix
+from .rustworkx import graph_biadjacency_matrix as graph_biadjacency_matrix
 from .rustworkx import cycle_basis as cycle_basis
 from .rustworkx import articulation_points as articulation_points
 from .rustworkx import bridges as bridges
@@ -346,6 +348,15 @@ def adjacency_matrix(
     null_value: float = ...,
     node_list: Sequence[int] | None = ...,
 ) -> npt.NDArray[np.float64]: ...
+def biadjacency_matrix(
+    graph: PyGraph[_S, _T] | PyDiGraph[_S, _T],
+    row_order: Sequence[int],
+    column_order: Sequence[int],
+    weight_fn: Callable[[_T], float] | None = ...,
+    default_weight: float = ...,
+    format: str = ...,
+    parallel_edge: str = ...,
+) -> Any: ...
 def all_simple_paths(
     graph: PyGraph | PyDiGraph,
     from_: int,

rustworkx/rustworkx.pyi

@@ -298,6 +298,26 @@ def graph_adjacency_matrix(
     parallel_edge: str = ...,
     node_list: Sequence[int] | None = ...,
 ) -> npt.NDArray[np.float64]: ...
+def digraph_biadjacency_matrix(
+    graph: PyDiGraph[_S, _T],
+    row_order: Sequence[int],
+    column_order: Sequence[int],
+    /,
+    weight_fn: Callable[[_T], float] | None = ...,
+    default_weight: float = ...,
+    format: str = ...,
+    parallel_edge: str = ...,
+) -> Any: ...
+def graph_biadjacency_matrix(
+    graph: PyGraph[_S, _T],
+    row_order: Sequence[int],
+    column_order: Sequence[int],
+    /,
+    weight_fn: Callable[[_T], float] | None = ...,
+    default_weight: float = ...,
+    format: str = ...,
+    parallel_edge: str = ...,
+) -> Any: ...
 def cycle_basis(graph: PyGraph, /, root: int | None = ...) -> list[list[int]]: ...
 def articulation_points(graph: PyGraph, /) -> set[int]: ...
 def bridges(graph: PyGraph, /) -> set[tuple[int]]: ...
@@ -1438,6 +1458,8 @@ class PyGraph(Generic[_S, _T]):
         matrix: npt.NDArray[np.float64], /, null_value: float = ...
     ) -> PyGraph[int, float]: ...
     @staticmethod
+    def from_biadjacency_matrix(matrix: Any, /) -> PyGraph[int, float]: ...
+    @staticmethod
     def from_complex_adjacency_matrix(
         matrix: npt.NDArray[np.complex64], /, null_value: complex = ...
     ) -> PyGraph[int, complex]: ...
@@ -1622,6 +1644,8 @@ class PyDiGraph(Generic[_S, _T]):
         matrix: npt.NDArray[np.float64], /, null_value: float = ...
     ) -> PyDiGraph[int, float]: ...
     @staticmethod
+    def from_biadjacency_matrix(matrix: Any, /) -> PyDiGraph[int, float]: ...
+    @staticmethod
     def from_complex_adjacency_matrix(
         matrix: npt.NDArray[np.complex64], /, null_value: complex = ...
     ) -> PyDiGraph[int, complex]: ...