compute maximum bisimulation using Paige-Tarjan's Algorithm (#1089)

* fighting a lot with the borrowchecker and dont want to wrap in cells

* rewrote initialization

* adjusted build_counterimage to work with new blocks

* Rewrote group_by_counterimage and split. Added new CounterImageGroup

* removed repartition and instead expanded the split function

* fixed various bugs

* added return iterator

* added tests

* typing stubs

* added docs and fixed styling

* added release notes

* removed unnecessary categories from release notes

* use Entry enum instead of .contains_key to fill Hash Map

* adjusted test to use self.subTest

* improved error handling

* removed unused enum

* Added test for multigraph compatibility

* fixed multigraph compatability

* added comment

* added new custom return type IndexPartitionBlock

* adjusted release notes and fixed formatting

* added typing stubs for IndexPartitionBlock

* included IndexPartitionBlock in lib.rs

* changed types to work with new custom_vec_iter_impl! macro

* fixed broken stubs

---------

Co-authored-by: Ivan Carvalho <8753214+IvanIsCoding@users.noreply.github.com>

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]]): ...