Skip to content

Commit 007d302

Browse files
SpectraL519SpectraL519
committed
bsearch and fsearch docs
1 parent af48dda commit 007d302

4 files changed

Lines changed: 170 additions & 4 deletions

File tree

‎include/hgl/algorithm/traversal/backward_search.hpp‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,9 @@
22
// This file is part of the CPP-GL project (https://github.com/SpectraL519/cpp-gl).
33
// Licensed under the MIT License. See the LICENSE file in the project root for full license information.
44

5+
/// @file hgl/algorithm/backward_search.hpp
6+
/// @brief Concrete backward B-search traversals (B-BFS and B-DFS) for bf-directed hypergraphs.
7+
58
#pragma once
69

710
#include "hgl/algorithm/core.hpp"
@@ -12,6 +15,46 @@
1215

1316
namespace hgl::algorithm {
1417

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
1558
template <
1659
result_discriminator Result = ret,
1760
traits::c_bf_directed_hypergraph H,
@@ -53,6 +96,46 @@ result_type<Result, search_tree<H>> backward_bfs(
5396
return stree;
5497
}
5598

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
56139
template <
57140
result_discriminator Result = ret,
58141
traits::c_bf_directed_hypergraph H,

‎include/hgl/algorithm/traversal/breadth_first_search.hpp‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,12 +46,12 @@ namespace hgl::algorithm {
4646
/// | :-------- | :--- | :--- |
4747
/// | 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. |
4848
/// | H | The type of the hypergraph being searched. | Must satisfy the [**c_hypergraph**](hgl_concepts.md#hgl-traits-c-hypergraph) concept. |
49-
/// | 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" |
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" |
5050
/// | 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" |
5151
///
5252
/// @param hypergraph The hypergraph to traverse.
5353
/// @param root_vertex_id The ID of the vertex to start the search from. If `no_root`, searches the entire hypergraph.
54-
/// @param pre_visit Hook executed immediately before officially visiting the vertex.
54+
/// @param pre_visit Hook executed immediately before visiting the vertex.
5555
/// @param post_visit Hook executed after all adjacent hyperedges and target vertices of the current node have been evaluated.
5656
/// @return A @ref hgl::algorithm::search_tree "search_tree" if `Result == ret`, otherwise nothing (`void`).
5757
/// @hideparams

‎include/hgl/algorithm/traversal/depth_first_search.hpp‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,12 +46,12 @@ namespace hgl::algorithm {
4646
/// | :-------- | :--- | :--- |
4747
/// | 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. |
4848
/// | H | The type of the hypergraph being searched. | Must satisfy the [**c_hypergraph**](hgl_concepts.md#hgl-traits-c-hypergraph) concept. |
49-
/// | 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" |
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" |
5050
/// | 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" |
5151
///
5252
/// @param hypergraph The hypergraph to traverse.
5353
/// @param root_vertex_id The ID of the vertex to start the search from. If `no_root`, searches the entire hypergraph.
54-
/// @param pre_visit Hook executed immediately before officially visiting the vertex.
54+
/// @param pre_visit Hook executed immediately before visiting the vertex.
5555
/// @param post_visit Hook executed after all adjacent hyperedges and target vertices of the current node have been evaluated.
5656
/// @return A @ref hgl::algorithm::search_tree "search_tree" if `Result == ret`, otherwise nothing (`void`).
5757
/// @hideparams

‎include/hgl/algorithm/traversal/forward_search.hpp‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,9 @@
22
// This file is part of the CPP-GL project (https://github.com/SpectraL519/cpp-gl).
33
// Licensed under the MIT License. See the LICENSE file in the project root for full license information.
44

5+
/// @file hgl/algorithm/forward_search.hpp
6+
/// @brief Concrete forward F-search traversals (F-BFS and F-DFS) for bf-directed hypergraphs.
7+
58
#pragma once
69

710
#include "hgl/algorithm/core.hpp"
@@ -12,6 +15,46 @@
1215

1316
namespace hgl::algorithm {
1417

18+
/// @ingroup HGL-Algorithm
19+
/// @brief Executes a Breadth-First F-Search (F-BFS) traversal over a bf-directed hypergraph.
20+
///
21+
/// This algorithm implements F-reachability semantics using Breadth-First Search for BF-directed hypergraphs.
22+
/// Unlike a standard backward traversal (where reaching a single head vertex is sufficient to traverse an
23+
/// incoming hyperedge), a forward search (F-search) uses a blocking predicate. A hyperedge is only traversed,
24+
/// and its tail vertices enqueued, after **all** of its head (destination) 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::forward_bfs(hypergraph, roots); // (1)!
30+
///
31+
/// hgl::algorithm::forward_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 an F-BFS returning a search tree mapped to the components F-reachable from the specified roots.
40+
///
41+
/// 2\. Executes an F-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 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" |
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 officially 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
1558
template <
1659
result_discriminator Result = ret,
1760
traits::c_bf_directed_hypergraph H,
@@ -53,6 +96,46 @@ result_type<Result, search_tree<H>> forward_bfs(
5396
return stree;
5497
}
5598

99+
/// @ingroup HGL-Algorithm
100+
/// @brief Executes a Depth-First F-Search (F-DFS) traversal over a bf-directed hypergraph.
101+
///
102+
/// This algorithm implements F-reachability semantics using a stack-based Depth-First Search for BF-directed
103+
/// hypergraphs. Unlike a standard backward traversal (where reaching a single head vertex is sufficient to traverse an
104+
/// incoming hyperedge), a forward search (F-search) uses a blocking predicate. A hyperedge is only traversed,
105+
/// and its tail vertices pushed to the stack, after **all** of its head (destination) vertices have been officially 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::forward_dfs(hypergraph, roots); // (1)!
111+
///
112+
/// hgl::algorithm::forward_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 an F-DFS returning a search tree mapped to the components F-reachable from the specified roots.
121+
///
122+
/// 2\. Executes an F-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
56139
template <
57140
result_discriminator Result = ret,
58141
traits::c_bf_directed_hypergraph H,

0 commit comments

Comments
 (0)