Remove redundant namespace directives and consolidate error handling

.github/copilot-instructions.md

@@ -277,7 +277,8 @@ auto even_squares = numbers
 - **MUST**: Use these Aleph exception macros (defined in `ah-errors.H`):
   - `ah_domain_error_if(condition)` → for domain/logic errors (replaces `throw std::domain_error`)
   - `ah_runtime_error_if(condition)` → for runtime errors (replaces `throw std::runtime_error`)
-  - `ah_range_error_if(condition)` → for out-of-range errors (replaces `throw std::range_error`)
+  - `ah_out_of_range_error_if(condition)` → for out-of-range errors (replaces `throw std::out_of_range`)
+  - `ah_range_error_if(condition)` → for internal calculations that do not meet mathematical requirements (replaces `throw std::range_error`)
   - `ah_invalid_argument_if(condition)` → for invalid arguments (replaces `throw std::invalid_argument`)
   - Unconditional versions: `ah_domain_error()`, `ah_runtime_error()`, `ah_range_error()`, `ah_invalid_argument()`
   - `_unless` variants: `ah_domain_error_unless(condition)`, etc. (inverted logic)
@@ -286,7 +287,7 @@ auto even_squares = numbers
 - **Example (Aleph style - CORRECT)**:
   ```cpp
   ah_domain_error_if(x < 0) << "sqrt requires non-negative value, got " << x;
-  ah_range_error_if(index >= size) << "Index " << index << " out of range [0, " << size << ")";
+  ah_out_of_range_error_if(index >= size) << "Index " << index << " out of range [0, " << size << ")";
   ah_runtime_error_unless(file.is_open()) << "Failed to open file: " << filename;
   ```
 

Blossom.H

@@ -32,32 +32,31 @@
 /** @file Blossom.H
  *  @brief Edmonds' Blossom algorithm for maximum matching in general graphs.
  *
- *  This file implements the classic Edmonds-Blossom algorithm for
- *  maximum cardinality matching in undirected graphs.
+ *  This file implements the classic Edmonds-Blossom algorithm for finding a
+ *  maximum cardinality matching in an undirected graph. 
  *
- *  ## Problem solved
+ *  Unlike bipartite matching, general graph matching must account for odd 
+ *  cycles. The algorithm identifies such cycles (called "blossoms") and 
+ *  contracts them into single super-nodes to find augmenting paths that 
+ *  would otherwise be hidden.
  *
- *  Given an undirected graph \f$G=(V,E)\f$, find a matching of maximum
- *  cardinality, where a matching is a set of arcs with no shared endpoint.
+ *  ## Problem solved
+ *  Given an undirected graph@f$G=(V,E)@f$, find a matching@f$M@f$
+ *  (a set of arcs with no shared endpoints) such that@f$|M|@f$is maximized.
  *
  *  ## Highlights
+ *  - Works on **general** (non-bipartite) undirected graphs.
+ *  - Handles odd cycles through recursive blossom contraction and expansion.
+ *  - Supports all Aleph-w graph representations through the generic interface.
+ *  - Integrates with Aleph-w arc filters for selective matching.
  *
- *  - Works on general (non-bipartite) graphs
- *  - Handles odd cycles through blossom contraction
- *  - Supports all Aleph graph backends through the generic graph interface
- *    (`List_Graph`, `List_SGraph`, `Array_Graph`)
- *  - Can be filtered with Aleph arc filters
- *
- *  ## Complexity
- *
- *  - Time: \f$O(V^3)\f$
- *  - Space: \f$O(V + E)\f$
+ *  @example blossom_example.cc
  *
- *  @see tpl_bipartite.H For bipartite matching algorithms
- *  @see Hungarian.H For assignment problem matching
+ *  @see tpl_bipartite.H For specialized bipartite matching algorithms.
+ *  @see Hungarian.H For minimum/maximum weight assignment matching.
  *
  *  @ingroup Graphs
- *  @author Leandro Rabindranath León
+ *  @author Leandro Rabindranath Leon
  */
 
 # ifndef BLOSSOM_H
