init_range -> init_node_range + bfs tmpl doc

Author: SpectraL519

docs/gl/quick_start.md

@@ -42,10 +42,12 @@ int main() {
         return 1;
     }
 
-    auto path_to_target = gl::algorithm::reconstruct_path(paths.predecessors, target_id); // (7)!
+    auto path_to_target
+        = gl::algorithm::reconstruct_path(paths.predecessors, target_id); // (7)!
     std::cout << "Shortest path distance to vertex " << target_id << ": "
               << paths.distances[target_id] << "\nPath: "
-              << gl::io::range_formatter(path_to_target, " -> ", "", "") << '\n'; // (8)!
+              << gl::io::range_formatter(path_to_target, " -> ", "", "") // (8)!
+              << '\n';
 
     return 0;
 }

include/gl/algorithm/templates/bfs.hpp

@@ -29,7 +29,7 @@ namespace gl::algorithm {
 ///
 /// bool completed = gl::algorithm::bfs(
 ///     graph,
-///     gl::algorithm::init_range<graph_type>(start_id), // (2)!
+///     gl::algorithm::init_node_range<graph_type>(start_id), // (2)!
 ///     gl::algorithm::default_visit_vertex_predicate(visited), // (3)!
 ///     [&](auto v, auto p) { // (4)!
 ///         std::cout << "Visited vertex " << v << '\n';

include/gl/algorithm/templates/dfs.hpp

@@ -28,7 +28,7 @@ namespace gl::algorithm {
 ///
 /// bool completed = gl::algorithm::dfs(
 ///     graph,
-///     gl::algorithm::init_range<graph_type>(start_id), // (2)!
+///     gl::algorithm::init_node_range<graph_type>(start_id), // (2)!
 ///     gl::algorithm::default_visit_vertex_predicate(visited), // (3)!
 ///     [&](auto v, auto p) { // (4)!
 ///         std::cout << "Visited vertex " << v << '\n';

include/gl/algorithm/templates/pfs.hpp

@@ -34,7 +34,7 @@ namespace gl::algorithm {
 ///     [](const auto& lhs, const auto& rhs) { // (2)!
 ///         return lhs.vertex_id > rhs.vertex_id;
 ///     },
-///     gl::algorithm::init_range<graph_type>(start_id), // (3)!
+///     gl::algorithm::init_node_range<graph_type>(start_id), // (3)!
 ///     gl::algorithm::default_visit_vertex_predicate(visited // (4)!
 ///     [&](auto v, auto p) { // (5)!
 ///         std::cout << "Priority visited vertex " << v << '\n';

include/gl/algorithm/topology/coloring.hpp

@@ -79,7 +79,7 @@ template <
 
         const bool is_bipartite = bfs(
             graph,
-            init_range<G>(root_id),
+            init_node_range<G>(root_id),
             empty_callback{}, // visit predicate
             empty_callback{}, // visit callback
             [&coloring](typename G::id_type vertex_id, const edge_type& in_edge)

include/gl/algorithm/traversal/breadth_first_search.hpp

@@ -87,7 +87,7 @@ result_type<Result, predecessors_map<G>> breadth_first_search(
     if (root_vertex_id != no_root) {
         bfs(
             graph,
-            init_range<G>(root_vertex_id),
+            init_node_range<G>(root_vertex_id),
             default_visit_vertex_predicate(visited),
             default_visit_callback<G, Result>(visited, pred_map),
             default_enqueue_node_predicate<G, true>(visited),
@@ -99,7 +99,7 @@ result_type<Result, predecessors_map<G>> breadth_first_search(
         for (const auto root_id : graph.vertex_ids())
             bfs(
                 graph,
-                init_range<G>(root_id),
+                init_node_range<G>(root_id),
                 default_visit_vertex_predicate(visited),
                 default_visit_callback<G, Result>(visited, pred_map),
                 default_enqueue_node_predicate<G, true>(visited),

include/gl/algorithm/traversal/depth_first_search.hpp

@@ -95,7 +95,7 @@ result_type<Result, predecessors_map<G>> depth_first_search(
     if (root_vertex_id != no_root) {
         dfs(
             graph,
-            init_range<G>(root_vertex_id),
+            init_node_range<G>(root_vertex_id),
             default_visit_vertex_predicate(visited),
             default_visit_callback<G, Result>(visited, pred_map),
             default_enqueue_node_predicate<G, true>(visited),
@@ -107,7 +107,7 @@ result_type<Result, predecessors_map<G>> depth_first_search(
         for (const auto root_id : graph.vertex_ids())
             dfs(
                 graph,
-                init_range<G>(root_id),
+                init_node_range<G>(root_id),
                 default_visit_vertex_predicate(visited),
                 default_visit_callback<G, Result>(visited, pred_map),
                 default_enqueue_node_predicate<G, true>(visited),

include/gl/algorithm/util.hpp

@@ -45,15 +45,16 @@ template <traits::c_id_type IdType>
 }
 
 /// @ingroup GL GL-Algorithm
-/// @brief Initializes a search container (queue or stack) with the starting root vertex.
+/// @brief Initializes a search container with the starting root vertex.
 /// @tparam G The type of the graph.
 /// @tparam InitRangeType The underlying container type for the container.
 /// @param root_vertex_id The ID of the starting vertex.
 /// @return A container initialized with a single @ref search_node for the root vertex.
 template <
     traits::c_graph G,
     traits::c_forward_range_of<search_node<G>> InitRangeType = std::vector<search_node<G>>>
-[[nodiscard]] gl_attr_force_inline InitRangeType init_range(typename G::id_type root_vertex_id) {
+[[nodiscard]] gl_attr_force_inline InitRangeType init_node_range(typename G::id_type root_vertex_id
+) {
     return InitRangeType{search_node<G>{root_vertex_id}};
 }
 

include/hgl/algorithm/templates/bfs.hpp

@@ -2,6 +2,9 @@
 // This file is part of the CPP-GL project (https://github.com/SpectraL519/cpp-gl).
 // Licensed under the MIT License. See the LICENSE file in the project root for full license information.
 
+/// @file hgl/algorithm/templates/bfs.hpp
+/// @brief Generic Breadth-First Search (BFS) template algorithm engine for hypergraphs.
+
 #pragma once
 
 #include "hgl/algorithm/core.hpp"
@@ -10,15 +13,82 @@
 
 namespace hgl::algorithm {
 
-/// @ingroup hgl_alg
+/// @ingroup HGL-Algorithm
+/// @brief A highly customizable, generic Breadth-First Search (BFS) algorithm engine for hypergraphs.
+///
+/// This template provides the strict structural execution of a queue-based Breadth-First Search
+/// over a hypergraph's topology. Because a hypergraph traversal inherently requires a two-step
+/// expansion (from a vertex to its incident hyperedges, and then to the adjacent vertices), this
+/// engine exposes specific hooks for both steps. Concrete algorithms are constructed by injecting
+/// logic into the provided callback and predicate hooks.
+///
+/// ### Example Usage
+/// ```cpp
+/// std::vector<bool> visited(hypergraph.n_vertices(), false); // (1)!
+///
+/// bool completed = hgl::algorithm::bfs(
+///     hypergraph,
+///     hgl::algorithm::init_node_range<H>(start_id), // (2)!
+///     [&](const auto& node) { return not visited[node.vertex_id]; }, // (3)!
+///     [&](const auto& node) { // (4)!
+///         visited[node.vertex_id] = true;
+///         std::cout << "Visited vertex " << node.vertex_id << '\n';
+///         return true; // Continue search
+///     },
+///     hgl::empty_callback{}, // (5)!
+///     [&](const auto& tgt_node) { return not visited[tgt_node.vertex_id]; } // (6)!
+/// );
+/// ```
+///
+/// 1\. Provide an external state array to track the visited vertices.
+///
+/// 2\. Initialize the search queue with a root @ref hgl::algorithm::search_node "search node" representing the starting point.
+///
+/// 3\. The *visit predicate* ensures vertices are not processed multiple times.
+///
+/// 4\. The concrete vertex visiting logic - marks the vertex as visited and logs it to the console.
+///
+/// 5\. Traverse all hyperedges unconditionally.
+///
+/// 6\. The *enqueue predicate* filters out already visited adjacent vertices before they enter the queue.
+///
+/// ### Template Parameters
+/// | Parameter | Description | Constraint |
+/// | :-------- | :--- | :--- |
+/// | Dir | The @ref hgl::algorithm::traversal_direction "traversal direction" (i.e., `forward` or `backward`). Relevant only for BF-directed hypergraphs. | Defaults to `forward`. |
+/// | H | The type of the hypergraph being searched. | Must satisfy the [**c_hypergraph**](hgl_concepts.md#hgl-traits-c-hypergraph) concept. |
+/// | InitQueueRangeType | A forward range of `search_node<H>` used to prime the BFS queue. | Must be a *forward range* of @ref hgl::algorithm::search_node "search nodes". |
+/// | VisitPredicate | Type of the callable deciding if a popped node should be processed. | Must be one of:<br/>- A `(const search_node<H>&) -> bool` callable<br/>- An @ref hgl::algorithm::empty_callback "empty_callback" |
+/// | VisitCallback | Type of the callable executed when a vertex is officially visited. | Must be one of:<br/>- A `(const search_node<H>&) -> bool` callable<br/>- An @ref hgl::algorithm::empty_callback "empty_callback" |
+/// | TraverseHePredicate | Type of the callable deciding if an incident hyperedge should be traversed. | Must be one of:<br/>- An `(id_type, id_type) -> decision` callable<br/>- An @ref hgl::algorithm::empty_callback "empty_callback" |
+/// | EnqueuePredicate | Type of the callable deciding if a target vertex should be enqueued via a specific hyperedge. | Must be one of:<br/>- A `(const search_node<H>&) -> decision` callable<br/>- An @ref hgl::algorithm::empty_callback "empty_callback" |
+/// | PreVisitCallback | Type of the callable executed immediately before `VisitCallback`. | Must be one of:<br/>- A `(const search_node<H>&) -> void` callable<br/>- An @ref hgl::algorithm::empty_callback "empty_callback" |
+/// | 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" |
+///
+/// @param hypergraph The hypergraph to traverse.
+/// @param initial_queue_content The initial set of search nodes to begin the traversal from.
+/// @param visit_pred Predicate to filter nodes immediately after popping them from the queue.
+/// @param visit Primary callback for node processing.
+/// @param traverse_he_pred Predicate to determine if an incident hyperedge should be traversed. Returns a @ref hgl::algorithm::decision "decision":
+/// - `accept` to traverse the hyperedge,
+/// - `reject` to skip the hyperedge,
+/// - `abort` to terminate the BFS entirely.
+/// @param enqueue_pred Predicate to determine if an adjacent vertex should be queued via a hyperedge. Returns a @ref hgl::algorithm::decision "decision":
+/// - `accept` to enqueue the vertex's search node,
+/// - `reject` to skip the node,
+/// - `abort` to terminate the BFS entirely.
+/// @param pre_visit Callback executed prior to the primary visit logic.
+/// @param post_visit Callback executed after all adjacent elements of the current node have been processed.
+/// @return `true` if the search completed normally, `false` if it was explicitly aborted via a callback.
+/// @hideparams
 template <
     traversal_direction Dir = traversal_direction::forward,
     traits::c_hypergraph H,
     traits::c_forward_range_of<search_node<H>> InitQueueRangeType = std::vector<search_node<H>>,
     traits::c_optional_predicate<const search_node<H>&> VisitPredicate = empty_callback,
     traits::c_optional_predicate<const search_node<H>&> VisitCallback = empty_callback,
     traits::c_optional_decision_predicate<typename H::id_type, typename H::id_type>
-        TraverseHyperedgePredicate = empty_callback,
+        TraverseHePredicate = empty_callback,
     traits::c_decision_predicate<const search_node<H>&> EnqueuePredicate = empty_callback,
     traits::c_optional_callback<void, const search_node<H>&> PreVisitCallback = empty_callback,
     traits::c_optional_callback<void, const search_node<H>&> PostVisitCallback = empty_callback>
@@ -27,7 +97,7 @@ bool bfs(
     const InitQueueRangeType& initial_queue_content,
     const VisitPredicate& visit_pred = {},
     const VisitCallback& visit = {},
-    const TraverseHyperedgePredicate& traverse_he_pred = {},
+    const TraverseHePredicate& traverse_he_pred = {},
     const EnqueuePredicate& enqueue_pred = {},
     const PreVisitCallback& pre_visit = {},
     const PostVisitCallback& post_visit = {}
@@ -57,7 +127,7 @@ bool bfs(
                 return false;
 
         for (const auto he_id : policy::target_hyperedges(hypergraph, curr_node.vertex_id)) {
-            if constexpr (not traits::c_empty_callback<TraverseHyperedgePredicate>) {
+            if constexpr (not traits::c_empty_callback<TraverseHePredicate>) {
                 const auto traverse = traverse_he_pred(he_id, curr_node.vertex_id);
                 if (traverse == decision::abort)
                     return false;

include/hgl/algorithm/traversal/breadth_first_search.hpp

@@ -31,7 +31,7 @@ result_type<Result, search_tree<H>> breadth_first_search(
     if (root_vertex_id != no_root) {
         bfs(
             hypergraph,
-            init_range<H>(root_vertex_id),
+            init_node_range<H>(root_vertex_id),
             default_visit_predicate<H>(visited_vertices),
             default_visit_callback<H, Result>(visited_vertices, stree),
             default_traverse_hyperedge_predicate(visited_hyperedges),
@@ -44,7 +44,7 @@ result_type<Result, search_tree<H>> breadth_first_search(
         for (const auto root_id : hypergraph.vertex_ids())
             bfs(
                 hypergraph,
-                init_range<H>(root_id),
+                init_node_range<H>(root_id),
                 default_visit_predicate<H>(visited_vertices),
                 default_visit_callback<H, Result>(visited_vertices, stree),
                 default_traverse_hyperedge_predicate(visited_hyperedges),