compute maximum bisimulation using Paige-Tarjan's Algorithm

releasenotes/notes/maximum-bisimulation-942a9d0dc9b46ee4.yaml

@@ -0,0 +1,14 @@
+features:
+  - |
+    Added a new function :func:`~rustworkx.digraph_maximum_bisimulation` to
+    compute the maximum bisimulation or relational coarsest partition of a
+    graph. This function is based on the algorithm described in the publication
+    "Three partition refinement algorithms" by Paige and Tarjan. This function
+    recieves a graph and returns a
+    :class:`~rustworkx.RelationalCoarsestPartition`. This function is in regards
+    to issue `#1075 <https://github.com/Qiskit/rustworkx/issues/1075>`__.
+  - |
+    Added a new class :class:`~rustworkx.RelationalCoarsestPartition` to output
+    the maximum bisimulation or relational coarsest partition of a graph. This
+    class contains instances of :class:`~rustworkx.NodeIndices` and can be
+    iterated over.

rustworkx/__init__.pyi

@@ -34,6 +34,7 @@ from .rustworkx import FailedToConverge as FailedToConverge
 from .rustworkx import InvalidMapping as InvalidMapping
 from .rustworkx import GraphNotBipartite as GraphNotBipartite
 
+from .rustworkx import digraph_maximum_bisimulation as digraph_maximum_bisimulation
 from .rustworkx import digraph_cartesian_product as digraph_cartesian_product
 from .rustworkx import graph_cartesian_product as graph_cartesian_product
 from .rustworkx import digraph_eigenvector_centrality as digraph_eigenvector_centrality
@@ -237,6 +238,7 @@ from .rustworkx import BFSPredecessors as BFSPredecessors
 from .rustworkx import EdgeIndexMap as EdgeIndexMap
 from .rustworkx import EdgeIndices as EdgeIndices
 from .rustworkx import Chains as Chains
+from .rustworkx import RelationalCoarsestPartition as RelationalCoarsestPartition
 from .rustworkx import EdgeList as EdgeList
 from .rustworkx import NodeMap as NodeMap
 from .rustworkx import NodesCountMapping as NodesCountMapping

rustworkx/rustworkx.pyi

@@ -504,6 +504,10 @@ def is_maximal_matching(
     /,
 ) -> bool: ...
 
+# Maximum Bisimulation
+
+def digraph_maximum_bisimulation(graph: PyDiGraph) -> RelationalCoarsestPartition: ...
+
 # Planar
 
 def is_planar(graph: PyGraph, /) -> bool: ...
@@ -1025,6 +1029,9 @@ class EdgeIndices(_RustworkxCustomVecIter[int]): ...
 @final
 class Chains(_RustworkxCustomVecIter[EdgeIndices]): ...
 
+@final
+class RelationalCoarsestPartition(_RustworkxCustomVecIter[NodeIndices]): ...
+
 @final
 class EdgeList(_RustworkxCustomVecIter[tuple[int, int]]): ...