Skip to content

Commit df38b0a

Browse files
barakatzirIvanIsCoding
barakatzir
and
IvanIsCoding
authored
Enhance traversal docs (#1375)
* Enhance universal bfs_search docs and misc docs fixes * Enhance docs of non universal bfs_search * non-universal centrality doc fixes * New BFS pseudo-code in rustworkx-core * fixes after looking at docs * enhance dfs search docs * formatting * Fix docs publishing job * simplify pseudo-code * enhance dijksra_search docs * add dijkstra_search doc example * fix universal dijkstra_search type annotations * correct description: python code -> psuedo-code --------- Co-authored-by: Ivan Carvalho <[email protected]>
1 parent f2f4542 commit df38b0a

File tree

9 files changed

+739
-292
lines changed

9 files changed

+739
-292
lines changed

‎.github/workflows/docs_dev.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,12 +28,12 @@ jobs:
2828
run: |
2929
tools/build_documentation_dev.sh
3030
- name: Upload artifact
31-
uses: actions/upload-pages-artifact@v2
31+
uses: actions/upload-pages-artifact@v3
3232
with:
3333
name: html_docs
3434
path: docs/build/html
3535
- name: Deploy
36-
uses: peaceiris/actions-gh-pages@v3
36+
uses: peaceiris/actions-gh-pages@v4
3737
with:
3838
github_token: ${{ secrets.GITHUB_TOKEN }}
3939
publish_branch: gh-pages

‎.github/workflows/docs_release.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,12 +29,12 @@ jobs:
2929
run: |
3030
tools/build_documentation_release.sh
3131
- name: Upload artifact
32-
uses: actions/upload-pages-artifact@v2
32+
uses: actions/upload-pages-artifact@v3
3333
with:
3434
name: html_docs
3535
path: release_docs/
3636
- name: Deploy
37-
uses: peaceiris/actions-gh-pages@v3
37+
uses: peaceiris/actions-gh-pages@v4
3838
with:
3939
github_token: ${{ secrets.GITHUB_TOKEN }}
4040
publish_branch: gh-pages

‎rustworkx-core/src/traversal/bfs_visit.rs‎

Lines changed: 22 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -56,29 +56,32 @@ pub enum BfsEvent<N, E> {
5656
///
5757
/// ***Panics** if you attempt to prune a node from its `Finish` event.
5858
///
59-
/// The pseudo-code for the BFS algorithm is listed below, with the annotated
60-
/// event points, for which the given visitor object will be called with the
61-
/// appropriate method.
59+
/// Pseudo-code for the BFS algorithm is listed below, with the annotated event points,
60+
/// for which the given visitor object will be called with the appropriate method.
6261
///
6362
/// ```norust
63+
/// // G - graph, s - single source node
6464
/// BFS(G, s)
65-
/// for each vertex u in V
66-
/// color[u] := WHITE
65+
/// let color be a mapping // color[u] - vertex u color WHITE/GRAY/BLACK
66+
/// for each u in G // u - vertex in G
67+
/// color[u] := WHITE // color all vertices as undiscovered
6768
/// end for
68-
/// color[s] := GRAY
69-
/// EQUEUE(Q, s) discover vertex s
70-
/// while (Q != Ø)
71-
/// u := DEQUEUE(Q)
72-
/// for each vertex v in Adj[u] (u,v) is a tree edge
73-
/// if (color[v] = WHITE)
74-
/// color[v] = GRAY
75-
/// else (u,v) is a non - tree edge
76-
/// if (color[v] = GRAY) (u,v) has a gray target
77-
/// ...
78-
/// else if (color[v] = BLACK) (u,v) has a black target
79-
/// ...
80-
/// end for
81-
/// color[u] := BLACK finish vertex u
69+
/// let Q be a queue
70+
/// ENQUEUE(Q, s)
71+
/// color[s] := GRAY // event: Discover(s)
72+
/// while (Q is not empty)
73+
/// u := DEQUEUE(Q)
74+
/// for each v, w in OutEdges(G, u) // v - target vertex, w - edge weight
75+
/// if (WHITE = color[v]) // event: TreeEdge(u, v, w)
76+
/// color[v] := GRAY // event: Discover(v)
77+
/// ENQUEUE(Q, v)
78+
/// else // event: NonTreeEdge(u, v, w)
79+
/// if (GRAY = color[v]) // event: GrayTargetEdge(u, v, w)
80+
/// ...
81+
/// elif (BLACK = color[v]) // event: BlackTargetEdge(u, v, w)
82+
/// ...
83+
/// end for
84+
/// color[u] := BLACK // event: Finish(u)
8285
/// end while
8386
/// ```
8487
///

‎rustworkx-core/src/traversal/dfs_visit.rs‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,43 @@ pub enum DfsEvent<N, E> {
6565
///
6666
/// ***Panics** if you attempt to prune a node from its `Finish` event.
6767
///
68+
/// Pseudo-code for the DFS algorithm is listed below, with the annotated event points,
69+
/// for which the given visitor object will be called with the appropriate method.
70+
///
71+
/// ```norust
72+
/// // G - graph, s - single source node
73+
/// DFS(G, s)
74+
/// let color be a mapping // color[u] - vertex u color WHITE/GRAY/BLACK
75+
/// for each u in G // u - vertex in G
76+
/// color[u] := WHITE // color all as undiscovered
77+
/// end for
78+
/// time := 0
79+
/// let S be a stack
80+
/// PUSH(S, (s, iterator of OutEdges(G, s))) // S - stack of vertices and edge iterators
81+
/// color[s] := GRAY // event: Discover(s, time)
82+
/// while (S is not empty)
83+
/// let (u, iterator) := LAST(S)
84+
/// flag := False // whether edge to undiscovered vertex found
85+
/// for each v, w in iterator // v - target vertex, w - edge weight
86+
/// if (WHITE = color[v]) // event: TreeEdge(u, v, w)
87+
/// time := time + 1
88+
/// color[v] := GRAY // event: Discover(v, time)
89+
/// flag := True
90+
/// break
91+
/// elif (GRAY = color[v]) // event: BackEdge(u, v, w)
92+
/// ...
93+
/// elif (BLACK = color[v]) // event: CrossForwardEdge(u, v, w)
94+
/// ...
95+
/// end for
96+
/// if (flag is True)
97+
/// PUSH(S, (v, iterator of OutEdges(G, v)))
98+
/// elif (flag is False)
99+
/// time := time + 1
100+
/// color[u] := BLACK // event: Finish(u, time)
101+
/// POP(S)
102+
/// end while
103+
/// ```
104+
///
68105
/// # Example returning `Control`.
69106
///
70107
/// Find a path from vertex 0 to 5, and exit the visit as soon as we reach

‎rustworkx-core/src/traversal/dijkstra_visit.rs‎

Lines changed: 24 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -94,25 +94,30 @@ pub enum DijkstraEvent<N, E, K> {
9494
/// appropriate method.
9595
///
9696
/// ```norust
97-
/// DIJKSTRA(G, source, weight)
98-
/// for each vertex u in V
99-
/// d[u] := infinity
100-
/// p[u] := u
101-
/// end for
102-
/// d[source] := 0
103-
/// INSERT(Q, source)
104-
/// while (Q != Ø)
105-
/// u := EXTRACT-MIN(Q) discover vertex u
106-
/// for each vertex v in Adj[u] examine edge (u,v)
107-
/// if (weight[(u,v)] + d[u] < d[v]) edge (u,v) relaxed
108-
/// d[v] := weight[(u,v)] + d[u]
109-
/// p[v] := u
110-
/// DECREASE-KEY(Q, v)
111-
/// else edge (u,v) not relaxed
112-
/// ...
113-
/// if (d[v] was originally infinity)
114-
/// INSERT(Q, v)
115-
/// end for finish vertex u
97+
/// // G - graph, s - single source node, weight - edge cost function
98+
/// DIJKSTRA(G, s, weight)
99+
/// let score be empty mapping
100+
/// let visited be empty set
101+
/// let Q be a priority queue
102+
/// score[s] := DEFAULT_COST
103+
/// PUSH(Q, (score[s], s)) // only score determines the priority
104+
/// while Q is not empty
105+
/// cost, u := POP-MIN(Q)
106+
/// if u in visited
107+
/// continue
108+
/// PUT(visited, u) // event: Discover(u, cost)
109+
/// for each _, v, w in OutEdges(G, u) // v - target vertex, w - edge weight
110+
/// ... // event: ExamineEdge(u, v, w)
111+
/// if v in visited
112+
/// continue
113+
/// next_cost = cost + weight(w)
114+
/// if {(v is key in score)
115+
/// and (score[v] <= next_cost)} // event: EdgeNotRelaxed(u, v, w)
116+
/// ...
117+
/// else: // v not scored or scored higher
118+
/// score[v] = next_cost // event: EdgeRelaxed(u, v, w)
119+
/// PUSH(Q, (next_cost, v))
120+
/// end for // event: Finish(u)
116121
/// end while
117122
/// ```
118123
///

0 commit comments

Comments
 (0)