Expose can_contract_without_cycle (#1459)

* expose can-contract-without-cycle function

* add tests for can_contract_without_cycle & make it non static

* fix doc test

* update release note

* revert can_contract_without_cycle to can_contract

Author: 0xSooki

releasenotes/notes/expose-can-contract-without-cycle-bd82ec1e5fd87bc7.yaml

@@ -0,0 +1,4 @@
+---
+features:
+  - |
+    Exposed the `can_contract_without_cycle` method on `PyDiGraph` object. This method enables users to check, prior to contraction, whether merging a set of nodes into a single node would introduce a cycle in the graph. This is especially useful for applications that require maintaining acyclic properties, such as working with DAGs.

rustworkx-core/src/graph_ext/contraction.rs

@@ -498,8 +498,44 @@ where
 
     Ok(node_index)
 }
-
-fn can_contract<G>(graph: G, nodes: &IndexSet<G::NodeId, foldhash::fast::RandomState>) -> bool
+/// Check if a set of nodes in a directed graph can be contracted without introducing a cycle.
+///
+/// This function determines whether contracting the given set of nodes into a single node
+/// would introduce a cycle in the graph. It is typically used to check the feasibility of the contraction before performing
+/// the actual operation.
+///
+/// # Arguments
+///
+/// * `graph` - The graph to check.
+/// * `nodes` - A set of node indices to be contracted.
+///
+/// A bool whether the graph can be contracted based on the given nodes is returned.
+///
+/// # Example
+///
+/// ```rust
+/// use petgraph::stable_graph::StableDiGraph;
+/// use indexmap::IndexSet;
+/// use foldhash::fast::RandomState;
+/// use rustworkx_core::graph_ext::contraction::can_contract;
+///
+/// // Create a simple DAG: a -> b -> c
+/// let mut graph = StableDiGraph::<&str, ()>::default();
+/// let a = graph.add_node("a");
+/// let b = graph.add_node("b");
+/// let c = graph.add_node("c");
+/// graph.add_edge(a, b, ());
+/// graph.add_edge(b, c, ());
+///
+/// // Try to contract nodes b and c
+/// let mut nodes = IndexSet::with_hasher(RandomState::default());
+/// nodes.insert(b);
+/// nodes.insert(c);
+///
+/// let can_contract = can_contract(&graph, &nodes);
+/// assert!(can_contract); // true: contracting b and c does not introduce a cycle
+/// ```
+pub fn can_contract<G>(graph: G, nodes: &IndexSet<G::NodeId, foldhash::fast::RandomState>) -> bool
 where
     G: Data + Visitable + IntoEdgesDirected,
     G::NodeId: Eq + Hash,

rustworkx-core/src/graph_ext/mod.rs

@@ -77,8 +77,8 @@ pub mod contraction;
 pub mod multigraph;
 
 pub use contraction::{
-    ContractNodesDirected, ContractNodesSimpleDirected, ContractNodesSimpleUndirected,
-    ContractNodesUndirected,
+    can_contract, ContractNodesDirected, ContractNodesSimpleDirected,
+    ContractNodesSimpleUndirected, ContractNodesUndirected,
 };
 pub use multigraph::{HasParallelEdgesDirected, HasParallelEdgesUndirected};
 

rustworkx-core/tests/graph_ext/contraction.rs

@@ -10,13 +10,17 @@
 // License for the specific language governing permissions and limitations
 // under the License.
 
+use foldhash::fast::RandomState;
 use foldhash::HashSet;
 use hashbrown::HashMap;
+use indexmap::IndexSet;
 use petgraph::data::Build;
+use petgraph::prelude::*;
 use petgraph::visit::{
     Data, EdgeCount, EdgeRef, GraphBase, IntoEdgeReferences, IntoNodeIdentifiers,
 };
 use rustworkx_core::err::ContractError;
+use rustworkx_core::graph_ext::contraction::can_contract;
 use rustworkx_core::graph_ext::*;
 use std::convert::Infallible;
 use std::fmt::Debug;
@@ -401,3 +405,36 @@ where
     assert_eq!(dag.node_count(), 1);
     assert_eq!(dag.edge_count(), 0);
 }