@@ -407,23 +406,25 @@ namespace Aleph
 
   /** @brief Computes a maximum cardinality matching in a general graph.
    *
-   *  This routine applies Edmonds' Blossom algorithm to an undirected
-   *  graph and stores the resulting matching arcs in `matching`.
+   *  Applies Edmonds' Blossom algorithm to an undirected graph. The resulting 
+   *  matching arcs are stored in the provided list.
    *
-   *  @tparam GT Graph type.
-   *  @tparam SA Arc filter type.
+   *  @tparam GT Graph type (e.g., `List_Graph`).
+   *  @tparam SA Arc filter type (defaults to show all arcs).
+   *
+   *  @param[in]  g        The undirected graph to process.
+   *  @param[out] matching A list where the arcs of the maximum matching will be stored.
+   *  @param[in]  sa       An optional arc filter instance.
    *
-   *  @param[in] g Undirected graph.
-   *  @param[out] matching List of arcs that compose a maximum matching.
-   *  @param[in] sa Arc filter used during traversal.
+   *  @return The cardinality of the maximum matching found (@f$|M|@f$).
    *
-   *  @return Cardinality of the maximum matching (`matching.size()`).
+   *  @throws ah_domain_error if `g` is a directed graph (digraph).
+   *  @throws ah_bad_alloc if memory allocation for internal structures fails.
    *
-   *  @exception domain_error If `g` is a digraph.
+   *  @note Self-loops and parallel arcs are handled correctly. Self-loops are 
+   *        ignored as they cannot participate in a matching.
    *
-   *  @note Self-loops are ignored because they cannot belong to a matching.
-   *  @note If multiple parallel arcs connect the same endpoints, one of them
-   *        may be selected.
+   *  @par **Complexity**: Time@f$O(V^3)@f$, Space@f$O(V + E)@f$.
    *
    *  @ingroup Graphs
    */

Blossom_Weighted.H

@@ -37,9 +37,9 @@
  *
  *  ## Problem solved
  *
- *  Given an undirected graph @f$G=(V,E)@f$ where each edge @f$e \in E@f$ 
- *  has a weight @f$w(e)@f$, find a matching @f$M@f$ such that 
- *  @f$\sum_{e \in M} w(e)@f$ is maximized.
+ *  Given an undirected graph@f$G=(V,E)@f$where each edge@f$e \in E@f$
+ *  has a weight@f$w(e)@f$, find a matching@f$M@f$such that 
+ * @f$\sum_{e \in M} w(e)@f$is maximized.
  *
  *  ## Highlights
  *
@@ -53,8 +53,8 @@
  *
  *  ## Complexity
  *
- *  - Time: @f$O(V^3)@f$
- *  - Space: @f$O(V + E)@f$
+ *  - Time:@f$O(V^3)@f$
+ *  - Space:@f$O(V + E)@f$
  *
  *  ## Weight model
  *

Graph_Coloring.H

@@ -39,17 +39,17 @@
  *
  *  Graph coloring is fundamentally an undirected problem. All algorithms in
  *  this module treat directed arcs as bidirectional constraints: if there
- *  is an arc @f$u \to v@f$, then @f$u@f$ and @f$v@f$ cannot have the same color.
+ *  is an arc@f$u \to v@f$, then@f$u@f$and@f$v@f$cannot have the same color.
  *
  *  ## Included Algorithms:
  *
  *  - **Greedy Coloring**: Processes nodes in their natural iteration order.
- *    Complexity: @f$O((V+E) \log V)@f$.
+ *    Complexity:@f$O((V+E) \log V)@f$.
  *  - **Welsh-Powell**: Sorts nodes by decreasing degree before coloring.
- *    Complexity: @f$O((V+E) \log V)@f$.
+ *    Complexity:@f$O((V+E) \log V)@f$.
  *  - **DSatur (Degree of Saturation)**: Adaptive heuristic that prioritizes
  *    nodes with the most distinct colors in their neighborhood.
- *    Complexity: @f$O(V^2 + E \log V)@f$.
+ *    Complexity:@f$O(V^2 + E \log V)@f$.
  *  - **Chromatic Number**: Exact minimum colors (@f$\chi(G)@f$) for small
  *    graphs (up to 64 nodes) via backtracking. Complexity: Exponential.
  *
@@ -164,7 +164,7 @@ void validate_no_self_loops(const GT &g)
  *
  *  Assigns each node the smallest 0-based color index not already used by
  *  any of its colored neighbors, visiting nodes in their natural graph-
- *  iteration order.  Uses at most @f$\Delta+1@f$ colors where @f$\Delta@f$
+ *  iteration order.  Uses at most@f$\Delta+1@f$colors where@f$\Delta@f$
  *  is the maximum degree.
  *
  *  @tparam GT Graph type (List_Graph, List_Digraph, Array_Graph, …).
@@ -174,14 +174,14 @@ void validate_no_self_loops(const GT &g)
  *  @param[out] colors Output map from @c GT::Node* to 0-based color index.
  *                     Cleared and overwritten on entry.
  *
