Refactored ultragraph's trait system and algo implementations for better maintainability.

Signed-off-by: Marvin Hansen <[email protected]>

Author: marvin-hansen

ultragraph/src/lib.rs

@@ -12,7 +12,11 @@ pub mod types;
 // Errors
 pub use crate::errors::graph_error::GraphError;
 // Traits
-pub use crate::traits::graph_algo::GraphAlgorithms;
+pub use crate::traits::graph_algo::*;
+pub use crate::traits::graph_algo_centrality::*;
+pub use crate::traits::graph_algo_pathfinder::*;
+pub use crate::traits::graph_algo_structural::*;
+pub use crate::traits::graph_algo_topological::*;
 pub use crate::traits::graph_freeze::Freezable;
 pub use crate::traits::graph_mut::GraphMut;
 pub use crate::traits::graph_traversal::GraphTraversal;

ultragraph/src/traits/graph_algo.rs

@@ -3,73 +3,18 @@
  * Copyright (c) "2025" . The DeepCausality Authors and Contributors. All Rights Reserved.
  */
 
-use crate::{GraphError, GraphView};
+use crate::traits::graph_algo_topological::TopologicalGraphAlgorithms;
+use crate::{CentralityGraphAlgorithms, PathfindingGraphAlgorithms, StructuralGraphAlgorithms};
 
-/// Defines a suite of high-performance, read-only analytical algorithms.
+/// A comprehensive suite of graph algorithms.
 ///