+
+#[test]
+fn test_can_contract_without_cycle_true() {
+    // a -> b -> c (contract b and c, should be allowed)
+    let mut graph = StableDiGraph::<&str, ()>::default();
+    let a = graph.add_node("a");
+    let b = graph.add_node("b");
+    let c = graph.add_node("c");
+    graph.add_edge(a, b, ());
+    graph.add_edge(b, c, ());
+    let mut nodes: IndexSet<_, RandomState> = IndexSet::with_hasher(RandomState::default());
+    nodes.insert(b);
+    nodes.insert(c);
+
+    assert!(can_contract(&graph, &nodes));
+}
+
+#[test]
+fn test_can_contract_without_cycle_false() {
+    // a -> b -> c, c -> a (contract a and c, would create a cycle)
+    let mut graph = StableDiGraph::<&str, ()>::default();
+    let a = graph.add_node("a");
+    let b = graph.add_node("b");
+    let c = graph.add_node("c");
+    graph.add_edge(a, b, ());
+    graph.add_edge(b, c, ());
+    graph.add_edge(c, a, ());
+    let mut nodes: IndexSet<_, RandomState> = IndexSet::with_hasher(RandomState::default());
+    nodes.insert(a);
+    nodes.insert(c);
+
+    assert!(!can_contract(&graph, &nodes));
+}

rustworkx/rustworkx.pyi

@@ -1426,6 +1426,7 @@ class PyDiGraph(Generic[_S, _T]):
         check_cycle: bool | None = ...,
         weight_combo_fn: Callable[[_T, _T], _T] | None = ...,
     ) -> int: ...
+    def can_contract_without_cycle(self, nodes: Sequence[int], /) -> bool: ...
     def copy(self) -> Self: ...
     def edge_index_map(self) -> EdgeIndexMap[_T]: ...
     def edge_indices(self) -> EdgeIndices: ...

src/digraph.rs

@@ -41,10 +41,10 @@ use ndarray::prelude::*;
 use num_traits::Zero;
 use numpy::Complex64;
 use numpy::PyReadonlyArray2;
-
 use petgraph::algo;
 use petgraph::graph::{EdgeIndex, NodeIndex};
 use petgraph::prelude::*;
+use rustworkx_core::graph_ext::contraction::can_contract;
 
 use crate::RxPyResult;
 use petgraph::visit::{
@@ -60,6 +60,8 @@ use super::{
     find_node_by_weight, weight_callable, DAGHasCycle, DAGWouldCycle, IsNan, NoEdgeBetweenNodes,
     NoSuitableNeighbors, NodesRemoved, StablePyGraph,
 };
+use foldhash::fast::RandomState;
+use indexmap::IndexSet;
 
 use super::dag_algo::is_directed_acyclic_graph;
 
@@ -3013,6 +3015,17 @@ impl PyDiGraph {
         Ok(res.index())
     }
 
+    /// Check if contracting the specified nodes can occur without introducing cycles.
+    ///
+    /// :param list[int] nodes: A set of node indices to check for contraction.
+    /// :returns: `True` if contraction can proceed without creating cycles, `False` otherwise.
+    #[pyo3(text_signature = "(self, nodes, /)",signature = (nodes))]
+    pub fn can_contract_without_cycle(&self, nodes: Vec<usize>) -> bool {
+        let index_set: IndexSet<NodeIndex, RandomState> =
+            nodes.into_iter().map(NodeIndex::new).collect();
+        can_contract(&self.graph, &index_set)
+    }
+
     /// Return a new PyDiGraph object for a subgraph of this graph and a NodeMap
     /// object that maps the nodes of the subgraph to the nodes of the original graph.
     ///

tests/digraph/test_contract_nodes.py

@@ -263,3 +263,26 @@ def test_replace_all_nodes(self):
         self.dag.contract_nodes(self.dag.node_indexes(), "m")
         self.assertEqual(set(self.dag.nodes()), {"m"})
         self.assertFalse(self.dag.edges())
+
+
+class TestCanContractWithoutCycle(unittest.TestCase):
+    def test_can_contract_without_cycle_true(self):
+        # a -> b -> c (contract b and c, should be allowed)
+        graph = rustworkx.PyDiGraph()
+        a = graph.add_node("a")
+        b = graph.add_node("b")
+        c = graph.add_node("c")
+        graph.add_edge(a, b, 0)
+        graph.add_edge(b, c, 0)
+        self.assertTrue(graph.can_contract_without_cycle([b, c]))
+
+    def test_can_contract_without_cycle_false(self):
+        # a -> b -> c, c -> a (contract a and c, would create a cycle)
+        graph = rustworkx.PyDiGraph()
+        a = graph.add_node("a")
+        b = graph.add_node("b")
+        c = graph.add_node("c")
+        graph.add_edge(a, b, 0)
+        graph.add_edge(b, c, 0)
+        graph.add_edge(c, a, 0)
+        self.assertFalse(graph.can_contract_without_cycle([a, c]))