|
2 | 2 | // This file is part of the CPP-GL project (https://github.com/SpectraL519/cpp-gl). |
3 | 3 | // Licensed under the MIT License. See the LICENSE file in the project root for full license information. |
4 | 4 |
|
| 5 | +/// @file hgl/algorithm/backward_search.hpp |
| 6 | +/// @brief Concrete backward B-search traversals (B-BFS and B-DFS) for bf-directed hypergraphs. |
| 7 | + |
5 | 8 | #pragma once |
6 | 9 |
|
7 | 10 | #include "hgl/algorithm/core.hpp" |
|
12 | 15 |
|
13 | 16 | namespace hgl::algorithm { |
14 | 17 |
|
| 18 | +/// @ingroup HGL-Algorithm |
| 19 | +/// @brief Executes a Breadth-First B-Search (B-BFS) traversal over a bf-directed hypergraph. |
| 20 | +/// |
| 21 | +/// This algorithm implements B-reachability semantics using Breadth-First Search for BF-directed hypergraphs. |
| 22 | +/// Unlike a standard traversal (where reaching a single tail vertex is sufficient to traverse an outgoing |
| 23 | +/// hyperedge), a backward search (B-search) uses a blocking predicate. A hyperedge is only traversed, and |
| 24 | +/// its head vertices enqueued, after **all** of its tail (source) vertices have been visited. |
| 25 | +/// |
| 26 | +/// ### Example Usage |
| 27 | +/// ```cpp |
| 28 | +/// std::vector<hgl::size_type> roots = { start_id_1, start_id_2 }; |
| 29 | +/// auto search_tree = hgl::algorithm::backward_bfs(hypergraph, roots); // (1)! |
| 30 | +/// |
| 31 | +/// hgl::algorithm::backward_bfs<hgl::algorithm::noret>( // (2)! |
| 32 | +/// hypergraph, |
| 33 | +/// roots, |
| 34 | +/// [](const auto& node) { std::cout << "Pre-visit: " << node.vertex_id << '\n'; }, |
| 35 | +/// [](const auto& node) { std::cout << "Post-visit: " << node.vertex_id << '\n'; } |
| 36 | +/// ); |
| 37 | +/// ``` |
| 38 | +/// |
| 39 | +/// 1\. Executes a B-BFS returning a search tree mapped to the components B-reachable from the specified roots. |
| 40 | +/// |
| 41 | +/// 2\. Executes a B-BFS purely for side-effects (callbacks) without allocating memory for a search tree. |
| 42 | +/// |
| 43 | +/// ### Template Parameters |
| 44 | +/// | Parameter | Description | Constraint | |
| 45 | +/// | :-------- | :--- | :--- | |
| 46 | +/// | Result | Controls whether the algorithm builds and returns a search tree (`ret`) or evaluates purely for side effects (`noret`). | Must be a valid @ref hgl::algorithm::result_discriminator "result_discriminator" enum value. | |
| 47 | +/// | H | The type of the hypergraph being searched. | Must satisfy the [**c_bf_directed_hypergraph**](hgl_concepts.md#hgl-traits-c-bf-directed-hypergraph) concept. | |
| 48 | +/// | RootRange | The type of the container providing the initial roots to enqueue. | Must satisfy [**c_forward_range_of**](gl_concepts.md#gl-traits-c-forward-range-of) over the hypergraph's `id_type`. | |
| 49 | +/// | PreVisitCallback | Type of the callable executed immediately before visiting a vertex. | Must be one of:<br/>- A `(const search_node<H>&) -> void` callable<br/>- An @ref hgl::algorithm::empty_callback "empty_callback" | |
| 50 | +/// | PostVisitCallback | Type of the callable executed after all adjacent elements are evaluated. | Must be one of:<br/>- A `(const search_node<H>&) -> void` callable<br/>- An @ref hgl::algorithm::empty_callback "empty_callback" | |
| 51 | +/// |
| 52 | +/// @param hypergraph The bf-directed hypergraph to traverse. |
| 53 | +/// @param root_vertices A range of initial vertex IDs to start the search from. |
| 54 | +/// @param pre_visit Hook executed immediately before visiting the vertex. |
| 55 | +/// @param post_visit Hook executed after all adjacent hyperedges and target vertices of the current node have been evaluated. |
| 56 | +/// @return A @ref hgl::algorithm::search_tree "search_tree" if `Result == ret`, otherwise nothing (`void`). |
| 57 | +/// @hideparams |
15 | 58 | template < |
16 | 59 | result_discriminator Result = ret, |
17 | 60 | traits::c_bf_directed_hypergraph H, |
@@ -53,6 +96,46 @@ result_type<Result, search_tree<H>> backward_bfs( |
53 | 96 | return stree; |
54 | 97 | } |
55 | 98 |
|
| 99 | +/// @ingroup HGL-Algorithm |
| 100 | +/// @brief Executes a Depth-First B-Search (B-DFS) traversal over a bf-directed hypergraph. |
| 101 | +/// |
| 102 | +/// This algorithm implements B-reachability semantics using a stack-based Depth-First Search for BF-directed |
| 103 | +/// hypergraphs. Unlike a standard traversal (where reaching a single tail vertex is sufficient to traverse an |
| 104 | +/// outgoing hyperedge), a backward search (B-search) uses a blocking predicate. A hyperedge is only traversed, |
| 105 | +/// and its head vertices enqueued, after **all** of its tail (source) vertices have been visited. |
| 106 | +/// |
| 107 | +/// ### Example Usage |
| 108 | +/// ```cpp |
| 109 | +/// std::vector<hgl::size_type> roots = { start_id_1, start_id_2 }; |
| 110 | +/// auto search_tree = hgl::algorithm::backward_dfs(hypergraph, roots); // (1)! |
| 111 | +/// |
| 112 | +/// hgl::algorithm::backward_dfs<hgl::algorithm::noret>( // (2)! |
| 113 | +/// hypergraph, |
| 114 | +/// roots, |
| 115 | +/// [](const auto& node) { std::cout << "Pre-visit: " << node.vertex_id << '\n'; }, |
| 116 | +/// [](const auto& node) { std::cout << "Post-visit: " << node.vertex_id << '\n'; } |
| 117 | +/// ); |
| 118 | +/// ``` |
| 119 | +/// |
| 120 | +/// 1\. Executes a B-DFS returning a search tree mapped to the components B-reachable from the specified roots. |
| 121 | +/// |
| 122 | +/// 2\. Executes a B-DFS purely for side-effects (callbacks) without allocating memory for a search tree. |
| 123 | +/// |
| 124 | +/// ### Template Parameters |
| 125 | +/// | Parameter | Description | Constraint | |
| 126 | +/// | :-------- | :--- | :--- | |
| 127 | +/// | Result | Controls whether the algorithm builds and returns a search tree (`ret`) or evaluates purely for side effects (`noret`). | Must be a valid @ref hgl::algorithm::result_discriminator "result_discriminator" enum value. | |
| 128 | +/// | H | The type of the hypergraph being searched. | Must satisfy the [**c_bf_directed_hypergraph**](hgl_concepts.md#hgl-traits-c-bf-directed-hypergraph) concept. | |
| 129 | +/// | RootRange | The type of the container providing the initial roots to enqueue. | Must satisfy [**c_forward_range_of**](gl_concepts.md#gl-traits-c-forward-range-of) over the hypergraph's `id_type`. | |
| 130 | +/// | PreVisitCallback | Type of the callable executed immediately before officially visiting a vertex. | Must be one of:<br/>- A `(const search_node<H>&) -> void` callable<br/>- An @ref hgl::algorithm::empty_callback "empty_callback" | |
| 131 | +/// | PostVisitCallback | Type of the callable executed after all adjacent elements are evaluated. | Must be one of:<br/>- A `(const search_node<H>&) -> void` callable<br/>- An @ref hgl::algorithm::empty_callback "empty_callback" | |
| 132 | +/// |
| 133 | +/// @param hypergraph The bf-directed hypergraph to traverse. |
| 134 | +/// @param root_vertices A range of initial vertex IDs to start the search from. |
| 135 | +/// @param pre_visit Hook executed immediately before officially visiting the vertex. |
| 136 | +/// @param post_visit Hook executed after all adjacent hyperedges and target vertices of the current node have been evaluated. |
| 137 | +/// @return A @ref hgl::algorithm::search_tree "search_tree" if `Result == ret`, otherwise nothing (`void`). |
| 138 | +/// @hideparams |
56 | 139 | template < |
57 | 140 | result_discriminator Result = ret, |
58 | 141 | traits::c_bf_directed_hypergraph H, |
|
0 commit comments