compute maximum bisimulation using Paige-Tarjan's Algorithm

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

@@ -0,0 +1,17 @@
+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.IndexPartitionBlock` and can be
+    iterated over.
+  - |
+    Added a new class :class:`~rustworkx.IndexPartitionBlock` to output
+    a block of a node partition. This class is an iterator over node indices.

rustworkx/__init__.pyi

@@ -36,6 +36,7 @@ from .rustworkx import InvalidMapping as InvalidMapping
 from .rustworkx import GraphNotBipartite as GraphNotBipartite
 from .rustworkx import ColoringStrategy as ColoringStrategy
 
+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
@@ -246,6 +247,8 @@ 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 IndexPartitionBlock as IndexPartitionBlock
+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

@@ -535,6 +535,10 @@ def is_maximal_matching(
     /,
 ) -> bool: ...
 
+# Maximum Bisimulation
+
+def digraph_maximum_bisimulation(graph: PyDiGraph) -> RelationalCoarsestPartition: ...
+
 # Planar
 
 def is_planar(graph: PyGraph, /) -> bool: ...
@@ -1091,6 +1095,12 @@ class EdgeIndices(_RustworkxCustomVecIter[int]): ...
 @final
 class Chains(_RustworkxCustomVecIter[EdgeIndices]): ...
 
+@final
+class IndexPartitionBlock(_RustworkxCustomVecIter[int]): ...
+
+@final
+class RelationalCoarsestPartition(_RustworkxCustomVecIter[IndexPartitionBlock]): ...
+
 @final
 class EdgeList(_RustworkxCustomVecIter[tuple[int, int]]): ...