From 0460d7cb47c81997e1d1a46aa6a19ff6f6d28e8d Mon Sep 17 00:00:00 2001 From: georgios-ts Date: Mon, 27 Sep 2021 16:08:05 +0300 Subject: [PATCH 01/13] Add dfs-search Widely used graph libraries like Boost Graph Library and graph-tool provide the ability to insert callback functions at specified event points for many common graph search algorithms. petgraph has a similar concept in `petgraph::visit::depth_first_search` function. This commit implements an iterative version of `depth_first_search`, that will be used in a follow-up in the pending PRs #444, #445. At the same time it exposes this new functionality in Python by letting users subclassing `retworkx.visit.DFSVisitor` and provide their own implementation for the appropriate callback functions. The benefit is less memory consumption since we avoid storing the results but rather let the user take the desired action at specified points. For example, if a user wants to process the nodes in dfs-order, we don't need to create a new list with all the graph nodes in dfs-order but rather the user can process a node on the fly. We can (probably) leverage this approach in other algorithms as an alternative for our inability to provide "real" python iterators. --- docs/source/api.rst | 4 + .../notes/dfs-search-6083680bf62356b0.yaml | 28 +++ retworkx/__init__.py | 71 +++++++ retworkx/visit.py | 58 ++++++ src/lib.rs | 2 + src/traversal/dfs_visit.rs | 195 ++++++++++++++++++ src/traversal/mod.rs | 148 +++++++++++++ 7 files changed, 506 insertions(+) create mode 100644 releasenotes/notes/dfs-search-6083680bf62356b0.yaml create mode 100644 retworkx/visit.py create mode 100644 src/traversal/dfs_visit.rs diff --git a/docs/source/api.rst b/docs/source/api.rst index d217e075b..51b094b0d 100644 --- a/docs/source/api.rst +++ b/docs/source/api.rst @@ -56,6 +56,7 @@ Traversal :toctree: stubs retworkx.dfs_edges + retworkx.dfs_search retworkx.bfs_successors retworkx.topological_sort retworkx.lexicographical_topological_sort @@ -63,6 +64,7 @@ Traversal retworkx.ancestors retworkx.collect_runs retworkx.collect_bicolor_runs + retworkx.visit.DFSVisitor .. _dag-algorithms: @@ -238,6 +240,7 @@ the functions from the explicitly typed based on the data type. retworkx.digraph_all_pairs_dijkstra_path_lengths retworkx.digraph_k_shortest_path_lengths retworkx.digraph_dfs_edges + retworkx.digraph_dfs_search retworkx.digraph_find_cycle retworkx.digraph_transitivity retworkx.digraph_core_number @@ -281,6 +284,7 @@ typed API based on the data type. retworkx.graph_k_shortest_path_lengths retworkx.graph_all_pairs_dijkstra_path_lengths retworkx.graph_dfs_edges + retworkx.graph_dfs_search retworkx.graph_transitivity retworkx.graph_core_number retworkx.graph_complement diff --git a/releasenotes/notes/dfs-search-6083680bf62356b0.yaml b/releasenotes/notes/dfs-search-6083680bf62356b0.yaml new file mode 100644 index 000000000..256f65247 --- /dev/null +++ b/releasenotes/notes/dfs-search-6083680bf62356b0.yaml @@ -0,0 +1,28 @@ +--- +features: + - | + Added a new :func:`~retworkx.dfs_search` (and it's per type variants + :func:`~retworkx.graph_dfs_search` and :func:`~retworkx.digraph_dfs_search`) + that traverses the graph in a depth-first manner and emits events at specified + points. The events are handled by a visitor object that subclasses + :class:`~retworkx.visit.DFSVisitor` through the appropriate callback functions. + For example: + + .. jupyter-execute:: + + import retworkx + from retworkx.visit import DFSVisitor + + class TreeEdgesRecorder(DFSVisitor): + + def __init__(self): + self.edges = [] + + def tree_edge(self, edge): + self.edges.append(edge) + + graph = retworkx.PyGraph() + graph.extend_from_edge_list([(1, 3), (0, 1), (2, 1), (0, 2)]) + vis = TreeEdgesRecorder() + retworkx.dfs_search(graph, 0, vis) + print('Tree edges:', vis.edges) diff --git a/retworkx/__init__.py b/retworkx/__init__.py index 784be4bc2..445f2efa2 100644 --- a/retworkx/__init__.py +++ b/retworkx/__init__.py @@ -1730,3 +1730,74 @@ def _graph_union( merge_edges=False, ): return graph_union(first, second, merge_nodes=False, merge_edges=False) + + +@functools.singledispatch +def dfs_search(graph, source, visitor): + """Depth-first traversal of a directed/undirected graph. + + The pseudo-code for the DFS algorithm is listed below, with the annotated + event points, for which the given visitor object will be called with the + appropriate method. + + :: + + DFS(G) + for each vertex u in V + color[u] := WHITE initialize vertex u + end for + time := 0 + call DFS-VISIT(G, source) start vertex s + + DFS-VISIT(G, u) + color[u] := GRAY discover vertex u + for each v in Adj[u] examine edge (u,v) + if (color[v] = WHITE) (u,v) is a tree edge + all DFS-VISIT(G, v) + else if (color[v] = GRAY) (u,v) is a back edge + ... + else if (color[v] = BLACK) (u,v) is a cross or forward edge + ... + end for + color[u] := BLACK finish vertex u + + In the following example we keep track of the tree edges: + + .. jupyter-execute:: + + import retworkx + from retworkx.visit import DFSVisitor + + class TreeEdgesRecorder(DFSVisitor): + + def __init__(self): + self.edges = [] + + def tree_edge(self, edge): + self.edges.append(edge) + + graph = retworkx.PyGraph() + graph.extend_from_edge_list([(1, 3), (0, 1), (2, 1), (0, 2)]) + vis = TreeEdgesRecorder() + retworkx.dfs_search(graph, 0, vis) + print('Tree edges:', vis.edges) + + :param PyGraph graph: The graph to be used. + :param int source: An optional node index to use as the starting node + for the depth-first search. If this is not specified then a source + will be chosen arbitrarly and repeated until all components of the + graph are searched. + :param visitor: A visitor object that is invoked at the event points inside the + algorithm. This should be a subclass of :class:`~retworkx.visit.DFSVisitor`. + """ + raise TypeError("Invalid Input Type %s for graph" % type(graph)) + + +@dfs_search.register(PyDiGraph) +def _digraph_dfs_search(graph, source, visitor): + return digraph_dfs_search(graph, source, visitor) + + +@dfs_search.register(PyGraph) +def _graph_dfs_search(graph, source, visitor): + return graph_dfs_search(graph, source, visitor) diff --git a/retworkx/visit.py b/retworkx/visit.py new file mode 100644 index 000000000..ed38ee5c1 --- /dev/null +++ b/retworkx/visit.py @@ -0,0 +1,58 @@ +# This code is licensed under the Apache License, Version 2.0. You may +# obtain a copy of this license in the LICENSE.txt file in the root directory +# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0. +# +# Any modifications or derivative works of this code must retain this +# copyright notice, and modified files need to carry a notice indicating +# that they have been altered from the originals. + + +class DFSVisitor: + """A visitor object that is invoked at the event-points inside the + :func:`~retworkx.dfs_search` algorithm. By default, it performs no + action, and should be used as a base class in order to be useful. + """ + + def discover_vertex(self, v, t): + """ + This is invoked when a vertex is encountered for the first time. + Together we report the discover time of vertex `v`. + """ + return + + def finish_vertex(self, v, t): + """ + This is invoked on vertex `v` after `finish_vertex` has been called for all + the vertices in the DFS-tree rooted at vertex u. If vertex `v` is a leaf in + the DFS-tree, then the `finish_vertex` function is called on `v` after all + the out-edges of `v` have been examined. Together we report the finish time + of vertex `v`. + """ + return + + def tree_edge(self, e): + """ + This is invoked on each edge as it becomes a member of the edges + that form the search tree. + """ + return + + def back_edge(self, e): + """ + This is invoked on the back edges in the graph. + For an undirected graph there is some ambiguity between tree edges + and back edges since the edge :math:`(u, v)` and :math:`(v, u)` are the + same edge, but both the `tree_edge()` and `back_edge()` functions will be + invoked. One way to resolve this ambiguity is to record the tree edges, + and then disregard the back-edges that are already marked as tree edges. + An easy way to record tree edges is to record predecessors at the + `tree_edge` event point. + """ + return + + def forward_or_cross_edge(self, e): + """ + This is invoked on forward or cross edges in the graph. + In an undirected graph this method is never called. + """ + return diff --git a/src/lib.rs b/src/lib.rs index f9ad455e3..1aa7735c3 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -292,6 +292,8 @@ fn retworkx(py: Python<'_>, m: &PyModule) -> PyResult<()> { ))?; m.add_wrapped(wrap_pyfunction!(metric_closure))?; m.add_wrapped(wrap_pyfunction!(steiner_tree))?; + m.add_wrapped(wrap_pyfunction!(digraph_dfs_search))?; + m.add_wrapped(wrap_pyfunction!(graph_dfs_search))?; m.add_class::()?; m.add_class::()?; m.add_class::()?; diff --git a/src/traversal/dfs_visit.rs b/src/traversal/dfs_visit.rs new file mode 100644 index 000000000..5be50e49c --- /dev/null +++ b/src/traversal/dfs_visit.rs @@ -0,0 +1,195 @@ +// Licensed under the Apache License, Version 2.0 (the "License"); you may +// not use this file except in compliance with the License. You may obtain +// a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +// License for the specific language governing permissions and limitations +// under the License. + +// This module is an iterative implementation of the upstream petgraph +// ``depth_first_search`` function. +// https://github.com/petgraph/petgraph/blob/0.6.0/src/visit/dfsvisit.rs + +use pyo3::prelude::*; + +use petgraph::stable_graph::NodeIndex; +use petgraph::visit::{ + ControlFlow, DfsEvent, IntoNeighbors, Time, VisitMap, Visitable, +}; + +/// Return if the expression is a break value, execute the provided statement +/// if it is a prune value. +/// https://github.com/petgraph/petgraph/blob/0.6.0/src/visit/dfsvisit.rs#L27 +macro_rules! try_control { + ($e:expr, $p:stmt) => { + try_control!($e, $p, ()); + }; + ($e:expr, $p:stmt, $q:stmt) => { + match $e { + x => { + if x.should_break() { + return x; + } else if x.should_prune() { + $p + } else { + $q + } + } + } + }; +} + +/// An iterative depth first search. +/// +/// Starting points are the nodes in the iterator `starts` (specify just one +/// start vertex *x* by using `Some(x)`). +/// +/// The traversal emits discovery and finish events for each reachable vertex, +/// and edge classification of each reachable edge. `visitor` is called for each +/// event, see `petgraph::DfsEvent` for possible values. +/// +/// The return value should implement the trait `ControlFlow`, and can be used to change +/// the control flow of the search. +/// +/// `Control` Implements `ControlFlow` such that `Control::Continue` resumes the search. +/// `Control::Break` will stop the visit early, returning the contained value. +/// `Control::Prune` will stop traversing any additional edges from the current +/// node and proceed immediately to the `Finish` event. +/// +/// There are implementations of `ControlFlow` for `()`, and `Result` where +/// `C: ControlFlow`. The implementation for `()` will continue until finished. +/// For `Result`, upon encountering an `E` it will break, otherwise acting the same as `C`. +/// +/// ***Panics** if you attempt to prune a node from its `Finish` event. +pub fn depth_first_search(graph: G, starts: I, mut visitor: F) -> C +where + G: IntoNeighbors + Visitable, + I: IntoIterator, + F: FnMut(DfsEvent) -> C, + C: ControlFlow, +{ + let time = &mut Time(0); + let discovered = &mut graph.visit_map(); + let finished = &mut graph.visit_map(); + + for start in starts { + try_control!( + dfs_visitor(graph, start, &mut visitor, discovered, finished, time), + unreachable!() + ); + } + C::continuing() +} + +fn dfs_visitor( + graph: G, + u: G::NodeId, + visitor: &mut F, + discovered: &mut G::Map, + finished: &mut G::Map, + time: &mut Time, +) -> C +where + G: IntoNeighbors + Visitable, + F: FnMut(DfsEvent) -> C, + C: ControlFlow, +{ + if !discovered.visit(u) { + return C::continuing(); + } + + try_control!(visitor(DfsEvent::Discover(u, time_post_inc(time))), {}, { + let mut stack: Vec<(G::NodeId, ::Neighbors)> = + Vec::new(); + stack.push((u, graph.neighbors(u))); + + while let Some(elem) = stack.last_mut() { + let u = elem.0; + let neighbors = &mut elem.1; + let mut next = None; + + for v in neighbors { + if !discovered.is_visited(&v) { + try_control!(visitor(DfsEvent::TreeEdge(u, v)), continue); + discovered.visit(v); + try_control!( + visitor(DfsEvent::Discover(v, time_post_inc(time))), + continue + ); + next = Some(v); + break; + } else if !finished.is_visited(&v) { + try_control!(visitor(DfsEvent::BackEdge(u, v)), continue); + } else { + try_control!( + visitor(DfsEvent::CrossForwardEdge(u, v)), + continue + ); + } + } + + match next { + Some(v) => stack.push((v, graph.neighbors(v))), + None => { + let first_finish = finished.visit(u); + debug_assert!(first_finish); + try_control!( + visitor(DfsEvent::Finish(u, time_post_inc(time))), + panic!("Pruning on the `DfsEvent::Finish` is not supported!") + ); + stack.pop(); + } + }; + } + }); + + C::continuing() +} + +fn time_post_inc(x: &mut Time) -> Time { + let v = *x; + x.0 += 1; + v +} + +#[derive(FromPyObject)] +pub struct PyDfsVisitor { + discover_vertex: PyObject, + finish_vertex: PyObject, + tree_edge: PyObject, + back_edge: PyObject, + forward_or_cross_edge: PyObject, +} + +pub fn handler( + py: Python, + vis: &PyDfsVisitor, + event: DfsEvent, +) -> PyResult<()> { + match event { + DfsEvent::Discover(u, Time(t)) => { + vis.discover_vertex.call1(py, (u.index(), t))?; + } + DfsEvent::TreeEdge(u, v) => { + let edge = (u.index(), v.index()); + vis.tree_edge.call1(py, (edge,))?; + } + DfsEvent::BackEdge(u, v) => { + let edge = (u.index(), v.index()); + vis.back_edge.call1(py, (edge,))?; + } + DfsEvent::CrossForwardEdge(u, v) => { + let edge = (u.index(), v.index()); + vis.forward_or_cross_edge.call1(py, (edge,))?; + } + DfsEvent::Finish(u, Time(t)) => { + vis.finish_vertex.call1(py, (u.index(), t))?; + } + } + + Ok(()) +} diff --git a/src/traversal/mod.rs b/src/traversal/mod.rs index c4b0b0fa2..44712e4c0 100644 --- a/src/traversal/mod.rs +++ b/src/traversal/mod.rs @@ -13,8 +13,10 @@ #![allow(clippy::float_cmp)] mod dfs_edges; +pub mod dfs_visit; use super::{digraph, graph, iterators}; +use dfs_visit::{depth_first_search, handler, PyDfsVisitor}; use hashbrown::HashSet; @@ -167,3 +169,149 @@ fn descendants(graph: &digraph::PyDiGraph, node: usize) -> HashSet { out_set.remove(&node); out_set } + +/// Depth-first traversal of a directed graph. +/// +/// The pseudo-code for the DFS algorithm is listed below, with the annotated +/// event points, for which the given visitor object will be called with the +/// appropriate method. +/// +/// :: +/// +/// DFS(G) +/// for each vertex u in V +/// color[u] := WHITE initialize vertex u +/// end for +/// time := 0 +/// call DFS-VISIT(G, source) start vertex s +/// +/// DFS-VISIT(G, u) +/// color[u] := GRAY discover vertex u +/// for each v in Adj[u] examine edge (u,v) +/// if (color[v] = WHITE) (u,v) is a tree edge +/// all DFS-VISIT(G, v) +/// else if (color[v] = GRAY) (u,v) is a back edge +/// ... +/// else if (color[v] = BLACK) (u,v) is a cross or forward edge +/// ... +/// end for +/// color[u] := BLACK finish vertex u +/// +/// In the following example we keep track of the tree edges: +/// +/// .. jupyter-execute:: +/// +/// import retworkx +/// from retworkx.visit import DFSVisitor +/// +/// class TreeEdgesRecorder(DFSVisitor): +/// +/// def __init__(self): +/// self.edges = [] +/// +/// def tree_edge(self, edge): +/// self.edges.append(edge) +/// +/// graph = retworkx.PyGraph() +/// graph.extend_from_edge_list([(1, 3), (0, 1), (2, 1), (0, 2)]) +/// vis = TreeEdgesRecorder() +/// retworkx.dfs_search(graph, 0, vis) +/// print('Tree edges:', vis.edges) +/// +/// :param PyDiGraph graph: The graph to be used. +/// :param int source: An optional node index to use as the starting node +/// for the depth-first search. If this is not specified then a source +/// will be chosen arbitrarly and repeated until all components of the +/// graph are searched. +/// :param visitor: A visitor object that is invoked at the event points inside the +/// algorithm. This should be a subclass of :class:`~retworkx.visit.DFSVisitor`. +#[pyfunction] +#[pyo3(text_signature = "(graph, source, visitor)")] +pub fn digraph_dfs_search( + py: Python, + graph: &digraph::PyDiGraph, + source: Option, + visitor: PyDfsVisitor, +) -> PyResult<()> { + let starts = match source { + Some(nx) => vec![NodeIndex::new(nx)], + None => graph.graph.node_indices().collect(), + }; + + depth_first_search(&graph.graph, starts, |event| { + handler(py, &visitor, event) + }) +} + +/// Depth-first traversal of an undirected graph. +/// +/// The pseudo-code for the DFS algorithm is listed below, with the annotated +/// event points, for which the given visitor object will be called with the +/// appropriate method. +/// +/// :: +/// +/// DFS(G) +/// for each vertex u in V +/// color[u] := WHITE initialize vertex u +/// end for +/// time := 0 +/// call DFS-VISIT(G, source) start vertex s +/// +/// DFS-VISIT(G, u) +/// color[u] := GRAY discover vertex u +/// for each v in Adj[u] examine edge (u,v) +/// if (color[v] = WHITE) (u,v) is a tree edge +/// all DFS-VISIT(G, v) +/// else if (color[v] = GRAY) (u,v) is a back edge +/// ... +/// else if (color[v] = BLACK) (u,v) is a cross or forward edge +/// ... +/// end for +/// color[u] := BLACK finish vertex u +/// +/// In the following example we keep track of the tree edges: +/// +/// .. jupyter-execute:: +/// +/// import retworkx +/// from retworkx.visit import DFSVisitor +/// +/// class TreeEdgesRecorder(DFSVisitor): +/// +/// def __init__(self): +/// self.edges = [] +/// +/// def tree_edge(self, edge): +/// self.edges.append(edge) +/// +/// graph = retworkx.PyGraph() +/// graph.extend_from_edge_list([(1, 3), (0, 1), (2, 1), (0, 2)]) +/// vis = TreeEdgesRecorder() +/// retworkx.dfs_search(graph, 0, vis) +/// print('Tree edges:', vis.edges) +/// +/// :param PyGraph graph: The graph to be used. +/// :param int source: An optional node index to use as the starting node +/// for the depth-first search. If this is not specified then a source +/// will be chosen arbitrarly and repeated until all components of the +/// graph are searched. +/// :param visitor: A visitor object that is invoked at the event points inside the +/// algorithm. This should be a subclass of :class:`~retworkx.visit.DFSVisitor`. +#[pyfunction] +#[pyo3(text_signature = "(graph, source, visitor)")] +pub fn graph_dfs_search( + py: Python, + graph: &graph::PyGraph, + source: Option, + visitor: PyDfsVisitor, +) -> PyResult<()> { + let starts = match source { + Some(nx) => vec![NodeIndex::new(nx)], + None => graph.graph.node_indices().collect(), + }; + + depth_first_search(&graph.graph, starts, |event| { + handler(py, &visitor, event) + }) +} From d480336c1c55981f8a62a21de6d127cee792fd1b Mon Sep 17 00:00:00 2001 From: georgios-ts Date: Tue, 28 Sep 2021 16:26:12 +0300 Subject: [PATCH 02/13] break or prune the search tree with custom exceptions --- docs/source/api.rst | 2 ++ retworkx/__init__.py | 13 +++++++++++++ retworkx/{visit.py => visitor.py} | 0 src/lib.rs | 12 ++++++++++++ src/traversal/dfs_visit.rs | 31 +++++++++++++++++++++---------- src/traversal/mod.rs | 26 ++++++++++++++++++++++++-- 6 files changed, 72 insertions(+), 12 deletions(-) rename retworkx/{visit.py => visitor.py} (100%) diff --git a/docs/source/api.rst b/docs/source/api.rst index 51b094b0d..f1563456c 100644 --- a/docs/source/api.rst +++ b/docs/source/api.rst @@ -312,6 +312,8 @@ Exceptions retworkx.NoSuitableNeighbors retworkx.NoPathFound retworkx.NullGraph + retworkx.visit.StopSearch + retworkx.visit.PruneSearch Custom Return Types =================== diff --git a/retworkx/__init__.py b/retworkx/__init__.py index 445f2efa2..ccff9ac80 100644 --- a/retworkx/__init__.py +++ b/retworkx/__init__.py @@ -11,8 +11,12 @@ import functools from .retworkx import * +from .visitor import DFSVisitor + +visit.DFSVisitor = DFSVisitor sys.modules["retworkx.generators"] = generators +sys.modules["retworkx.visit"] = visit class PyDAG(PyDiGraph): @@ -1761,6 +1765,11 @@ def dfs_search(graph, source, visitor): end for color[u] := BLACK finish vertex u + If an exception is raised inside the callback function, the graph traversal + will be stopped immediately. You can exploit this to exit early by raising a + :class:`~retworkx.visit.StopSearch` exception. You can also prune part of the + search tree by raising :class:`~retworkx.visit.PruneSearch`. + In the following example we keep track of the tree edges: .. jupyter-execute:: @@ -1782,6 +1791,10 @@ def tree_edge(self, edge): retworkx.dfs_search(graph, 0, vis) print('Tree edges:', vis.edges) + .. note:: + + Graph can *not* be mutated while traversing. + :param PyGraph graph: The graph to be used. :param int source: An optional node index to use as the starting node for the depth-first search. If this is not specified then a source diff --git a/retworkx/visit.py b/retworkx/visitor.py similarity index 100% rename from retworkx/visit.py rename to retworkx/visitor.py diff --git a/src/lib.rs b/src/lib.rs index 6b1ae6643..c123ec7e6 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -196,6 +196,17 @@ create_exception!(retworkx, NoSuitableNeighbors, PyException); create_exception!(retworkx, NullGraph, PyException); // No path was found between the specified nodes. create_exception!(retworkx, NoPathFound, PyException); +// Prune part of the search tree while traversing a graph. +create_exception!(retworkx, PruneSearch, PyException); +// Stop graph traversal. +create_exception!(retworkx, StopSearch, PyException); + +#[pymodule] +fn visit(py: Python, m: &PyModule) -> PyResult<()> { + m.add("StopSearch", py.get_type::())?; + m.add("PruneSearch", py.get_type::())?; + Ok(()) +} #[pymodule] fn retworkx(py: Python<'_>, m: &PyModule) -> PyResult<()> { @@ -318,5 +329,6 @@ fn retworkx(py: Python<'_>, m: &PyModule) -> PyResult<()> { m.add_class::()?; m.add_class::()?; m.add_wrapped(wrap_pymodule!(generators))?; + m.add_wrapped(wrap_pymodule!(visit))?; Ok(()) } diff --git a/src/traversal/dfs_visit.rs b/src/traversal/dfs_visit.rs index 5be50e49c..0f079e4ae 100644 --- a/src/traversal/dfs_visit.rs +++ b/src/traversal/dfs_visit.rs @@ -18,9 +18,11 @@ use pyo3::prelude::*; use petgraph::stable_graph::NodeIndex; use petgraph::visit::{ - ControlFlow, DfsEvent, IntoNeighbors, Time, VisitMap, Visitable, + Control, ControlFlow, DfsEvent, IntoNeighbors, Time, VisitMap, Visitable, }; +use crate::PruneSearch; + /// Return if the expression is a break value, execute the provided statement /// if it is a prune value. /// https://github.com/petgraph/petgraph/blob/0.6.0/src/visit/dfsvisit.rs#L27 @@ -169,27 +171,36 @@ pub fn handler( py: Python, vis: &PyDfsVisitor, event: DfsEvent, -) -> PyResult<()> { - match event { +) -> PyResult> { + let res = match event { DfsEvent::Discover(u, Time(t)) => { - vis.discover_vertex.call1(py, (u.index(), t))?; + vis.discover_vertex.call1(py, (u.index(), t)) } DfsEvent::TreeEdge(u, v) => { let edge = (u.index(), v.index()); - vis.tree_edge.call1(py, (edge,))?; + vis.tree_edge.call1(py, (edge,)) } DfsEvent::BackEdge(u, v) => { let edge = (u.index(), v.index()); - vis.back_edge.call1(py, (edge,))?; + vis.back_edge.call1(py, (edge,)) } DfsEvent::CrossForwardEdge(u, v) => { let edge = (u.index(), v.index()); - vis.forward_or_cross_edge.call1(py, (edge,))?; + vis.forward_or_cross_edge.call1(py, (edge,)) } DfsEvent::Finish(u, Time(t)) => { - vis.finish_vertex.call1(py, (u.index(), t))?; + vis.finish_vertex.call1(py, (u.index(), t)) } - } + }; - Ok(()) + match res { + Err(e) => { + if e.is_instance::(py) { + Ok(Control::Prune) + } else { + Err(e) + } + } + Ok(_) => Ok(Control::Continue), + } } diff --git a/src/traversal/mod.rs b/src/traversal/mod.rs index b0ec83651..e21a022fb 100644 --- a/src/traversal/mod.rs +++ b/src/traversal/mod.rs @@ -203,6 +203,11 @@ fn descendants(graph: &digraph::PyDiGraph, node: usize) -> HashSet { /// end for /// color[u] := BLACK finish vertex u /// +/// If an exception is raised inside the callback function, the graph traversal +/// will be stopped immediately. You can exploit this to exit early by raising a +/// :class:`~retworkx.visit.StopSearch` exception. You can also prune part of the +/// search tree by raising :class:`~retworkx.visit.PruneSearch`. +/// /// In the following example we keep track of the tree edges: /// /// .. jupyter-execute:: @@ -224,6 +229,10 @@ fn descendants(graph: &digraph::PyDiGraph, node: usize) -> HashSet { /// retworkx.dfs_search(graph, 0, vis) /// print('Tree edges:', vis.edges) /// +/// .. note:: +/// +/// Graph can *not* be mutated while traversing. +/// /// :param PyDiGraph graph: The graph to be used. /// :param int source: An optional node index to use as the starting node /// for the depth-first search. If this is not specified then a source @@ -246,7 +255,9 @@ pub fn digraph_dfs_search( depth_first_search(&graph.graph, starts, |event| { handler(py, &visitor, event) - }) + })?; + + Ok(()) } /// Depth-first traversal of an undirected graph. @@ -276,6 +287,11 @@ pub fn digraph_dfs_search( /// end for /// color[u] := BLACK finish vertex u /// +/// If an exception is raised inside the callback function, the graph traversal +/// will be stopped immediately. You can exploit this to exit early by raising a +/// :class:`~retworkx.visit.StopSearch` exception. You can also prune part of the +/// search tree by raising :class:`~retworkx.visit.PruneSearch`. +/// /// In the following example we keep track of the tree edges: /// /// .. jupyter-execute:: @@ -297,6 +313,10 @@ pub fn digraph_dfs_search( /// retworkx.dfs_search(graph, 0, vis) /// print('Tree edges:', vis.edges) /// +/// .. note:: +/// +/// Graph can *not* be mutated while traversing. +/// /// :param PyGraph graph: The graph to be used. /// :param int source: An optional node index to use as the starting node /// for the depth-first search. If this is not specified then a source @@ -319,5 +339,7 @@ pub fn graph_dfs_search( depth_first_search(&graph.graph, starts, |event| { handler(py, &visitor, event) - }) + })?; + + Ok(()) } From 11854114a51a8b90c8820914cf1995b44ca93e1f Mon Sep 17 00:00:00 2001 From: georgios-ts Date: Tue, 28 Sep 2021 16:37:08 +0300 Subject: [PATCH 03/13] tests --- tests/digraph/test_dfs_search.py | 107 +++++++++++++++++++++++++++++++ tests/graph/test_dfs_search.py | 107 +++++++++++++++++++++++++++++++ 2 files changed, 214 insertions(+) create mode 100644 tests/digraph/test_dfs_search.py create mode 100644 tests/graph/test_dfs_search.py diff --git a/tests/digraph/test_dfs_search.py b/tests/digraph/test_dfs_search.py new file mode 100644 index 000000000..2c0b68352 --- /dev/null +++ b/tests/digraph/test_dfs_search.py @@ -0,0 +1,107 @@ +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. + +import unittest + +import retworkx + + +class TestDfsSearch(unittest.TestCase): + def setUp(self): + self.graph = retworkx.PyDiGraph() + self.graph.extend_from_edge_list( + [ + (0, 1), + (0, 2), + (1, 3), + (2, 1), + (2, 5), + (2, 6), + (5, 3), + (4, 7), + ] + ) + + def test_digraph_dfs_tree_edges(self): + class TreeEdgesRecorder(retworkx.visit.DFSVisitor): + def __init__(self): + self.edges = [] + + def tree_edge(self, edge): + self.edges.append(edge) + + vis = TreeEdgesRecorder() + retworkx.digraph_dfs_search(self.graph, 0, vis) + self.assertEqual(vis.edges, [(0, 2), (2, 6), (2, 5), (5, 3), (2, 1)]) + + def test_digraph_dfs_tree_edges_no_starting_point(self): + class TreeEdgesRecorder(retworkx.visit.DFSVisitor): + def __init__(self): + self.edges = [] + + def tree_edge(self, edge): + self.edges.append(edge) + + vis = TreeEdgesRecorder() + retworkx.digraph_dfs_search(self.graph, None, vis) + self.assertEqual( + vis.edges, [(0, 2), (2, 6), (2, 5), (5, 3), (2, 1), (4, 7)] + ) + + def test_digraph_dfs_tree_edges_restricted(self): + class TreeEdgesRecorderRestricted(retworkx.visit.DFSVisitor): + + prohibited = [(0, 1), (5, 3)] + + def __init__(self): + self.edges = [] + + def tree_edge(self, edge): + if edge in self.prohibited: + raise retworkx.visit.PruneSearch + self.edges.append(edge) + + vis = TreeEdgesRecorderRestricted() + retworkx.digraph_dfs_search(self.graph, 0, vis) + self.assertEqual(vis.edges, [(0, 2), (2, 6), (2, 5), (2, 1), (1, 3)]) + + def test_digraph_dfs_goal_search(self): + class GoalSearch(retworkx.visit.DFSVisitor): + + goal = 3 + + def __init__(self): + self.parents = {} + + def tree_edge(self, edge): + u, v = edge + self.parents[v] = u + + if v == self.goal: + raise retworkx.visit.StopSearch + + def reconstruct_path(self): + v = self.goal + path = [v] + while v in self.parents: + v = self.parents[v] + path.append(v) + + path.reverse() + return path + + vis = GoalSearch() + try: + retworkx.digraph_dfs_search(self.graph, 0, vis) + except retworkx.visit.StopSearch: + pass + self.assertEqual(vis.reconstruct_path(), [0, 2, 5, 3]) diff --git a/tests/graph/test_dfs_search.py b/tests/graph/test_dfs_search.py new file mode 100644 index 000000000..cb26b3189 --- /dev/null +++ b/tests/graph/test_dfs_search.py @@ -0,0 +1,107 @@ +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. + +import unittest + +import retworkx + + +class TestDfsSearch(unittest.TestCase): + def setUp(self): + self.graph = retworkx.PyGraph() + self.graph.extend_from_edge_list( + [ + (0, 1), + (0, 2), + (1, 3), + (2, 1), + (2, 5), + (2, 6), + (5, 3), + (4, 7), + ] + ) + + def test_graph_dfs_tree_edges(self): + class TreeEdgesRecorder(retworkx.visit.DFSVisitor): + def __init__(self): + self.edges = [] + + def tree_edge(self, edge): + self.edges.append(edge) + + vis = TreeEdgesRecorder() + retworkx.graph_dfs_search(self.graph, 0, vis) + self.assertEqual(vis.edges, [(0, 2), (2, 6), (2, 5), (5, 3), (3, 1)]) + + def test_graph_dfs_tree_edges_no_starting_point(self): + class TreeEdgesRecorder(retworkx.visit.DFSVisitor): + def __init__(self): + self.edges = [] + + def tree_edge(self, edge): + self.edges.append(edge) + + vis = TreeEdgesRecorder() + retworkx.graph_dfs_search(self.graph, None, vis) + self.assertEqual( + vis.edges, [(0, 2), (2, 6), (2, 5), (5, 3), (3, 1), (4, 7)] + ) + + def test_graph_dfs_tree_edges_restricted(self): + class TreeEdgesRecorderRestricted(retworkx.visit.DFSVisitor): + + prohibited = [(0, 2), (1, 2)] + + def __init__(self): + self.edges = [] + + def tree_edge(self, edge): + if edge in self.prohibited: + raise retworkx.visit.PruneSearch + self.edges.append(edge) + + vis = TreeEdgesRecorderRestricted() + retworkx.graph_dfs_search(self.graph, 0, vis) + self.assertEqual(vis.edges, [(0, 1), (1, 3), (3, 5), (5, 2), (2, 6)]) + + def test_graph_dfs_goal_search(self): + class GoalSearch(retworkx.visit.DFSVisitor): + + goal = 3 + + def __init__(self): + self.parents = {} + + def tree_edge(self, edge): + u, v = edge + self.parents[v] = u + + if v == self.goal: + raise retworkx.visit.StopSearch + + def reconstruct_path(self): + v = self.goal + path = [v] + while v in self.parents: + v = self.parents[v] + path.append(v) + + path.reverse() + return path + + vis = GoalSearch() + try: + retworkx.graph_dfs_search(self.graph, 0, vis) + except retworkx.visit.StopSearch: + pass + self.assertEqual(vis.reconstruct_path(), [0, 2, 5, 3]) From 883316983f32f4ed2813af3365a17c59a3300ca7 Mon Sep 17 00:00:00 2001 From: georgios-ts Date: Wed, 13 Oct 2021 20:34:18 +0300 Subject: [PATCH 04/13] move `depth_first_search` to retworkx-core + create a new traversal module together with `dfs_edges` function --- retworkx-core/src/lib.rs | 3 +- .../src/{ => traversal}/dfs_edges.rs | 2 +- retworkx-core/src/traversal/dfs_visit.rs | 240 ++++++++++++++++++ retworkx-core/src/traversal/mod.rs | 19 ++ src/traversal/dfs_visit.rs | 139 +--------- src/traversal/mod.rs | 9 +- 6 files changed, 267 insertions(+), 145 deletions(-) rename retworkx-core/src/{ => traversal}/dfs_edges.rs (98%) create mode 100644 retworkx-core/src/traversal/dfs_visit.rs create mode 100644 retworkx-core/src/traversal/mod.rs diff --git a/retworkx-core/src/lib.rs b/retworkx-core/src/lib.rs index 9275981a7..e4b1c7eeb 100644 --- a/retworkx-core/src/lib.rs +++ b/retworkx-core/src/lib.rs @@ -68,11 +68,10 @@ pub type Result = core::result::Result; /// Module for centrality algorithms pub mod centrality; -/// Module for depth first search edge methods -pub mod dfs_edges; /// Module for maximum weight matching algorithmss pub mod max_weight_matching; pub mod shortest_path; +pub mod traversal; // These modules define additional data structures pub mod dictmap; mod min_scored; diff --git a/retworkx-core/src/dfs_edges.rs b/retworkx-core/src/traversal/dfs_edges.rs similarity index 98% rename from retworkx-core/src/dfs_edges.rs rename to retworkx-core/src/traversal/dfs_edges.rs index 906cd8805..ec4b39b8c 100644 --- a/retworkx-core/src/dfs_edges.rs +++ b/retworkx-core/src/traversal/dfs_edges.rs @@ -32,7 +32,7 @@ use petgraph::visit::{ /// # Example /// ```rust /// use retworkx_core::petgraph; -/// use retworkx_core::dfs_edges::dfs_edges; +/// use retworkx_core::traversal::dfs_edges; /// /// let g = petgraph::graph::UnGraph::::from_edges(&[ /// (0, 1), (1, 2), (1, 3), (2, 4), (3, 4) diff --git a/retworkx-core/src/traversal/dfs_visit.rs b/retworkx-core/src/traversal/dfs_visit.rs new file mode 100644 index 000000000..d2bdf38ae --- /dev/null +++ b/retworkx-core/src/traversal/dfs_visit.rs @@ -0,0 +1,240 @@ +// Licensed under the Apache License, Version 2.0 (the "License"); you may +// not use this file except in compliance with the License. You may obtain +// a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +// License for the specific language governing permissions and limitations +// under the License. + +// This module is an iterative implementation of the upstream petgraph +// ``depth_first_search`` function. +// https://github.com/petgraph/petgraph/blob/0.6.0/src/visit/dfsvisit.rs + +use petgraph::visit::{ + ControlFlow, DfsEvent, IntoNeighbors, Time, VisitMap, Visitable, +}; + +/// Return if the expression is a break value, execute the provided statement +/// if it is a prune value. +/// https://github.com/petgraph/petgraph/blob/0.6.0/src/visit/dfsvisit.rs#L27 +macro_rules! try_control { + ($e:expr, $p:stmt) => { + try_control!($e, $p, ()); + }; + ($e:expr, $p:stmt, $q:stmt) => { + match $e { + x => { + if x.should_break() { + return x; + } else if x.should_prune() { + $p + } else { + $q + } + } + } + }; +} + +/// An iterative depth first search. +/// +/// It is an iterative implementation of the upstream petgraph +/// [`depth_first_search`](https://docs.rs/petgraph/0.6.0/petgraph/visit/fn.depth_first_search.html) function. +/// +/// Starting points are the nodes in the iterator `starts` (specify just one +/// start vertex *x* by using `Some(x)`). +/// +/// The traversal emits discovery and finish events for each reachable vertex, +/// and edge classification of each reachable edge. `visitor` is called for each +/// event, see `petgraph::DfsEvent` for possible values. +/// +/// The return value should implement the trait `ControlFlow`, and can be used to change +/// the control flow of the search. +/// +/// `Control` Implements `ControlFlow` such that `Control::Continue` resumes the search. +/// `Control::Break` will stop the visit early, returning the contained value. +/// `Control::Prune` will stop traversing any additional edges from the current +/// node and proceed immediately to the `Finish` event. +/// +/// There are implementations of `ControlFlow` for `()`, and `Result` where +/// `C: ControlFlow`. The implementation for `()` will continue until finished. +/// For `Result`, upon encountering an `E` it will break, otherwise acting the same as `C`. +/// +/// ***Panics** if you attempt to prune a node from its `Finish` event. +/// +/// # Example returning `Control`. +/// +/// Find a path from vertex 0 to 5, and exit the visit as soon as we reach +/// the goal vertex. +/// +/// ``` +/// use retworkx_core::petgraph::prelude::*; +/// use retworkx_core::petgraph::graph::node_index as n; +/// use retworkx_core::petgraph::visit::depth_first_search; +/// use retworkx_core::petgraph::visit::{DfsEvent, Control}; +/// +/// let gr: Graph<(), ()> = Graph::from_edges(&[ +/// (0, 1), (0, 2), (0, 3), +/// (1, 3), +/// (2, 3), (2, 4), +/// (4, 0), (4, 5), +/// ]); +/// +/// // record each predecessor, mapping node → node +/// let mut predecessor = vec![NodeIndex::end(); gr.node_count()]; +/// let start = n(0); +/// let goal = n(5); +/// depth_first_search(&gr, Some(start), |event| { +/// if let DfsEvent::TreeEdge(u, v) = event { +/// predecessor[v.index()] = u; +/// if v == goal { +/// return Control::Break(v); +/// } +/// } +/// Control::Continue +/// }); +/// +/// let mut next = goal; +/// let mut path = vec![next]; +/// while next != start { +/// let pred = predecessor[next.index()]; +/// path.push(pred); +/// next = pred; +/// } +/// path.reverse(); +/// assert_eq!(&path, &[n(0), n(2), n(4), n(5)]); +/// ``` +/// +/// # Example returning a `Result`. +/// ``` +/// use retworkx_core::petgraph::graph::node_index as n; +/// use retworkx_core::petgraph::prelude::*; +/// use retworkx_core::petgraph::visit::depth_first_search; +/// use retworkx_core::petgraph::visit::{DfsEvent, Time}; +/// +/// let gr: Graph<(), ()> = Graph::from_edges(&[(0, 1), (1, 2), (1, 1), (2, 1)]); +/// let start = n(0); +/// let mut back_edges = 0; +/// let mut discover_time = 0; +/// // Stop the search, the first time a BackEdge is encountered. +/// let result = depth_first_search(&gr, Some(start), |event| { +/// match event { +/// // In the cases where Ok(()) is returned, +/// // Result falls back to the implementation of Control on the value (). +/// // In the case of (), this is to always return Control::Continue. +/// // continuing the search. +/// DfsEvent::Discover(_, Time(t)) => { +/// discover_time = t; +/// Ok(()) +/// } +/// DfsEvent::BackEdge(_, _) => { +/// back_edges += 1; +/// // the implementation of ControlFlow for Result, +/// // treats this Err value as Continue::Break +/// Err(event) +/// } +/// _ => Ok(()), +/// } +/// }); +/// +/// // Even though the graph has more than one cycle, +/// // The number of back_edges visited by the search should always be 1. +/// assert_eq!(back_edges, 1); +/// println!("discover time:{:?}", discover_time); +/// println!("number of backedges encountered: {}", back_edges); +/// println!("back edge: {:?}", result); +/// ``` +pub fn depth_first_search(graph: G, starts: I, mut visitor: F) -> C +where + G: IntoNeighbors + Visitable, + I: IntoIterator, + F: FnMut(DfsEvent) -> C, + C: ControlFlow, +{ + let time = &mut Time(0); + let discovered = &mut graph.visit_map(); + let finished = &mut graph.visit_map(); + + for start in starts { + try_control!( + dfs_visitor(graph, start, &mut visitor, discovered, finished, time), + unreachable!() + ); + } + C::continuing() +} + +fn dfs_visitor( + graph: G, + u: G::NodeId, + visitor: &mut F, + discovered: &mut G::Map, + finished: &mut G::Map, + time: &mut Time, +) -> C +where + G: IntoNeighbors + Visitable, + F: FnMut(DfsEvent) -> C, + C: ControlFlow, +{ + if !discovered.visit(u) { + return C::continuing(); + } + + try_control!(visitor(DfsEvent::Discover(u, time_post_inc(time))), {}, { + let mut stack: Vec<(G::NodeId, ::Neighbors)> = + Vec::new(); + stack.push((u, graph.neighbors(u))); + + while let Some(elem) = stack.last_mut() { + let u = elem.0; + let neighbors = &mut elem.1; + let mut next = None; + + for v in neighbors { + if !discovered.is_visited(&v) { + try_control!(visitor(DfsEvent::TreeEdge(u, v)), continue); + discovered.visit(v); + try_control!( + visitor(DfsEvent::Discover(v, time_post_inc(time))), + continue + ); + next = Some(v); + break; + } else if !finished.is_visited(&v) { + try_control!(visitor(DfsEvent::BackEdge(u, v)), continue); + } else { + try_control!( + visitor(DfsEvent::CrossForwardEdge(u, v)), + continue + ); + } + } + + match next { + Some(v) => stack.push((v, graph.neighbors(v))), + None => { + let first_finish = finished.visit(u); + debug_assert!(first_finish); + try_control!( + visitor(DfsEvent::Finish(u, time_post_inc(time))), + panic!("Pruning on the `DfsEvent::Finish` is not supported!") + ); + stack.pop(); + } + }; + } + }); + + C::continuing() +} + +fn time_post_inc(x: &mut Time) -> Time { + let v = *x; + x.0 += 1; + v +} diff --git a/retworkx-core/src/traversal/mod.rs b/retworkx-core/src/traversal/mod.rs new file mode 100644 index 000000000..329811cfc --- /dev/null +++ b/retworkx-core/src/traversal/mod.rs @@ -0,0 +1,19 @@ +// Licensed under the Apache License, Version 2.0 (the "License"); you may +// not use this file except in compliance with the License. You may obtain +// a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +// License for the specific language governing permissions and limitations +// under the License. + +//! Module for graph traversal algorithms. + +mod dfs_edges; +mod dfs_visit; + +pub use dfs_edges::dfs_edges; +pub use dfs_visit::depth_first_search; diff --git a/src/traversal/dfs_visit.rs b/src/traversal/dfs_visit.rs index 0f079e4ae..e07e0987d 100644 --- a/src/traversal/dfs_visit.rs +++ b/src/traversal/dfs_visit.rs @@ -17,147 +17,10 @@ use pyo3::prelude::*; use petgraph::stable_graph::NodeIndex; -use petgraph::visit::{ - Control, ControlFlow, DfsEvent, IntoNeighbors, Time, VisitMap, Visitable, -}; +use petgraph::visit::{Control, DfsEvent, Time}; use crate::PruneSearch; -/// Return if the expression is a break value, execute the provided statement -/// if it is a prune value. -/// https://github.com/petgraph/petgraph/blob/0.6.0/src/visit/dfsvisit.rs#L27 -macro_rules! try_control { - ($e:expr, $p:stmt) => { - try_control!($e, $p, ()); - }; - ($e:expr, $p:stmt, $q:stmt) => { - match $e { - x => { - if x.should_break() { - return x; - } else if x.should_prune() { - $p - } else { - $q - } - } - } - }; -} - -/// An iterative depth first search. -/// -/// Starting points are the nodes in the iterator `starts` (specify just one -/// start vertex *x* by using `Some(x)`). -/// -/// The traversal emits discovery and finish events for each reachable vertex, -/// and edge classification of each reachable edge. `visitor` is called for each -/// event, see `petgraph::DfsEvent` for possible values. -/// -/// The return value should implement the trait `ControlFlow`, and can be used to change -/// the control flow of the search. -/// -/// `Control` Implements `ControlFlow` such that `Control::Continue` resumes the search. -/// `Control::Break` will stop the visit early, returning the contained value. -/// `Control::Prune` will stop traversing any additional edges from the current -/// node and proceed immediately to the `Finish` event. -/// -/// There are implementations of `ControlFlow` for `()`, and `Result` where -/// `C: ControlFlow`. The implementation for `()` will continue until finished. -/// For `Result`, upon encountering an `E` it will break, otherwise acting the same as `C`. -/// -/// ***Panics** if you attempt to prune a node from its `Finish` event. -pub fn depth_first_search(graph: G, starts: I, mut visitor: F) -> C -where - G: IntoNeighbors + Visitable, - I: IntoIterator, - F: FnMut(DfsEvent) -> C, - C: ControlFlow, -{ - let time = &mut Time(0); - let discovered = &mut graph.visit_map(); - let finished = &mut graph.visit_map(); - - for start in starts { - try_control!( - dfs_visitor(graph, start, &mut visitor, discovered, finished, time), - unreachable!() - ); - } - C::continuing() -} - -fn dfs_visitor( - graph: G, - u: G::NodeId, - visitor: &mut F, - discovered: &mut G::Map, - finished: &mut G::Map, - time: &mut Time, -) -> C -where - G: IntoNeighbors + Visitable, - F: FnMut(DfsEvent) -> C, - C: ControlFlow, -{ - if !discovered.visit(u) { - return C::continuing(); - } - - try_control!(visitor(DfsEvent::Discover(u, time_post_inc(time))), {}, { - let mut stack: Vec<(G::NodeId, ::Neighbors)> = - Vec::new(); - stack.push((u, graph.neighbors(u))); - - while let Some(elem) = stack.last_mut() { - let u = elem.0; - let neighbors = &mut elem.1; - let mut next = None; - - for v in neighbors { - if !discovered.is_visited(&v) { - try_control!(visitor(DfsEvent::TreeEdge(u, v)), continue); - discovered.visit(v); - try_control!( - visitor(DfsEvent::Discover(v, time_post_inc(time))), - continue - ); - next = Some(v); - break; - } else if !finished.is_visited(&v) { - try_control!(visitor(DfsEvent::BackEdge(u, v)), continue); - } else { - try_control!( - visitor(DfsEvent::CrossForwardEdge(u, v)), - continue - ); - } - } - - match next { - Some(v) => stack.push((v, graph.neighbors(v))), - None => { - let first_finish = finished.visit(u); - debug_assert!(first_finish); - try_control!( - visitor(DfsEvent::Finish(u, time_post_inc(time))), - panic!("Pruning on the `DfsEvent::Finish` is not supported!") - ); - stack.pop(); - } - }; - } - }); - - C::continuing() -} - -fn time_post_inc(x: &mut Time) -> Time { - let v = *x; - x.0 += 1; - v -} - #[derive(FromPyObject)] pub struct PyDfsVisitor { discover_vertex: PyObject, diff --git a/src/traversal/mod.rs b/src/traversal/mod.rs index c9bfebe28..15cbd09e7 100644 --- a/src/traversal/mod.rs +++ b/src/traversal/mod.rs @@ -11,10 +11,11 @@ // under the License. pub mod dfs_visit; -use retworkx_core::dfs_edges; + +use retworkx_core::traversal::{depth_first_search, dfs_edges}; use super::{digraph, graph, iterators}; -use dfs_visit::{depth_first_search, handler, PyDfsVisitor}; +use dfs_visit::{handler, PyDfsVisitor}; use hashbrown::HashSet; @@ -46,7 +47,7 @@ fn digraph_dfs_edges( source: Option, ) -> EdgeList { EdgeList { - edges: dfs_edges::dfs_edges(&graph.graph, source.map(NodeIndex::new)), + edges: dfs_edges(&graph.graph, source.map(NodeIndex::new)), } } @@ -66,7 +67,7 @@ fn digraph_dfs_edges( #[pyo3(text_signature = "(graph, /, source=None)")] fn graph_dfs_edges(graph: &graph::PyGraph, source: Option) -> EdgeList { EdgeList { - edges: dfs_edges::dfs_edges(&graph.graph, source.map(NodeIndex::new)), + edges: dfs_edges(&graph.graph, source.map(NodeIndex::new)), } } From 587ca31c34aab244092247c64f7b412b5195ef7d Mon Sep 17 00:00:00 2001 From: georgios-ts Date: Mon, 18 Oct 2021 17:53:47 +0300 Subject: [PATCH 05/13] add option to pass a vector of starting nodes + in dfs events report the weight of an edge --- .../notes/dfs-search-6083680bf62356b0.yaml | 2 +- retworkx-core/src/traversal/dfs_visit.rs | 80 ++++++++++++++----- retworkx-core/src/traversal/mod.rs | 2 +- retworkx/__init__.py | 2 +- src/traversal/dfs_visit.rs | 17 ++-- src/traversal/mod.rs | 16 ++-- tests/digraph/test_dfs_search.py | 13 +-- tests/graph/test_dfs_search.py | 13 +-- 8 files changed, 92 insertions(+), 53 deletions(-) diff --git a/releasenotes/notes/dfs-search-6083680bf62356b0.yaml b/releasenotes/notes/dfs-search-6083680bf62356b0.yaml index 256f65247..c2d74e721 100644 --- a/releasenotes/notes/dfs-search-6083680bf62356b0.yaml +++ b/releasenotes/notes/dfs-search-6083680bf62356b0.yaml @@ -24,5 +24,5 @@ features: graph = retworkx.PyGraph() graph.extend_from_edge_list([(1, 3), (0, 1), (2, 1), (0, 2)]) vis = TreeEdgesRecorder() - retworkx.dfs_search(graph, 0, vis) + retworkx.dfs_search(graph, [0], vis) print('Tree edges:', vis.edges) diff --git a/retworkx-core/src/traversal/dfs_visit.rs b/retworkx-core/src/traversal/dfs_visit.rs index d2bdf38ae..e92b67748 100644 --- a/retworkx-core/src/traversal/dfs_visit.rs +++ b/retworkx-core/src/traversal/dfs_visit.rs @@ -15,7 +15,7 @@ // https://github.com/petgraph/petgraph/blob/0.6.0/src/visit/dfsvisit.rs use petgraph::visit::{ - ControlFlow, DfsEvent, IntoNeighbors, Time, VisitMap, Visitable, + ControlFlow, EdgeRef, IntoEdges, Time, VisitMap, Visitable, }; /// Return if the expression is a break value, execute the provided statement @@ -40,6 +40,23 @@ macro_rules! try_control { }; } +/// A depth first search (DFS) visitor event. +#[derive(Copy, Clone, Debug)] +pub enum DfsEvent { + Discover(N, Time), + /// An edge of the tree formed by the traversal. + TreeEdge(N, N, E), + /// An edge to an already visited node. + BackEdge(N, N, E), + /// A cross or forward edge. + /// + /// For an edge *(u, v)*, if the discover time of *v* is greater than *u*, + /// then it is a forward edge, else a cross edge. + CrossForwardEdge(N, N, E), + /// All edges from a node have been reported. + Finish(N, Time), +} + /// An iterative depth first search. /// /// It is an iterative implementation of the upstream petgraph @@ -74,8 +91,9 @@ macro_rules! try_control { /// ``` /// use retworkx_core::petgraph::prelude::*; /// use retworkx_core::petgraph::graph::node_index as n; -/// use retworkx_core::petgraph::visit::depth_first_search; -/// use retworkx_core::petgraph::visit::{DfsEvent, Control}; +/// use retworkx_core::petgraph::visit::Control; +/// +/// use retworkx_core::traversal::{DfsEvent, depth_first_search}; /// /// let gr: Graph<(), ()> = Graph::from_edges(&[ /// (0, 1), (0, 2), (0, 3), @@ -89,7 +107,7 @@ macro_rules! try_control { /// let start = n(0); /// let goal = n(5); /// depth_first_search(&gr, Some(start), |event| { -/// if let DfsEvent::TreeEdge(u, v) = event { +/// if let DfsEvent::TreeEdge(u, v, _) = event { /// predecessor[v.index()] = u; /// if v == goal { /// return Control::Break(v); @@ -113,13 +131,21 @@ macro_rules! try_control { /// ``` /// use retworkx_core::petgraph::graph::node_index as n; /// use retworkx_core::petgraph::prelude::*; -/// use retworkx_core::petgraph::visit::depth_first_search; -/// use retworkx_core::petgraph::visit::{DfsEvent, Time}; +/// use retworkx_core::petgraph::visit::Time; +/// +/// use retworkx_core::traversal::{DfsEvent, depth_first_search}; /// /// let gr: Graph<(), ()> = Graph::from_edges(&[(0, 1), (1, 2), (1, 1), (2, 1)]); /// let start = n(0); /// let mut back_edges = 0; /// let mut discover_time = 0; +/// +/// #[derive(Debug)] +/// struct BackEdgeFound { +/// source: NodeIndex, +/// target: NodeIndex, +/// } +/// /// // Stop the search, the first time a BackEdge is encountered. /// let result = depth_first_search(&gr, Some(start), |event| { /// match event { @@ -131,11 +157,11 @@ macro_rules! try_control { /// discover_time = t; /// Ok(()) /// } -/// DfsEvent::BackEdge(_, _) => { +/// DfsEvent::BackEdge(u, v, _) => { /// back_edges += 1; /// // the implementation of ControlFlow for Result, /// // treats this Err value as Continue::Break -/// Err(event) +/// Err(BackEdgeFound {source: u, target: v}) /// } /// _ => Ok(()), /// } @@ -146,13 +172,13 @@ macro_rules! try_control { /// assert_eq!(back_edges, 1); /// println!("discover time:{:?}", discover_time); /// println!("number of backedges encountered: {}", back_edges); -/// println!("back edge: {:?}", result); +/// println!("back edge: ({:?})", result.unwrap_err()); /// ``` pub fn depth_first_search(graph: G, starts: I, mut visitor: F) -> C where - G: IntoNeighbors + Visitable, + G: IntoEdges + Visitable, I: IntoIterator, - F: FnMut(DfsEvent) -> C, + F: FnMut(DfsEvent) -> C, C: ControlFlow, { let time = &mut Time(0); @@ -177,8 +203,8 @@ fn dfs_visitor( time: &mut Time, ) -> C where - G: IntoNeighbors + Visitable, - F: FnMut(DfsEvent) -> C, + G: IntoEdges + Visitable, + F: FnMut(DfsEvent) -> C, C: ControlFlow, { if !discovered.visit(u) { @@ -186,18 +212,21 @@ where } try_control!(visitor(DfsEvent::Discover(u, time_post_inc(time))), {}, { - let mut stack: Vec<(G::NodeId, ::Neighbors)> = - Vec::new(); - stack.push((u, graph.neighbors(u))); + let mut stack: Vec<(G::NodeId, ::Edges)> = Vec::new(); + stack.push((u, graph.edges(u))); while let Some(elem) = stack.last_mut() { let u = elem.0; - let neighbors = &mut elem.1; + let adjacent_edges = &mut elem.1; let mut next = None; - for v in neighbors { + for edge in adjacent_edges { + let v = edge.target(); if !discovered.is_visited(&v) { - try_control!(visitor(DfsEvent::TreeEdge(u, v)), continue); + try_control!( + visitor(DfsEvent::TreeEdge(u, v, edge.weight())), + continue + ); discovered.visit(v); try_control!( visitor(DfsEvent::Discover(v, time_post_inc(time))), @@ -206,17 +235,24 @@ where next = Some(v); break; } else if !finished.is_visited(&v) { - try_control!(visitor(DfsEvent::BackEdge(u, v)), continue); + try_control!( + visitor(DfsEvent::BackEdge(u, v, edge.weight())), + continue + ); } else { try_control!( - visitor(DfsEvent::CrossForwardEdge(u, v)), + visitor(DfsEvent::CrossForwardEdge( + u, + v, + edge.weight() + )), continue ); } } match next { - Some(v) => stack.push((v, graph.neighbors(v))), + Some(v) => stack.push((v, graph.edges(v))), None => { let first_finish = finished.visit(u); debug_assert!(first_finish); diff --git a/retworkx-core/src/traversal/mod.rs b/retworkx-core/src/traversal/mod.rs index 329811cfc..28f40b0a6 100644 --- a/retworkx-core/src/traversal/mod.rs +++ b/retworkx-core/src/traversal/mod.rs @@ -16,4 +16,4 @@ mod dfs_edges; mod dfs_visit; pub use dfs_edges::dfs_edges; -pub use dfs_visit::depth_first_search; +pub use dfs_visit::{depth_first_search, DfsEvent}; diff --git a/retworkx/__init__.py b/retworkx/__init__.py index ccff9ac80..5c6b327ba 100644 --- a/retworkx/__init__.py +++ b/retworkx/__init__.py @@ -1796,7 +1796,7 @@ def tree_edge(self, edge): Graph can *not* be mutated while traversing. :param PyGraph graph: The graph to be used. - :param int source: An optional node index to use as the starting node + :param List[int] source: An optional list of node indices to use as the starting nodes for the depth-first search. If this is not specified then a source will be chosen arbitrarly and repeated until all components of the graph are searched. diff --git a/src/traversal/dfs_visit.rs b/src/traversal/dfs_visit.rs index e07e0987d..50718e7fd 100644 --- a/src/traversal/dfs_visit.rs +++ b/src/traversal/dfs_visit.rs @@ -17,9 +17,10 @@ use pyo3::prelude::*; use petgraph::stable_graph::NodeIndex; -use petgraph::visit::{Control, DfsEvent, Time}; +use petgraph::visit::{Control, Time}; use crate::PruneSearch; +use retworkx_core::traversal::DfsEvent; #[derive(FromPyObject)] pub struct PyDfsVisitor { @@ -33,22 +34,22 @@ pub struct PyDfsVisitor { pub fn handler( py: Python, vis: &PyDfsVisitor, - event: DfsEvent, + event: DfsEvent, ) -> PyResult> { let res = match event { DfsEvent::Discover(u, Time(t)) => { vis.discover_vertex.call1(py, (u.index(), t)) } - DfsEvent::TreeEdge(u, v) => { - let edge = (u.index(), v.index()); + DfsEvent::TreeEdge(u, v, weight) => { + let edge = (u.index(), v.index(), weight); vis.tree_edge.call1(py, (edge,)) } - DfsEvent::BackEdge(u, v) => { - let edge = (u.index(), v.index()); + DfsEvent::BackEdge(u, v, weight) => { + let edge = (u.index(), v.index(), weight); vis.back_edge.call1(py, (edge,)) } - DfsEvent::CrossForwardEdge(u, v) => { - let edge = (u.index(), v.index()); + DfsEvent::CrossForwardEdge(u, v, weight) => { + let edge = (u.index(), v.index(), weight); vis.forward_or_cross_edge.call1(py, (edge,)) } DfsEvent::Finish(u, Time(t)) => { diff --git a/src/traversal/mod.rs b/src/traversal/mod.rs index 15cbd09e7..a3aa3370b 100644 --- a/src/traversal/mod.rs +++ b/src/traversal/mod.rs @@ -227,7 +227,7 @@ fn descendants(graph: &digraph::PyDiGraph, node: usize) -> HashSet { /// Graph can *not* be mutated while traversing. /// /// :param PyDiGraph graph: The graph to be used. -/// :param int source: An optional node index to use as the starting node +/// :param List[int] source: An optional list of node indices to use as the starting nodes /// for the depth-first search. If this is not specified then a source /// will be chosen arbitrarly and repeated until all components of the /// graph are searched. @@ -238,11 +238,11 @@ fn descendants(graph: &digraph::PyDiGraph, node: usize) -> HashSet { pub fn digraph_dfs_search( py: Python, graph: &digraph::PyDiGraph, - source: Option, + source: Option>, visitor: PyDfsVisitor, ) -> PyResult<()> { - let starts = match source { - Some(nx) => vec![NodeIndex::new(nx)], + let starts: Vec<_> = match source { + Some(nx) => nx.into_iter().map(NodeIndex::new).collect(), None => graph.graph.node_indices().collect(), }; @@ -311,7 +311,7 @@ pub fn digraph_dfs_search( /// Graph can *not* be mutated while traversing. /// /// :param PyGraph graph: The graph to be used. -/// :param int source: An optional node index to use as the starting node +/// :param List[int] source: An optional list of node indices to use as the starting nodes /// for the depth-first search. If this is not specified then a source /// will be chosen arbitrarly and repeated until all components of the /// graph are searched. @@ -322,11 +322,11 @@ pub fn digraph_dfs_search( pub fn graph_dfs_search( py: Python, graph: &graph::PyGraph, - source: Option, + source: Option>, visitor: PyDfsVisitor, ) -> PyResult<()> { - let starts = match source { - Some(nx) => vec![NodeIndex::new(nx)], + let starts: Vec<_> = match source { + Some(nx) => nx.into_iter().map(NodeIndex::new).collect(), None => graph.graph.node_indices().collect(), }; diff --git a/tests/digraph/test_dfs_search.py b/tests/digraph/test_dfs_search.py index 2c0b68352..f582e2181 100644 --- a/tests/digraph/test_dfs_search.py +++ b/tests/digraph/test_dfs_search.py @@ -37,10 +37,10 @@ def __init__(self): self.edges = [] def tree_edge(self, edge): - self.edges.append(edge) + self.edges.append((edge[0], edge[1])) vis = TreeEdgesRecorder() - retworkx.digraph_dfs_search(self.graph, 0, vis) + retworkx.digraph_dfs_search(self.graph, [0], vis) self.assertEqual(vis.edges, [(0, 2), (2, 6), (2, 5), (5, 3), (2, 1)]) def test_digraph_dfs_tree_edges_no_starting_point(self): @@ -49,7 +49,7 @@ def __init__(self): self.edges = [] def tree_edge(self, edge): - self.edges.append(edge) + self.edges.append((edge[0], edge[1])) vis = TreeEdgesRecorder() retworkx.digraph_dfs_search(self.graph, None, vis) @@ -66,12 +66,13 @@ def __init__(self): self.edges = [] def tree_edge(self, edge): + edge = (edge[0], edge[1]) if edge in self.prohibited: raise retworkx.visit.PruneSearch self.edges.append(edge) vis = TreeEdgesRecorderRestricted() - retworkx.digraph_dfs_search(self.graph, 0, vis) + retworkx.digraph_dfs_search(self.graph, [0], vis) self.assertEqual(vis.edges, [(0, 2), (2, 6), (2, 5), (2, 1), (1, 3)]) def test_digraph_dfs_goal_search(self): @@ -83,7 +84,7 @@ def __init__(self): self.parents = {} def tree_edge(self, edge): - u, v = edge + u, v, _ = edge self.parents[v] = u if v == self.goal: @@ -101,7 +102,7 @@ def reconstruct_path(self): vis = GoalSearch() try: - retworkx.digraph_dfs_search(self.graph, 0, vis) + retworkx.digraph_dfs_search(self.graph, [0], vis) except retworkx.visit.StopSearch: pass self.assertEqual(vis.reconstruct_path(), [0, 2, 5, 3]) diff --git a/tests/graph/test_dfs_search.py b/tests/graph/test_dfs_search.py index cb26b3189..6926e865f 100644 --- a/tests/graph/test_dfs_search.py +++ b/tests/graph/test_dfs_search.py @@ -37,10 +37,10 @@ def __init__(self): self.edges = [] def tree_edge(self, edge): - self.edges.append(edge) + self.edges.append((edge[0], edge[1])) vis = TreeEdgesRecorder() - retworkx.graph_dfs_search(self.graph, 0, vis) + retworkx.graph_dfs_search(self.graph, [0], vis) self.assertEqual(vis.edges, [(0, 2), (2, 6), (2, 5), (5, 3), (3, 1)]) def test_graph_dfs_tree_edges_no_starting_point(self): @@ -49,7 +49,7 @@ def __init__(self): self.edges = [] def tree_edge(self, edge): - self.edges.append(edge) + self.edges.append((edge[0], edge[1])) vis = TreeEdgesRecorder() retworkx.graph_dfs_search(self.graph, None, vis) @@ -66,12 +66,13 @@ def __init__(self): self.edges = [] def tree_edge(self, edge): + edge = (edge[0], edge[1]) if edge in self.prohibited: raise retworkx.visit.PruneSearch self.edges.append(edge) vis = TreeEdgesRecorderRestricted() - retworkx.graph_dfs_search(self.graph, 0, vis) + retworkx.graph_dfs_search(self.graph, [0], vis) self.assertEqual(vis.edges, [(0, 1), (1, 3), (3, 5), (5, 2), (2, 6)]) def test_graph_dfs_goal_search(self): @@ -83,7 +84,7 @@ def __init__(self): self.parents = {} def tree_edge(self, edge): - u, v = edge + u, v, _ = edge self.parents[v] = u if v == self.goal: @@ -101,7 +102,7 @@ def reconstruct_path(self): vis = GoalSearch() try: - retworkx.graph_dfs_search(self.graph, 0, vis) + retworkx.graph_dfs_search(self.graph, [0], vis) except retworkx.visit.StopSearch: pass self.assertEqual(vis.reconstruct_path(), [0, 2, 5, 3]) From bd6b1a0c383fc3f77ad087ed8c7bb9f9e229ba8d Mon Sep 17 00:00:00 2001 From: georgios-ts Date: Mon, 18 Oct 2021 18:02:17 +0300 Subject: [PATCH 06/13] lint --- retworkx/__init__.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/retworkx/__init__.py b/retworkx/__init__.py index 5c6b327ba..e9ba1d4d1 100644 --- a/retworkx/__init__.py +++ b/retworkx/__init__.py @@ -1796,8 +1796,8 @@ def tree_edge(self, edge): Graph can *not* be mutated while traversing. :param PyGraph graph: The graph to be used. - :param List[int] source: An optional list of node indices to use as the starting nodes - for the depth-first search. If this is not specified then a source + :param List[int] source: An optional list of node indices to use as the starting + nodes for the depth-first search. If this is not specified then a source will be chosen arbitrarly and repeated until all components of the graph are searched. :param visitor: A visitor object that is invoked at the event points inside the From 25779f33f9bbe7d68843b74af73c8b1048414745 Mon Sep 17 00:00:00 2001 From: georgios-ts Date: Mon, 18 Oct 2021 18:33:05 +0300 Subject: [PATCH 07/13] fix docs --- retworkx/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/retworkx/__init__.py b/retworkx/__init__.py index e9ba1d4d1..4d89ea742 100644 --- a/retworkx/__init__.py +++ b/retworkx/__init__.py @@ -1788,7 +1788,7 @@ def tree_edge(self, edge): graph = retworkx.PyGraph() graph.extend_from_edge_list([(1, 3), (0, 1), (2, 1), (0, 2)]) vis = TreeEdgesRecorder() - retworkx.dfs_search(graph, 0, vis) + retworkx.dfs_search(graph, [0], vis) print('Tree edges:', vis.edges) .. note:: From 26c8db6612ee02b7cf0ed7e7804efc0e3d721bdb Mon Sep 17 00:00:00 2001 From: georgios-ts Date: Mon, 18 Oct 2021 19:06:08 +0300 Subject: [PATCH 08/13] this is the last fix --- src/traversal/mod.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/traversal/mod.rs b/src/traversal/mod.rs index a3aa3370b..2e9cea841 100644 --- a/src/traversal/mod.rs +++ b/src/traversal/mod.rs @@ -219,7 +219,7 @@ fn descendants(graph: &digraph::PyDiGraph, node: usize) -> HashSet { /// graph = retworkx.PyGraph() /// graph.extend_from_edge_list([(1, 3), (0, 1), (2, 1), (0, 2)]) /// vis = TreeEdgesRecorder() -/// retworkx.dfs_search(graph, 0, vis) +/// retworkx.dfs_search(graph, [0], vis) /// print('Tree edges:', vis.edges) /// /// .. note:: @@ -303,7 +303,7 @@ pub fn digraph_dfs_search( /// graph = retworkx.PyGraph() /// graph.extend_from_edge_list([(1, 3), (0, 1), (2, 1), (0, 2)]) /// vis = TreeEdgesRecorder() -/// retworkx.dfs_search(graph, 0, vis) +/// retworkx.dfs_search(graph, [0], vis) /// print('Tree edges:', vis.edges) /// /// .. note:: From c8e960faac5163b5cd5fea9699612587367b546d Mon Sep 17 00:00:00 2001 From: georgios-ts Date: Wed, 20 Oct 2021 15:01:30 +0300 Subject: [PATCH 09/13] define custom exceptions `StopSearch`, `PruneSearch` in python and import them in rust so we can simplify a bit the namespaces --- retworkx/__init__.py | 5 +---- retworkx/{visitor.py => visit.py} | 12 ++++++++++++ src/lib.rs | 13 +++---------- 3 files changed, 16 insertions(+), 14 deletions(-) rename retworkx/{visitor.py => visit.py} (92%) diff --git a/retworkx/__init__.py b/retworkx/__init__.py index 4d89ea742..b4e1007e9 100644 --- a/retworkx/__init__.py +++ b/retworkx/__init__.py @@ -11,12 +11,9 @@ import functools from .retworkx import * -from .visitor import DFSVisitor - -visit.DFSVisitor = DFSVisitor +import retworkx.visit sys.modules["retworkx.generators"] = generators -sys.modules["retworkx.visit"] = visit class PyDAG(PyDiGraph): diff --git a/retworkx/visitor.py b/retworkx/visit.py similarity index 92% rename from retworkx/visitor.py rename to retworkx/visit.py index ed38ee5c1..79f4e2dea 100644 --- a/retworkx/visitor.py +++ b/retworkx/visit.py @@ -7,6 +7,18 @@ # that they have been altered from the originals. +class StopSearch(Exception): + """Stop graph traversal""" + + pass + + +class PruneSearch(Exception): + """Prune part of the search tree while traversing a graph.""" + + pass + + class DFSVisitor: """A visitor object that is invoked at the event-points inside the :func:`~retworkx.dfs_search` algorithm. By default, it performs no diff --git a/src/lib.rs b/src/lib.rs index bb16e421b..1b0821a46 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -50,6 +50,7 @@ use num_complex::Complex64; use pyo3::create_exception; use pyo3::exceptions::PyException; +use pyo3::import_exception; use pyo3::prelude::*; use pyo3::wrap_pyfunction; use pyo3::wrap_pymodule; @@ -199,16 +200,9 @@ create_exception!(retworkx, NullGraph, PyException); // No path was found between the specified nodes. create_exception!(retworkx, NoPathFound, PyException); // Prune part of the search tree while traversing a graph. -create_exception!(retworkx, PruneSearch, PyException); +import_exception!(retworkx.visit, PruneSearch); // Stop graph traversal. -create_exception!(retworkx, StopSearch, PyException); - -#[pymodule] -fn visit(py: Python, m: &PyModule) -> PyResult<()> { - m.add("StopSearch", py.get_type::())?; - m.add("PruneSearch", py.get_type::())?; - Ok(()) -} +import_exception!(retworkx.visit, StopSearch); #[pymodule] fn retworkx(py: Python<'_>, m: &PyModule) -> PyResult<()> { @@ -333,6 +327,5 @@ fn retworkx(py: Python<'_>, m: &PyModule) -> PyResult<()> { m.add_class::()?; m.add_class::()?; m.add_wrapped(wrap_pymodule!(generators))?; - m.add_wrapped(wrap_pymodule!(visit))?; Ok(()) } From 0225d42a863bdf0d3edb875718664797391cbe5d Mon Sep 17 00:00:00 2001 From: georgios-ts Date: Wed, 20 Oct 2021 15:08:32 +0300 Subject: [PATCH 10/13] minor doc fixes --- retworkx/__init__.py | 10 +++++----- src/traversal/dfs_visit.rs | 6 +----- src/traversal/mod.rs | 22 +++++++++++----------- 3 files changed, 17 insertions(+), 21 deletions(-) diff --git a/retworkx/__init__.py b/retworkx/__init__.py index b4e1007e9..298cb5bdc 100644 --- a/retworkx/__init__.py +++ b/retworkx/__init__.py @@ -1748,19 +1748,19 @@ def dfs_search(graph, source, visitor): color[u] := WHITE initialize vertex u end for time := 0 - call DFS-VISIT(G, source) start vertex s + call DFS-VISIT(G, source) start vertex s DFS-VISIT(G, u) - color[u] := GRAY discover vertex u - for each v in Adj[u] examine edge (u,v) + color[u] := GRAY discover vertex u + for each v in Adj[u] examine edge (u,v) if (color[v] = WHITE) (u,v) is a tree edge all DFS-VISIT(G, v) else if (color[v] = GRAY) (u,v) is a back edge ... - else if (color[v] = BLACK) (u,v) is a cross or forward edge + else if (color[v] = BLACK) (u,v) is a cross or forward edge ... end for - color[u] := BLACK finish vertex u + color[u] := BLACK finish vertex u If an exception is raised inside the callback function, the graph traversal will be stopped immediately. You can exploit this to exit early by raising a diff --git a/src/traversal/dfs_visit.rs b/src/traversal/dfs_visit.rs index 50718e7fd..8d53a88cc 100644 --- a/src/traversal/dfs_visit.rs +++ b/src/traversal/dfs_visit.rs @@ -10,10 +10,6 @@ // License for the specific language governing permissions and limitations // under the License. -// This module is an iterative implementation of the upstream petgraph -// ``depth_first_search`` function. -// https://github.com/petgraph/petgraph/blob/0.6.0/src/visit/dfsvisit.rs - use pyo3::prelude::*; use petgraph::stable_graph::NodeIndex; @@ -31,7 +27,7 @@ pub struct PyDfsVisitor { forward_or_cross_edge: PyObject, } -pub fn handler( +pub fn dfs_handler( py: Python, vis: &PyDfsVisitor, event: DfsEvent, diff --git a/src/traversal/mod.rs b/src/traversal/mod.rs index 2e9cea841..aacebf83f 100644 --- a/src/traversal/mod.rs +++ b/src/traversal/mod.rs @@ -15,7 +15,7 @@ pub mod dfs_visit; use retworkx_core::traversal::{depth_first_search, dfs_edges}; use super::{digraph, graph, iterators}; -use dfs_visit::{handler, PyDfsVisitor}; +use dfs_visit::{dfs_handler, PyDfsVisitor}; use hashbrown::HashSet; @@ -182,11 +182,11 @@ fn descendants(graph: &digraph::PyDiGraph, node: usize) -> HashSet { /// color[u] := WHITE initialize vertex u /// end for /// time := 0 -/// call DFS-VISIT(G, source) start vertex s +/// call DFS-VISIT(G, source) start vertex s /// /// DFS-VISIT(G, u) -/// color[u] := GRAY discover vertex u -/// for each v in Adj[u] examine edge (u,v) +/// color[u] := GRAY discover vertex u +/// for each v in Adj[u] examine edge (u,v) /// if (color[v] = WHITE) (u,v) is a tree edge /// all DFS-VISIT(G, v) /// else if (color[v] = GRAY) (u,v) is a back edge @@ -194,7 +194,7 @@ fn descendants(graph: &digraph::PyDiGraph, node: usize) -> HashSet { /// else if (color[v] = BLACK) (u,v) is a cross or forward edge /// ... /// end for -/// color[u] := BLACK finish vertex u +/// color[u] := BLACK finish vertex u /// /// If an exception is raised inside the callback function, the graph traversal /// will be stopped immediately. You can exploit this to exit early by raising a @@ -247,7 +247,7 @@ pub fn digraph_dfs_search( }; depth_first_search(&graph.graph, starts, |event| { - handler(py, &visitor, event) + dfs_handler(py, &visitor, event) })?; Ok(()) @@ -266,11 +266,11 @@ pub fn digraph_dfs_search( /// color[u] := WHITE initialize vertex u /// end for /// time := 0 -/// call DFS-VISIT(G, source) start vertex s +/// call DFS-VISIT(G, source) start vertex s /// /// DFS-VISIT(G, u) -/// color[u] := GRAY discover vertex u -/// for each v in Adj[u] examine edge (u,v) +/// color[u] := GRAY discover vertex u +/// for each v in Adj[u] examine edge (u,v) /// if (color[v] = WHITE) (u,v) is a tree edge /// all DFS-VISIT(G, v) /// else if (color[v] = GRAY) (u,v) is a back edge @@ -278,7 +278,7 @@ pub fn digraph_dfs_search( /// else if (color[v] = BLACK) (u,v) is a cross or forward edge /// ... /// end for -/// color[u] := BLACK finish vertex u +/// color[u] := BLACK finish vertex u /// /// If an exception is raised inside the callback function, the graph traversal /// will be stopped immediately. You can exploit this to exit early by raising a @@ -331,7 +331,7 @@ pub fn graph_dfs_search( }; depth_first_search(&graph.graph, starts, |event| { - handler(py, &visitor, event) + dfs_handler(py, &visitor, event) })?; Ok(()) From d84d10372927b9a116cea0e1b73796f315d8270a Mon Sep 17 00:00:00 2001 From: georgios-ts Date: Wed, 20 Oct 2021 15:59:51 +0300 Subject: [PATCH 11/13] ignore flake warning --- retworkx/__init__.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/retworkx/__init__.py b/retworkx/__init__.py index 298cb5bdc..d0ef71079 100644 --- a/retworkx/__init__.py +++ b/retworkx/__init__.py @@ -11,6 +11,8 @@ import functools from .retworkx import * + +# flake8: noqa import retworkx.visit sys.modules["retworkx.generators"] = generators From 9f3db1f089979dfc466f5015e61140c120e7d75e Mon Sep 17 00:00:00 2001 From: georgios-ts Date: Sun, 9 Jan 2022 15:41:42 +0200 Subject: [PATCH 12/13] run black --- retworkx/visit.py | 1 - 1 file changed, 1 deletion(-) diff --git a/retworkx/visit.py b/retworkx/visit.py index 7f10a8a01..d0f21fb68 100644 --- a/retworkx/visit.py +++ b/retworkx/visit.py @@ -71,7 +71,6 @@ def black_target_edge(self, e): return - class DFSVisitor: """A visitor object that is invoked at the event-points inside the :func:`~retworkx.dfs_search` algorithm. By default, it performs no From f230431f926ffe2f1917acf29825f0a73352eaa7 Mon Sep 17 00:00:00 2001 From: georgios-ts Date: Mon, 10 Jan 2022 19:40:55 +0200 Subject: [PATCH 13/13] deduplicate macro and mention petgraph DfsEvent struct --- retworkx-core/src/traversal/bfs_visit.rs | 22 +------------------- retworkx-core/src/traversal/dfs_visit.rs | 26 +++++------------------- retworkx-core/src/traversal/mod.rs | 24 ++++++++++++++++++++++ 3 files changed, 30 insertions(+), 42 deletions(-) diff --git a/retworkx-core/src/traversal/bfs_visit.rs b/retworkx-core/src/traversal/bfs_visit.rs index 4aca42d6e..97ab2ab9c 100644 --- a/retworkx-core/src/traversal/bfs_visit.rs +++ b/retworkx-core/src/traversal/bfs_visit.rs @@ -13,27 +13,7 @@ use petgraph::visit::{ControlFlow, EdgeRef, IntoEdges, VisitMap, Visitable}; use std::collections::VecDeque; -/// Return if the expression is a break value, execute the provided statement -/// if it is a prune value. -/// https://github.com/petgraph/petgraph/blob/0.6.0/src/visit/dfsvisit.rs#L27 -macro_rules! try_control { - ($e:expr, $p:stmt) => { - try_control!($e, $p, ()); - }; - ($e:expr, $p:stmt, $q:stmt) => { - match $e { - x => { - if x.should_break() { - return x; - } else if x.should_prune() { - $p - } else { - $q - } - } - } - }; -} +use super::try_control; /// A breadth first search (BFS) visitor event. #[derive(Copy, Clone, Debug)] diff --git a/retworkx-core/src/traversal/dfs_visit.rs b/retworkx-core/src/traversal/dfs_visit.rs index e92b67748..be7e0c575 100644 --- a/retworkx-core/src/traversal/dfs_visit.rs +++ b/retworkx-core/src/traversal/dfs_visit.rs @@ -18,29 +18,13 @@ use petgraph::visit::{ ControlFlow, EdgeRef, IntoEdges, Time, VisitMap, Visitable, }; -/// Return if the expression is a break value, execute the provided statement -/// if it is a prune value. -/// https://github.com/petgraph/petgraph/blob/0.6.0/src/visit/dfsvisit.rs#L27 -macro_rules! try_control { - ($e:expr, $p:stmt) => { - try_control!($e, $p, ()); - }; - ($e:expr, $p:stmt, $q:stmt) => { - match $e { - x => { - if x.should_break() { - return x; - } else if x.should_prune() { - $p - } else { - $q - } - } - } - }; -} +use super::try_control; /// A depth first search (DFS) visitor event. +/// +/// It's similar to upstream petgraph +/// [`DfsEvent`](https://docs.rs/petgraph/0.6.0/petgraph/visit/enum.DfsEvent.html) +/// event. #[derive(Copy, Clone, Debug)] pub enum DfsEvent { Discover(N, Time), diff --git a/retworkx-core/src/traversal/mod.rs b/retworkx-core/src/traversal/mod.rs index 104aaf44b..2a06c3007 100644 --- a/retworkx-core/src/traversal/mod.rs +++ b/retworkx-core/src/traversal/mod.rs @@ -19,3 +19,27 @@ mod dfs_visit; pub use bfs_visit::{breadth_first_search, BfsEvent}; pub use dfs_edges::dfs_edges; pub use dfs_visit::{depth_first_search, DfsEvent}; + +/// Return if the expression is a break value, execute the provided statement +/// if it is a prune value. +/// https://github.com/petgraph/petgraph/blob/0.6.0/src/visit/dfsvisit.rs#L27 +macro_rules! try_control { + ($e:expr, $p:stmt) => { + try_control!($e, $p, ()); + }; + ($e:expr, $p:stmt, $q:stmt) => { + match $e { + x => { + if x.should_break() { + return x; + } else if x.should_prune() { + $p + } else { + $q + } + } + } + }; +} + +use try_control;