-/// This trait is intended for implementation on static, optimized graph structures
-/// like `next_graph::CsmGraph` to validate their structure and properties.
-pub trait GraphAlgorithms<N, W>: GraphView<N, W> {
-    // --- Structural Validation Algorithms ---
-
-    /// Finds a single cycle in the graph and returns the path of nodes that form it.
-    ///
-    /// This is the most powerful cycle detection method, as it not only confirms the
-    /// presence of a cycle but also identifies the specific nodes involved. This is
-    /// invaluable for debugging dynamically generated graphs.
-    ///
-    /// # Returns
-    /// `Some(Vec<usize>)` containing the sequence of node indices that form a cycle
-    /// (e.g., `[0, 1, 0]`). Returns `None` if the graph is a DAG.
-    fn find_cycle(&self) -> Result<Option<Vec<usize>>, GraphError>;
-
-    /// Checks if the graph contains any directed cycles.
-    ///
-    /// This method should be implemented as a simple call to `self.find_cycle().is_some()`.
-    fn has_cycle(&self) -> Result<bool, GraphError>;
-
-    /// Computes a topological sort of the graph, if it is a Directed Acyclic Graph (DAG).
-    /// Returns `None` if the graph contains a cycle.
-    fn topological_sort(&self) -> Result<Option<Vec<usize>>, GraphError>;
-
-    // --- Pathfinding and Reachability Algorithms ---
-
-    /// Checks if a path of any length exists from a start to a stop index.
-    fn is_reachable(&self, start_index: usize, stop_index: usize) -> Result<bool, GraphError>;
-
-    /// Returns the length of the shortest path (in number of nodes) from a start to a stop index.
-    fn shortest_path_len(
-        &self,
-        start_index: usize,
-        stop_index: usize,
-    ) -> Result<Option<usize>, GraphError>;
-
-    /// Finds the complete shortest path from a start to a stop index.
-    fn shortest_path(
-        &self,
-        start_index: usize,
-        stop_index: usize,
-    ) -> Result<Option<Vec<usize>>, GraphError>;
-
-    /// Finds the shortest path in a weighted graph using Dijkstra's algorithm.
-    ///
-    /// The edge weight type `W` must support addition, comparison, and have a zero value.
-    ///
-    /// # Returns
-    /// A tuple containing the sequence of node indices in the path and the total cost of that path.
-    /// Returns `None` if no path exists.
-    fn shortest_weighted_path(
-        &self,
-        start_index: usize,
-        stop_index: usize,
-    ) -> Result<Option<(Vec<usize>, W)>, GraphError>
-    where
-        W: Copy + Ord + Default + std::ops::Add<Output = W>;
-
-    /// Finds all Strongly Connected Components in the graph using Tarjan's algorithm.
-    ///
-    /// # Returns
-    /// A vector of vectors, where each inner vector is a list of node indices
-    /// belonging to a single SCC.
-    fn strongly_connected_components(&self) -> Result<Vec<Vec<usize>>, GraphError>;
+/// This trait aggregates several focused algorithm traits into a single, convenient
+/// supertrait. A type that implements `GraphAlgorithms` has access to all methods
+/// from the component traits.
+pub trait GraphAlgorithms<N, W>:
+    TopologicalGraphAlgorithms<N, W>
+    + PathfindingGraphAlgorithms<N, W>
+    + StructuralGraphAlgorithms<N, W>
+    + CentralityGraphAlgorithms<N, W>
+{
 }

ultragraph/src/traits/graph_algo_centrality.rs

@@ -0,0 +1,61 @@
+/*
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) "2025" . The DeepCausality Authors and Contributors. All Rights Reserved.
+ */
+use crate::{GraphError, GraphView};
+
+pub trait CentralityGraphAlgorithms<N, W>: GraphView<N, W> {
+    /// Calculates the betweenness centrality of each node in the graph.
+    ///
+    /// Betweenness centrality measures a node's importance by counting how often it
+    /// appears on the shortest paths between all other pairs of nodes. It is a powerful
+    /// metric for identifying bottlenecks, bridges, and critical control points in a network.
+    ///
+    /// The implementation uses Brandes' algorithm, which is highly efficient.
+    ///
+    /// # Arguments
+    ///
+    /// * `directed`: If `true`, the calculation considers the graph's edge directions.
+    ///   If `false`, all edges are treated as bidirectional.
+    /// * `normalized`: If `true`, the centrality scores are normalized by dividing by the
+    ///   number of possible pairs of nodes. This allows for comparison between graphs of
+    ///   different sizes. If `false`, the raw count of paths is returned.
+    ///
+    /// # Returns
+    ///
+    /// A `Result` containing a vector of `(node_index, centrality_score)` tuples.
+    /// The centrality score is an `f64` representing the node's importance.
+    /// The vector is unsorted.
+    fn betweenness_centrality(
+        &self,
+        directed: bool,
+        normalized: bool,
+    ) -> Result<Vec<(usize, f64)>, GraphError>;
+
+    /// Calculates betweenness centrality across a specific set of critical pathways.
+    ///
+    /// This function is a highly efficient tool for targeted analysis, such as root cause
+    /// investigation or identifying bottlenecks in specific set of graph pathways. Instead of
+    /// analyzing all possible paths, it only considers the shortest paths between the
+    /// start and end nodes of the pathways you provide.
+    ///
+    /// The algorithm correctly routes these paths through the entire graph, ensuring that
+    /// the results are accurate even if the shortest path temporarily leaves a conceptual
+    /// "subgraph".
+    ///
+    /// # Arguments
+    /// * `pathways`: A slice of `(start_node, end_node)` tuples defining the pathways to analyze.
+    /// * `directed`: If `true`, considers edge directions.
+    /// * `normalized`: If `true`, normalizes scores by the number of provided pathways.
+    ///
+    /// # Returns
+    /// An unsorted vector of `(node_index, centrality_score)` tuples for nodes that lie on
+    /// one or more of the specified pathways.
+    ///
+    fn pathway_betweenness_centrality(
+        &self,
+        pathways: &[(usize, usize)],
+        directed: bool,
+        normalized: bool,
+    ) -> Result<Vec<(usize, f64)>, GraphError>;
+}

ultragraph/src/traits/graph_algo_pathfinder.rs

@@ -0,0 +1,39 @@
+/*
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) "2025" . The DeepCausality Authors and Contributors. All Rights Reserved.
+ */
+use crate::{GraphError, GraphView};
+
+pub trait PathfindingGraphAlgorithms<N, W>: GraphView<N, W> {
+    /// Checks if a path of any length exists from a start to a stop index.
+    fn is_reachable(&self, start_index: usize, stop_index: usize) -> Result<bool, GraphError>;
+
+    /// Returns the length of the shortest path (in number of nodes) from a start to a stop index.
+    fn shortest_path_len(
+        &self,
+        start_index: usize,
+        stop_index: usize,
+    ) -> Result<Option<usize>, GraphError>;
+
+    /// Finds the complete shortest path from a start to a stop index.
+    fn shortest_path(
+        &self,
+        start_index: usize,
+        stop_index: usize,
+    ) -> Result<Option<Vec<usize>>, GraphError>;
+
+    /// Finds the shortest path in a weighted graph using Dijkstra's algorithm.
+    ///
+    /// The edge weight type `W` must support addition, comparison, and have a zero value.
+    ///
+    /// # Returns
+    /// A tuple containing the sequence of node indices in the path and the total cost of that path.
+    /// Returns `None` if no path exists.
+    fn shortest_weighted_path(
+        &self,
+        start_index: usize,
+        stop_index: usize,
+    ) -> Result<Option<(Vec<usize>, W)>, GraphError>
+    where
+        W: Copy + Ord + Default + std::ops::Add<Output = W>;
+}

ultragraph/src/traits/graph_algo_structural.rs

@@ -0,0 +1,14 @@
+/*
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) "2025" . The DeepCausality Authors and Contributors. All Rights Reserved.
+ */
+use crate::{GraphError, GraphView};
+
+pub trait StructuralGraphAlgorithms<N, W>: GraphView<N, W> {
+    /// Finds all Strongly Connected Components in the graph using Tarjan's algorithm.
+    ///
+    /// # Returns
+    /// A vector of vectors, where each inner vector is a list of node indices
+    /// belonging to a single SCC.
+    fn strongly_connected_components(&self) -> Result<Vec<Vec<usize>>, GraphError>;
+}

ultragraph/src/traits/graph_algo_topological.rs

@@ -0,0 +1,27 @@
+/*
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) "2025" . The DeepCausality Authors and Contributors. All Rights Reserved.
+ */
+use crate::{GraphError, GraphView};
+
+pub trait TopologicalGraphAlgorithms<N, W>: GraphView<N, W> {
+    /// Finds a single cycle in the graph and returns the path of nodes that form it.
+    ///
+    /// This is the most powerful cycle detection method, as it not only confirms the
+    /// presence of a cycle but also identifies the specific nodes involved. This is
+    /// invaluable for debugging dynamically generated graphs.
+    ///
+    /// # Returns
+    /// `Some(Vec<usize>)` containing the sequence of node indices that form a cycle
+    /// (e.g., `[0, 1, 0]`). Returns `None` if the graph is a DAG.
+    fn find_cycle(&self) -> Result<Option<Vec<usize>>, GraphError>;
+
+    /// Checks if the graph contains any directed cycles.
+    ///
+    /// This method should be implemented as a simple call to `self.find_cycle().is_some()`.
+    fn has_cycle(&self) -> Result<bool, GraphError>;
+
+    /// Computes a topological sort of the graph, if it is a Directed Acyclic Graph (DAG).
+    /// Returns `None` if the graph contains a cycle.
+    fn topological_sort(&self) -> Result<Option<Vec<usize>>, GraphError>;
+}

ultragraph/src/traits/mod.rs

@@ -9,5 +9,9 @@ pub mod graph_mut;
 pub mod graph_traversal;
 pub mod graph_view;
 
+pub mod graph_algo_centrality;
+pub mod graph_algo_pathfinder;
+pub mod graph_algo_structural;
+pub mod graph_algo_topological;
 pub mod graph_freeze;
 pub mod graph_unfreeze;