Merge pull request #265 from marvin-hansen/main

feat: Implement and test Brandes' Betweenness Centrality  Algorithm

Author: marvin-hansen

ultragraph/src/lib.rs

@@ -9,10 +9,12 @@ pub mod errors;
 
 mod traits;
 pub mod types;
+pub mod utils;
+
 // 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_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,20 @@
  * Copyright (c) "2025" . The DeepCausality Authors and Contributors. All Rights Reserved.
  */
 
-use crate::{GraphError, GraphView};
+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::*;
 
-/// 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,22 @@
+/*
+ * 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.
+    fn betweenness_centrality(
+        &self,
+        directed: bool,
+        normalized: bool,
+    ) -> Result<Vec<(usize, f64)>, GraphError>;
+
+    /// Calculates betweenness centrality across a specific set of critical 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,33 @@
+/*
+ * 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.
+    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,10 @@
+/*
+ * 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.
+    fn strongly_connected_components(&self) -> Result<Vec<Vec<usize>>, GraphError>;
+}

ultragraph/src/traits/graph_algo_topological.rs

@@ -0,0 +1,18 @@
+/*
+ * 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.
+    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/graph_traversal.rs

@@ -4,12 +4,6 @@ pub trait GraphTraversal<N, W>: GraphView<N, W> {
     // --- Traversal ---
 
     /// Returns a non-allocating iterator over the direct successors (outgoing edges) of node `a`.
-    ///
-    /// This method provides a direct, high-performance view into the graph's internal
-    /// structure without any intermediate memory allocations.
-    ///
-    /// # Returns
-    /// A `Result` containing an iterator that yields the `usize` indices of the neighbor nodes.
     fn outbound_edges(&self, a: usize) -> Result<impl Iterator<Item = usize> + '_, GraphError>;
 
     /// Returns a non-allocating iterator over the direct predecessors (incoming edges) of node `a`.

ultragraph/src/traits/graph_view.rs

@@ -18,15 +18,7 @@ pub trait GraphView<N, W> {
     fn contains_edge(&self, a: usize, b: usize) -> bool;
     fn number_edges(&self) -> usize;
 
-    /// Returns a vector of immutable references to all active nodes in the graph.
-    ///
-    /// The order of the nodes in the returned vector is not guaranteed.
-    /// This operation is O(V) as it iterates through all possible node slots
     fn get_all_nodes(&self) -> Vec<&N>;
-
-    /// Retrieves a list of all outgoing edges from a given source node.
-    /// Returns `None` if the source node does not exist.
-    /// The returned vector contains tuples of `(target_node_index, edge_weight_reference)`.
     fn get_edges(&self, source: usize) -> Option<Vec<(usize, &W)>>;
 
     fn get_last_index(&self) -> Option<usize>;

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;