alg templates doc refinement

Author: SpectraL519

docs/gl/algorithms/overview.md

@@ -11,10 +11,11 @@ This separation ensures maximum code reuse, provides strict zero-cost abstractio
 Located at the lowest level, the generic templates define the strict structural execution of a search. They know nothing about *shortest paths*, *spanning trees*, or *cycle detection*. Their only responsibility is to manage the pending elements (a queue, stack, or priority queue) and invoke a series of user-provided callback hooks at specific moments during the traversal.
 
 The core generic templates include:
-- [**`bfs`**](templates.md#breadth-first-search-bfs): A queue-based Breadth-First Search engine.
-- [**`dfs`**](templates.md#depth-first-search-dfs): A stack-based, iterative Depth-First Search engine.
-- [**`r_dfs`**](templates.md#recursive-depth-first-search-r_dfs): A recursive Depth-First Search engine utilizing the call stack.
-- [**`pfs`**](templates.md#priority-first-search-pfs): A priority-queue-based Priority-First Search engine for custom heuristics.
+
+- [**`bfs`**](templates.md#the-core-engines): A queue-based Breadth-First Search engine.
+- [**`dfs`**](templates.md#the-core-engines): A stack-based, iterative Depth-First Search engine.
+- [**`r_dfs`**](templates.md#the-core-engines): A recursive Depth-First Search engine utilizing the call stack.
+- [**`pfs`**](templates.md#the-core-engines): A priority-queue-based Priority-First Search engine for custom heuristics.
 
 ### 2. The Concrete Algorithms
 

docs/gl/algorithms/templates.md

@@ -8,14 +8,14 @@ All engines operate on a similar fundamental principle: pop a node from a fronti
 
 The library provides four primary traversal engines.
 
-* [**`bfs` (Breadth-First Search)**](../../cpp-gl/group__GL-Algorithm.md#function-bfs): Uses a `std::queue`. Explores the graph level by level, expanding uniformly outward from the initial range.
-* [**`dfs` (Depth-First Search)**](../../cpp-gl/group__GL-Algorithm.md#function-dfs): Uses a `std::stack`. Plunges as deeply as possible along a branch before backtracking.
-* [**`r_dfs` (Recursive DFS)**](../../cpp-gl/group__GL-Algorithm.md#function-r_dfs): Uses the C++ call stack. Instead of an initial range, it is initiated with a specific `start_id`. It operates identically to `dfs` but requires external logic to manage abort signals, as returning from the recursion only unwinds one level.
-* [**`pfs` (Priority-First Search)**](../../cpp-gl/group__GL-Algorithm.md#function-pfs): Uses a `std::priority_queue`. Requires a custom comparator (`PQCmp`) to mathematically order the frontier. This is the underlying engine for algorithms like Dijkstra and Prim.
+- [**`bfs` (Breadth-First Search)**](../../cpp-gl/group__GL-Algorithm.md#function-bfs): Uses a `std::queue`. Explores the graph level by level, expanding uniformly outward from the initial range.
+- [**`dfs` (Depth-First Search)**](../../cpp-gl/group__GL-Algorithm.md#function-dfs): Uses a `std::stack`. Dives as deeply as possible along a branch before backtracking.
+- [**`r_dfs` (Recursive DFS)**](../../cpp-gl/group__GL-Algorithm.md#function-r_dfs): Uses the C++ call stack. Instead of an initial range, it is initiated with a specific starting vertex ID. It operates identically to `dfs` but requires external logic to manage abort signals, as returning from the recursion only unwinds one level.
+- [**`pfs` (Priority-First Search)**](../../cpp-gl/group__GL-Algorithm.md#function-pfs): Uses a `std::priority_queue`. Requires a custom comparator (`PQCmp`) to mathematically order the frontier. This is the underlying engine for algorithms like Dijkstra and Prim.
 
 ## The Callback Sequence
 
-The true power of the generic templates lies in their callback hooks. Every iteration of the engine loop rigidly follows a defined sequence. By injecting custom lambdas (or omitting them via `empty_callback`), you dictate the algorithm's behavior.
+The true power of the generic templates lies in their callback/predicate hooks. Every iteration of the engine loop rigidly follows a defined sequence. By injecting custom lambdas (or omitting them via the [**empty_callback**](../../cpp-gl/structgl_1_1algorithm_1_1empty__callback.md)), you dictate the algorithm's behavior.
 
 ### Execution Flowchart
 
@@ -31,62 +31,80 @@ For a single popped node in `bfs`, `dfs`, or `pfs`, the execution flow looks exa
    The primary callback. If this returns `false`, the entire search is immediately aborted.
 
 4. **Edge Iteration**
-   The engine iterates over every outgoing edge connected to the `vertex_id`. For each edge:
+   The engine iterates over every outgoing edge connected to the `vertex_id`. For each edge it calls:
 
-   * **`enqueue_vertex_pred(target_id, edge)`**
-     Evaluates the target vertex. Returns a `gl::algorithm::decision`:
-     * `abort`: Kills the entire algorithm.
-     * `reject`: Ignores this edge and moves to the next.
-     * `accept`: Approves the target for enqueueing.
+      - **`enqueue_node_pred(target_id, edge)`**
 
-   * **`make_node(target_id, vertex_id, edge)`** *(PFS Only)*
-     If the target was accepted, this hook allows you to construct a custom object to push into the search frontier.
+        Evaluates whether a new search node should be created for the target. Returns a [**decision**](../../cpp-gl/structgl_1_1algorithm_1_1decision.md):
+
+          - `abort`: Kills the entire algorithm.
+          - `reject`: Ignores this edge and moves to the next.
+          - `accept`: Approves the target for enqueueing.
+
+      - **`make_node(target_id, vertex_id, edge)`** *(PFS Only)*
+
+        If the target was accepted, this hook allows you to construct a custom object to push into the search frontier.
 
 5. **`post_visit(vertex_id)`**
    Executed after all adjacent edges have been evaluated and processed.
 
-## Custom Node Injection (`pfs`)
+## Custom Node Injection (PFS)
 
-While `bfs` and `dfs` strictly operate on the lightweight `gl::algorithm::search_node`, the `pfs` (Priority-First Search) engine often requires tracking dynamic state alongside the vertex ID.
+While BFS and DFS templates strictly operate on the lightweight [**gl::algorithm::search_node<G>**](../../cpp-gl/structgl_1_1algorithm_1_1search__node.md), the Priority-First Search template often requires tracking dynamic state alongside the vertex ID.
 
 For instance, in Dijkstra's algorithm, the priority queue must sort nodes based on their accumulated distance from the starting point. You cannot sort based purely on the vertex ID.
 
-`pfs` solves this by automatically inferring the `NodeType` from the initial queue range container. If your `NodeType` requires more than just `(target_id, pred_id)` to construct, you must provide a `MakeNodeCallback`.
+`pfs` solves this by automatically inferring the `NodeType` from the initial queue range container. If your `NodeType` requires more than just `(target_id, pred_id)` to construct, you must provide `MakeNodeCallback` which is a `(vertex_id, pred_id, edge) -> NodeType` callback.
 
 ### Example: PFS Stateful Nodes
 
 ```cpp
-// 1. Define a custom stateful node
-struct path_node {
+struct path_node { // (1)!
     gl::default_id_type vertex_id;
     gl::default_id_type pred_id;
     int accumulated_distance;
 };
 
-// 2. Define the priority comparator
-auto cmp = [](const path_node& a, const path_node& b) {
-    return a.accumulated_distance > b.accumulated_distance; // Min-Heap
+std::vector<int> distance_map( // (2)!
+  graph.n_vertices(), std::numeric_limits<int>::max()
+);
+distance_map[start_id] = 0;
+
+auto cmp = [](const path_node& a, const path_node& b) { // (3)!
+    return a.accumulated_distance > b.accumulated_distance;
 };
 
-// 3. Setup the initial range
-std::vector<path_node> init_range = { path_node{start_id, start_id, 0} };
+std::vector<path_node> init_nodes = { // (4)!
+    path_node{start_id, start_id, 0}
+};
 
-// 4. Run the PFS engine
-gl::algorithm::pfs(
+gl::algorithm::pfs( // (5)!
     graph,
     cmp,
-    init_range,
-    gl::algorithm::empty_callback{}, // visit_vertex_pred
-    gl::algorithm::empty_callback{}, // visit
-
-    // enqueue_vertex_pred
-    [&](auto target_id, const auto& edge) {
-        return distance_map[target_id] > current_dist + edge.properties().weight;
+    init_nodes,
+    gl::algorithm::empty_callback{}, // (6)!
+    gl::algorithm::empty_callback{},
+    [&](auto target_id, const auto& edge) { // (7)!
+        return distance_map[target_id] > distance_map[edge.source()] + edge.properties().weight;
     },
-
-    // make_node - Construct the stateful object for the queue
-    [&](auto target_id, auto source_id, const auto& edge) {
-        int new_dist = current_dist + edge.properties().weight;
+    [&](auto target_id, auto source_id, const auto& edge) { // (8)!
+        int new_dist = distance_map[source_id] + edge.properties().weight;
+        distance_map[target_id] = new_dist; // (9)!
         return path_node{target_id, source_id, new_dist};
     }
 );
+```
+
+1. Define a custom stateful node tracking the distance accumulated so far.
+2. Initialize a global distance map with "infinity", setting the start vertex distance to 0.
+3. Define the priority comparator for a distance-based Min-Heap.
+4. Setup the initial range containing the root node.
+5. Run the Priority-First Search engine.
+6. Define an empty vertex visit predicate and vertex visit callback.
+7. Define the node enqueue predicate to only enqueue nodes that could yield paths shorter than those already discovered.
+8. Define the callback which constructs a stateful node for the algorithm queue.
+9. Update the global distance map to reflect the newly discovered shorter path.
+
+> [!NOTE] Algorithm Desing
+>
+> The example above is very similar, though not the same, to how the Dijkstra's algorithm implementation is designed within the library.