Allow multiple targets for rustworkx.all_simple_paths (#1488)

* Enable multiple targets passed as an iterable to rustworkx.all_simple_paths

* Fix formatting issues

* Use enum to represent single/multiple target nodes, add a release note

Author: lazyhope

releasenotes/notes/expose-all-simple-path-multiple-targets-767f818daeeb5a41.yaml

@@ -0,0 +1,18 @@
+---
+features:
+  - |
+    The :func:`~rustworkx.all_simple_paths` function now supports multiple
+    target nodes passed as an iterable. You can now pass either a single target
+    node (int) or multiple target nodes (iterable of ints) to find all simple
+    paths from a source node to any of the specified targets. For example::
+
+        import rustworkx as rx
+
+        graph = rx.generators.path_graph(4)
+        # Multiple targets - new functionality
+        paths = rx.all_simple_paths(graph, 0, [2, 3])
+        # paths: [[0, 1, 2], [0, 1, 2, 3]]
+
+    This enhancement maintains backward compatibility while providing more
+    flexibility for pathfinding operations in both :class:`~.PyGraph` and
+    :class:`~.PyDiGraph` objects.

rustworkx/__init__.py

@@ -263,7 +263,7 @@ def all_simple_paths(graph, from_, to, min_depth=None, cutoff=None):
     :param graph: The graph to find the path in. Can either be a
         class:`~rustworkx.PyGraph` or :class:`~rustworkx.PyDiGraph`
     :param int from_: The node index to find the paths from
-    :param int to: The node index to find the paths to
+    :param int | Iterable[int] to: The node index(es) to find the paths to
     :param int min_depth: The minimum depth of the path to include in the
         output list of paths. By default all paths are included regardless of
         depth, setting to 0 will behave like the default.

rustworkx/__init__.pyi

@@ -14,7 +14,7 @@ import numpy as np
 import numpy.typing as npt
 
 from typing import Generic, Any, Callable, overload
-from collections.abc import Iterator, Sequence
+from collections.abc import Iterable, Iterator, Sequence
 
 if sys.version_info >= (3, 13):
     from typing import TypeVar
@@ -325,7 +325,7 @@ def adjacency_matrix(
 def all_simple_paths(
     graph: PyGraph | PyDiGraph,
     from_: int,
-    to: int,
+    to: int | Iterable[int],
     min_depth: int | None = ...,
     cutoff: int | None = ...,
 ) -> list[list[int]]: ...

rustworkx/rustworkx.pyi

@@ -285,15 +285,15 @@ def local_complement(
 def digraph_all_simple_paths(
     graph: PyDiGraph,
     origin: int,
-    to: int,
+    to: int | Iterable[int],
     /,
     min_depth: int | None = ...,
     cutoff: int | None = ...,
 ) -> list[list[int]]: ...
 def graph_all_simple_paths(
     graph: PyGraph,
     origin: int,
-    to: int,
+    to: int | Iterable[int],
     /,
     min_depth: int | None = ...,
     cutoff: int | None = ...,

src/connectivity/mod.rs

@@ -950,13 +950,37 @@ pub fn local_complement(
     Ok(complement_graph)
 }
 
+/// Represents target nodes for path-finding operations.
+///
+/// This enum allows functions to accept either a single target node
+/// or multiple target nodes, providing flexibility in path-finding algorithms.
+pub enum TargetNodes {
+    Single(NodeIndex),
+    Multiple(HashSet<NodeIndex>),
+}
+
+impl<'py> FromPyObject<'py> for TargetNodes {
+    fn extract_bound(ob: &Bound<'py, PyAny>) -> PyResult<Self> {
+        if let Ok(int) = ob.extract::<usize>() {
+            Ok(Self::Single(NodeIndex::new(int)))
+        } else {
+            let mut target_set: HashSet<NodeIndex> = HashSet::new();
+            for target in ob.try_iter()? {
+                let target_index = NodeIndex::new(target?.extract::<usize>()?);
+                target_set.insert(target_index);
+            }
+            Ok(Self::Multiple(target_set))
+        }
+    }
+}
+
 /// Return all simple paths between 2 nodes in a PyGraph object
 ///
 /// A simple path is a path with no repeated nodes.
 ///
 /// :param PyGraph graph: The graph to find the path in
 /// :param int origin: The node index to find the paths from
-/// :param int to: The node index to find the paths to
+/// :param int | iterable[int] to: The node index(es) to find the paths to
 /// :param int min_depth: The minimum depth of the path to include in the output
 ///     list of paths. By default all paths are included regardless of depth,
 ///     setting to 0 will behave like the default.
@@ -971,7 +995,7 @@ pub fn local_complement(
 pub fn graph_all_simple_paths(
     graph: &graph::PyGraph,
     origin: usize,
-    to: usize,
+    to: TargetNodes,
     min_depth: Option<usize>,
     cutoff: Option<usize>,
 ) -> PyResult<Vec<Vec<usize>>> {
@@ -981,27 +1005,48 @@ pub fn graph_all_simple_paths(
             "The input index for 'from' is not a valid node index",
         ));
     }
-    let to_index = NodeIndex::new(to);
-    if !graph.graph.contains_node(to_index) {
-        return Err(InvalidNode::new_err(
-            "The input index for 'to' is not a valid node index",
-        ));
-    }
     let min_intermediate_nodes: usize = match min_depth {
         Some(0) | None => 0,
         Some(depth) => depth - 2,
     };
     let cutoff_petgraph: Option<usize> = cutoff.map(|depth| depth - 2);
-    let result: Vec<Vec<usize>> = algo::all_simple_paths::<Vec<_>, _, foldhash::fast::RandomState>(
-        &graph.graph,
-        from_index,
-        to_index,
-        min_intermediate_nodes,
-        cutoff_petgraph,
-    )
-    .map(|v: Vec<NodeIndex>| v.into_iter().map(|i| i.index()).collect())
-    .collect();
-    Ok(result)
+
+    match to {
+        TargetNodes::Single(to_index) => {
+            if !graph.graph.contains_node(to_index) {
+                return Err(InvalidNode::new_err(
+                    "The input index for 'to' is not a valid node index",
+                ));
+            }
+
+            let result: Vec<Vec<usize>> =
+                algo::all_simple_paths::<Vec<_>, _, foldhash::fast::RandomState>(
+                    &graph.graph,
+                    from_index,
+                    to_index,
+                    min_intermediate_nodes,
+                    cutoff_petgraph,
+                )
+                .map(|v: Vec<NodeIndex>| v.into_iter().map(|i| i.index()).collect())
+                .collect();
+            Ok(result)
+        }
+        TargetNodes::Multiple(target_set) => {
+            let result = connectivity::all_simple_paths_multiple_targets(
+                &graph.graph,
+                from_index,
+                &target_set,
+                min_intermediate_nodes,
+                cutoff_petgraph,
+            );
+
+            Ok(result
+                .into_values()
+                .flatten()
+                .map(|path| path.into_iter().map(|node| node.index()).collect())
+                .collect())
+        }
+    }
 }
 
 /// Return all simple paths between 2 nodes in a PyDiGraph object
@@ -1010,7 +1055,7 @@ pub fn graph_all_simple_paths(
 ///
 /// :param PyDiGraph graph: The graph to find the path in
 /// :param int origin: The node index to find the paths from
-/// :param int to: The node index to find the paths to
+/// :param int | iterable[int] to: The node index(es) to find the paths to
 /// :param int min_depth: The minimum depth of the path to include in the output
 ///     list of paths. By default all paths are included regardless of depth,
 ///     setting to 0 will behave like the default.
@@ -1025,7 +1070,7 @@ pub fn graph_all_simple_paths(
 pub fn digraph_all_simple_paths(
     graph: &digraph::PyDiGraph,
     origin: usize,
-    to: usize,
+    to: TargetNodes,
     min_depth: Option<usize>,
     cutoff: Option<usize>,
 ) -> PyResult<Vec<Vec<usize>>> {
@@ -1035,27 +1080,48 @@ pub fn digraph_all_simple_paths(
             "The input index for 'from' is not a valid node index",
         ));
     }
-    let to_index = NodeIndex::new(to);
-    if !graph.graph.contains_node(to_index) {
-        return Err(InvalidNode::new_err(
-            "The input index for 'to' is not a valid node index",
-        ));
-    }
     let min_intermediate_nodes: usize = match min_depth {
         Some(0) | None => 0,
         Some(depth) => depth - 2,
     };
     let cutoff_petgraph: Option<usize> = cutoff.map(|depth| depth - 2);
-    let result: Vec<Vec<usize>> = algo::all_simple_paths::<Vec<_>, _, foldhash::fast::RandomState>(
-        &graph.graph,
-        from_index,
-        to_index,
-        min_intermediate_nodes,
-        cutoff_petgraph,
-    )
-    .map(|v: Vec<NodeIndex>| v.into_iter().map(|i| i.index()).collect())
-    .collect();
-    Ok(result)
+
+    match to {
+        TargetNodes::Single(to_index) => {
+            if !graph.graph.contains_node(to_index) {
+                return Err(InvalidNode::new_err(
+                    "The input index for 'to' is not a valid node index",
+                ));
+            }
+
+            let result: Vec<Vec<usize>> =
+                algo::all_simple_paths::<Vec<_>, _, foldhash::fast::RandomState>(
+                    &graph.graph,
+                    from_index,
+                    to_index,
+                    min_intermediate_nodes,
+                    cutoff_petgraph,
+                )
+                .map(|v: Vec<NodeIndex>| v.into_iter().map(|i| i.index()).collect())
+                .collect();
+            Ok(result)
+        }
+        TargetNodes::Multiple(target_set) => {
+            let result = connectivity::all_simple_paths_multiple_targets(
+                &graph.graph,
+                from_index,
+                &target_set,
+                min_intermediate_nodes,
+                cutoff_petgraph,
+            );
+
+            Ok(result
+                .into_values()
+                .flatten()
+                .map(|path| path.into_iter().map(|node| node.index()).collect())
+                .collect())
+        }
+    }
 }
 
 /// Return all the simple paths between all pairs of nodes in the graph

tests/digraph/test_all_simple_paths.py

@@ -131,6 +131,45 @@ def test_graph_digraph_all_simple_paths(self):
         dag.add_node(1)
         self.assertRaises(TypeError, rustworkx.digraph_all_simple_paths, (dag, 0, 1))
 
+    def test_all_simple_paths_multiple_targets(self):
+        graph = rustworkx.generators.directed_path_graph(4)
+        graph.add_edge(1, 3, None)
+        paths = rustworkx.digraph_all_simple_paths(graph, 0, [2, 3])
+        expected = [[0, 1, 2], [0, 1, 2, 3], [0, 1, 3]]
+        self.assertEqual(len(expected), len(paths))
+        for i in expected:
+            self.assertIn(i, paths)
+
+    def test_all_simple_paths_multiple_targets_iterables(self):
+        graph = rustworkx.generators.directed_path_graph(4)
+        graph.add_edge(1, 3, None)
+        paths = rustworkx.digraph_all_simple_paths(graph, 0, iter([2, 3]))
+        expected = [[0, 1, 2], [0, 1, 2, 3], [0, 1, 3]]
+        self.assertEqual(len(expected), len(paths))
+        for i in expected:
+            self.assertIn(i, paths)
+
+    def test_all_simple_paths_multiple_targets_invalid_type(self):
+        graph = rustworkx.generators.directed_path_graph(4)
+        with self.assertRaises(TypeError):
+            rustworkx.digraph_all_simple_paths(graph, 0, [2, "a"])
+
+    def test_all_simple_paths_multiple_targets_invalid_index(self):
+        graph = rustworkx.generators.directed_path_graph(4)
+        paths = rustworkx.digraph_all_simple_paths(graph, 0, [3, 100])
+        expected = [[0, 1, 2, 3]]
+        self.assertEqual(expected, paths)
+
+    def test_all_simple_paths_on_nontrivial_graph(self):
+        graph = rustworkx.PyDiGraph()
+        graph.add_nodes_from(range(6))
+        graph.add_edges_from_no_data([(0, 1), (0, 5), (1, 2), (1, 5), (2, 3), (3, 4), (4, 5)])
+        paths = rustworkx.digraph_all_simple_paths(graph, 0, [2, 3])
+        expected = [[0, 1, 2], [0, 1, 2, 3]]
+        self.assertEqual(len(expected), len(paths))
+        for i in expected:
+            self.assertIn(i, paths)
+
 
 class TestDiGraphAllSimplePathsAllPairs(unittest.TestCase):
     def setUp(self):

tests/graph/test_all_simple_paths.py

@@ -232,6 +232,54 @@ def test_digraph_graph_all_simple_paths(self):
         dag.add_node(1)
         self.assertRaises(TypeError, rustworkx.graph_all_simple_paths, (dag, 0, 1))
 
+    def test_all_simple_paths_multiple_targets(self):
+        graph = rustworkx.generators.path_graph(4)
+        graph.add_edge(1, 3, None)
+        paths = rustworkx.graph_all_simple_paths(graph, 0, [2, 3])
+        expected = [[0, 1, 2], [0, 1, 3], [0, 1, 2, 3], [0, 1, 3, 2]]
+        self.assertEqual(len(expected), len(paths))
+        for i in expected:
+            self.assertIn(i, paths)
+
+    def test_all_simple_paths_multiple_targets_iterables(self):
+        graph = rustworkx.generators.path_graph(4)
+        graph.add_edge(1, 3, None)
+        paths = rustworkx.graph_all_simple_paths(graph, 0, iter([2, 3]))
+        expected = [[0, 1, 2], [0, 1, 3], [0, 1, 2, 3], [0, 1, 3, 2]]
+        self.assertEqual(len(expected), len(paths))
+        for i in expected:
+            self.assertIn(i, paths)
+
+    def test_all_simple_paths_multiple_targets_invalid_type(self):
+        graph = rustworkx.generators.path_graph(4)
+        with self.assertRaises(TypeError):
+            rustworkx.graph_all_simple_paths(graph, 0, [2, "a"])
+
+    def test_all_simple_paths_multiple_targets_invalid_index(self):
+        graph = rustworkx.generators.path_graph(4)
+        paths = rustworkx.graph_all_simple_paths(graph, 0, [3, 100])
+        expected = [[0, 1, 2, 3]]
+        self.assertEqual(expected, paths)
+
+    def test_all_simple_paths_on_nontrivial_graph(self):
+        graph = rustworkx.PyGraph()
+        graph.add_nodes_from(range(6))
+        graph.add_edges_from_no_data([(0, 1), (0, 5), (1, 2), (1, 5), (2, 3), (3, 4), (4, 5)])
+        paths = rustworkx.graph_all_simple_paths(graph, 0, [2, 3])
+        expected = [
+            [0, 1, 2],
+            [0, 1, 2, 3],
+            [0, 1, 5, 4, 3],
+            [0, 1, 5, 4, 3, 2],
+            [0, 5, 1, 2],
+            [0, 5, 1, 2, 3],
+            [0, 5, 4, 3],
+            [0, 5, 4, 3, 2],
+        ]
+        self.assertEqual(len(expected), len(paths))
+        for i in expected:
+            self.assertIn(i, paths)
+
 
 class TestGraphAllSimplePathsAllPairs(unittest.TestCase):
     def setUp(self):