- *  @return Number of distinct colors used (@f$\geq 1@f$ for non-empty graphs,
+ *  @return Number of distinct colors used (@f$\geq 1@f$for non-empty graphs,
  *          0 for an empty graph).
  *
  *  @throws std::domain_error if @p g contains a self-loop.
  *
  *  @pre No self-loops in @p g.
  *
- *  @note **Complexity**: @f$O((V+E) \log V)@f$.
+ *  @note **Complexity**:@f$O((V+E) \log V)@f$.
  *
  *  @note **Thread safety**: not thread-safe.  Temporarily writes to
  *        @c NODE_COOKIE on every node during execution; prior cookie values
@@ -250,8 +250,8 @@ size_t greedy_coloring(const GT &g, DynMapTree<typename GT::Node *, size_t> &col
  *
  *  @pre No self-loops in @p g.
  *
- *  @note **Complexity**: @f$O((V+E) \log V)@f$ (sort step dominates for
- *        dense graphs: @f$O(V \log V)@f$).
+ *  @note **Complexity**:@f$O((V+E) \log V)@f$(sort step dominates for
+ *        dense graphs:@f$O(V \log V)@f$).
  *
  *  @note **Thread safety**: not thread-safe.  Temporarily writes to
  *        @c NODE_COOKIE on every node; saved and restored via
@@ -333,7 +333,7 @@ size_t welsh_powell_coloring(const GT &g, DynMapTree<typename GT::Node *, size_t
  *
  *  @pre No self-loops in @p g.
  *
- *  @note **Complexity**: @f$O(V^2 + E \log V)@f$.
+ *  @note **Complexity**:@f$O(V^2 + E \log V)@f$.
  *
  *  @note **Thread safety**: not thread-safe.  Temporarily writes to
  *        @c NODE_COOKIE on every node; saved and restored via
@@ -429,7 +429,7 @@ size_t dsatur_coloring(const GT &g, DynMapTree<typename GT::Node *, size_t> &col
  *          connects same-colored endpoints; @c false otherwise (including
  *          self-loops and missing/foreign map entries).
  *
- *  @note **Complexity**: @f$O((V+E) \log V)@f$.
+ *  @note **Complexity**:@f$O((V+E) \log V)@f$.
  *
  *  @note Does not modify any graph state.  Thread-safe provided @p g and
  *        @p colors are not concurrently modified.
@@ -472,7 +472,7 @@ template <class GT, class SA = Dft_Show_Arc<GT>>
 /** @brief Computes the exact chromatic number of a small graph.
  *
  *  Uses DSatur to obtain an upper bound, then performs binary search with
- *  backtracking to find the minimum @f$k@f$ for which a valid @f$k@f$-coloring
+ *  backtracking to find the minimum@f$k@f$for which a valid@f$k@f$-coloring
  *  exists.  Applicable only to graphs with at most 64 nodes.
  *
  *  @tparam GT Graph type (List_Graph, List_Digraph, Array_Graph, …).
@@ -484,7 +484,7 @@ template <class GT, class SA = Dft_Show_Arc<GT>>
  *                     for an optimal coloring.  Cleared and overwritten on
  *                     entry.
  *
- *  @return The chromatic number @f$\chi(G)@f$ (0 for an empty graph,
+ *  @return The chromatic number@f$\chi(G)@f$(0 for an empty graph,
  *          1 if the graph has no edges).
  *
  *  @throws std::domain_error if @p g has more than 64 nodes or contains
@@ -493,7 +493,7 @@ template <class GT, class SA = Dft_Show_Arc<GT>>
  *  @pre @c g.get_num_nodes() <= 64 and no self-loops in @p g.
  *
  *  @note **Complexity**: Exponential in the worst case (backtracking over
- *        all @f$k@f$-colorings).  Practical for graphs up to ~30–40 nodes.
+ *        all@f$k@f$-colorings).  Practical for graphs up to ~30–40 nodes.
  *
  *  @note **Thread safety**: not thread-safe.  Temporarily writes to
  *        @c NODE_COOKIE on every node; saved and restored via

HLD.H

@@ -34,7 +34,7 @@
  *
  *  Heavy-Light Decomposition (HLD) partitions a rooted tree into
  *  @e heavy chains such that any root-to-node path crosses at most
- *  @f$O(\log n)@f$ chains.  Combined with a segment tree, this yields
+ * @f$O(\log n)@f$chains.  Combined with a segment tree, this yields
  *  efficient path queries and point updates.
  *
  *  @par Concept Visualization