Merge pull request #264 from marvin-hansen/main

Added Tarjan's algorithm to UltraGraph.

Author: marvin-hansen

ultragraph/README.md

@@ -73,6 +73,46 @@ This is the high-performance, read-only state.
 If you need to make further changes after a period of analysis, `g.unfreeze()` efficiently converts the `CsmGraph` back
 into a `DynamicGraph`, allowing the cycle of mutation and analysis to begin again.
 
+## ⚙️ Graph Algorithms
+
+The `UltraGraph` crate provides a suite of high-performance, read-only analytical algorithms for
+graph analysis. These algorithms are implemented on static, optimized graph structures for efficient
+computation.
+
+* **`find_cycle()`**: Finds a single cycle in the
+  graph and returns the path of nodes that form it.
+  Returns `None` if the graph is a Directed Acyclic Graph
+  (DAG).
+
+* **`has_cycle()`**: Checks if the graph contains any
+  directed cycles.
+
+* **`topological_sort()`**: Computes a topological
+  sort of the graph if it is a DAG. Returns `None` if the
+  graph contains a cycle.
+
+* **`is_reachable(start_index, stop_index)`**: Checks
+  if a path of any length exists from a start node to a
+  stop node.
+
+* **`shortest_path_len(start_index, stop_index)`**:
+  Returns the length (number of nodes) of the shortest
+  path from a start node to a stop node.
+
+* **`shortest_path(start_index, stop_index)`**: Finds
+  the complete shortest path (sequence of nodes) from a
+  start node to a stop node.
+
+* **`shortest_weighted_path(start_index, stop_
+ index)`**: Finds the shortest path in a weighted graph
+  using Dijkstra's algorithm, returning the path and its
+  total cost.
+
+* **`strongly_connected_components()`**: Finds all
+  Strongly Connected Components (SCCs) in the graph using
+  Tarjan's algorithm, returning a list of node sets, where
+  each set represents an SCC.
+
 ## 🚀 Benchmark Results
 
 ### Dynamic Graph

ultragraph/src/errors/graph_error.rs

@@ -29,6 +29,9 @@ pub enum GraphError {
 
     /// Root node already exists
     RootNodeAlreadyExists,
+
+    /// Graph algorithm error
+    AlgorithmError(&'static str),
 }
 
 impl fmt::Display for GraphError {
@@ -67,6 +70,10 @@ impl fmt::Display for GraphError {
             Self::RootNodeAlreadyExists => {
                 write!(f, "Root node already exists")
             }
+
+            Self::AlgorithmError(e) => {
+                write!(f, "AlgorithmError: {e}")
+            }
         }
     }
 }

ultragraph/src/traits/graph_algo.rs

@@ -66,11 +66,10 @@ pub trait GraphAlgorithms<N, W>: GraphView<N, W> {
     where
         W: Copy + Ord + Default + std::ops::Add<Output = W>;
 
-    // Implement later.
-    // /// 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>;
+    /// 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/types/storage/graph_csm/graph_csm_algo.rs

@@ -1,4 +1,6 @@
 use crate::{CsmGraph, GraphAlgorithms, GraphError, GraphView};
+use std::cmp::Reverse;
+use std::collections::BinaryHeap;
 use std::collections::VecDeque;
 use std::slice;
 
@@ -271,7 +273,6 @@ where
         Ok(Some(path))
     }
 
-    /// Finds the shortest path between two nodes in a weighted graph using Dijkstra's algorithm.
     fn shortest_weighted_path(
         &self,
         start_index: usize,
@@ -280,9 +281,6 @@ where
     where
         W: Copy + Ord + Default + std::ops::Add<Output = W>,
     {
-        use std::cmp::Reverse;
-        use std::collections::BinaryHeap;
-
         if !self.contains_node(start_index) || !self.contains_node(stop_index) {
             return Ok(None);
         }
@@ -329,7 +327,7 @@ where
                 let weight = self.forward_edges.weights[i];
                 let new_dist = dist + weight;
 
-                if distances[v].map_or(true, |d| new_dist < d) {
+                if distances[v].is_none() || new_dist < distances[v].unwrap() {
                     distances[v] = Some(new_dist);
                     predecessors[v] = Some(u);
                     pq.push((Reverse(new_dist), v));
@@ -339,4 +337,110 @@ where
 
         Ok(None)
     }
+
+    /// 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> {
+        let num_nodes = self.number_nodes();
+        if num_nodes == 0 {
+            return Ok(Vec::new());
+        }
+
+        let mut dfs_num: Vec<Option<usize>> = vec![None; num_nodes];
+        let mut low_link: Vec<Option<usize>> = vec![None; num_nodes];
+        let mut on_stack: Vec<bool> = vec![false; num_nodes];
+        let mut tarjan_stack: Vec<usize> = Vec::new();
+        let mut time: usize = 0;
+        let mut sccs: Vec<Vec<usize>> = Vec::new();
+
+        // Stack for iterative DFS. Stores (node_index, iterator_over_neighbors)
+        // The iterator is used to keep track of which neighbor to visit next.
+        let mut dfs_stack: Vec<(usize, slice::Iter<'_, usize>)> = Vec::new();
+
+        for i in 0..num_nodes {
+            if dfs_num[i].is_none() {
+                // Start DFS from node i
+                let start_offset = self.forward_edges.offsets[i];
+                let end_offset = self.forward_edges.offsets[i + 1];
+                let neighbors_iter = self.forward_edges.targets[start_offset..end_offset].iter();
+                dfs_stack.push((i, neighbors_iter));
+
+                // Simulate recursion
+                while let Some((u, neighbors)) = dfs_stack.last_mut() {
+                    // On first visit to u (pre-order traversal)
+                    if dfs_num[*u].is_none() {
+                        dfs_num[*u] = Some(time);
+                        low_link[*u] = Some(time);
+                        time += 1;
+                        tarjan_stack.push(*u);
+                        on_stack[*u] = true;
+                    }
+
+                    // Process neighbors
+                    if let Some(&v) = neighbors.next() {
+                        if dfs_num[v].is_none() {
+                            // Neighbor v not visited, "recurse"
+                            let v_start_offset = self.forward_edges.offsets[v];
+                            let v_end_offset = self.forward_edges.offsets[v + 1];
+                            let v_neighbors_iter =
+                                self.forward_edges.targets[v_start_offset..v_end_offset].iter();
+                            dfs_stack.push((v, v_neighbors_iter));
+                        } else if on_stack[v] {
+                            // Neighbor v is on stack, back-edge
+                            low_link[*u] = Some(
+                                low_link[*u]
+                                    .ok_or(GraphError::AlgorithmError("low_link for u not set"))?
+                                    .min(dfs_num[v].ok_or(GraphError::AlgorithmError(
+                                        "dfs_num for v not set",
+                                    ))?),
+                            );
+                        }
+                    } else {
+                        // All neighbors processed, "return" from u (post-order traversal)
+
+                        // If u is the root of an SCC
+                        if dfs_num[*u] == low_link[*u] {
+                            let mut current_scc = Vec::new();
+                            loop {
+                                let node = tarjan_stack
+                                    .pop()
+                                    .ok_or(GraphError::AlgorithmError("tarjan_stack is empty"))?;
+                                on_stack[node] = false;
+                                current_scc.push(node);
+                                if node == *u {
+                                    break;
+                                }
+                            }
+                            current_scc.reverse(); // SCC nodes are popped in reverse order
+                            sccs.push(current_scc);
+                        }
+
+                        // Update parent's low_link if u is not the root of an SCC
+                        // This must happen AFTER processing the current node's SCC, but BEFORE popping u from dfs_stack
+                        let popped_u = dfs_stack
+                            .pop()
+                            .ok_or(GraphError::AlgorithmError("DFS stack was empty in a post-order step, which should be impossible"))?
+                            .0;
+
+                        if let Some((parent_node, _)) = dfs_stack.last() {
+                            low_link[*parent_node] = Some(
+                                low_link[*parent_node]
+                                    .ok_or(GraphError::AlgorithmError(
+                                        "low_link for parent_node not set",
+                                    ))?
+                                    .min(low_link[popped_u].ok_or(GraphError::AlgorithmError(
+                                        "low_link for popped_u not set",
+                                    ))?),
+                            );
+                        }
+                    }
+                }
+            }
+        }
+
+        Ok(sccs)
+    }
 }

ultragraph/src/types/ultra_graph/graph_algo.rs

@@ -139,4 +139,22 @@ where
             GraphState::Dynamic(_) => Err(GraphError::GraphNotFrozen),
         }
     }
+
+    /// Finds the strongly connected components (SCCs) of the graph.
+    ///
+    /// # Preconditions
+    /// This high-performance operation is only available when the graph is in a `Static` (frozen) state.
+    ///
+    /// # Returns
+    /// A `Result` containing a `Vec<Vec<usize>>`, where each inner `Vec<usize>` represents
+    /// a strongly connected component as a list of node indices.
+    ///
+    /// # Errors
+    /// Returns `GraphError::GraphNotFrozen` if the graph is in a `Dynamic` state.
+    fn strongly_connected_components(&self) -> Result<Vec<Vec<usize>>, GraphError> {
+        match &self.state {
+            GraphState::Static(g) => g.strongly_connected_components(),
+            GraphState::Dynamic(_) => Err(GraphError::GraphNotFrozen),
+        }
+    }
 }

ultragraph/tests/errors/error_tests.rs

@@ -92,3 +92,65 @@ fn test_error_traits() {
     let copied_error = error1;
     assert_eq!(error1, copied_error);
 }
+
+/// Tests the creation and content of the AlgorithmError variant.
+#[test]
+fn test_algorithm_error_creation() {
+    let err_msg = "Pathfinding failed: graph is disconnected";
+    let error = GraphError::AlgorithmError(err_msg);
+
+    // You can use a `match` or `if let` to inspect the enum variant and its data.
+    if let GraphError::AlgorithmError(msg) = error {
+        assert_eq!(
+            msg, err_msg,
+            "The error message should be stored correctly."
+        );
+    } else {
+        panic!("Expected GraphError::AlgorithmError, but got a different variant.");
+    }
+}
+
+/// Tests the `Display` trait implementation for user-friendly output.
+#[test]
+fn test_algorithm_error_display_formatting() {
+    let err_msg = "Dijkstra's algorithm requires non-negative weights";
+    let error = GraphError::AlgorithmError(err_msg);
+    let expected_display_msg = format!("AlgorithmError: {err_msg}");
+
+    assert_eq!(error.to_string(), expected_display_msg);
+}
+
+/// Tests the `Debug` trait implementation for developer-focused output.
+#[test]
+fn test_algorithm_error_debug_formatting() {
+    let err_msg = "A cycle was detected in a directed acyclic graph (DAG)";
+    let error = GraphError::AlgorithmError(err_msg);
+    // The `Debug` format is derived automatically and includes the variant name.
+    let expected_debug_msg = format!("AlgorithmError(\"{err_msg}\")");
+
+    assert_eq!(format!("{error:?}"), expected_debug_msg);
+}
+
+/// Demonstrates how to check for a specific error variant within a `Result`.
+#[test]
+fn test_algorithm_error_in_a_result() {
+    let err_msg = "Invalid start node for traversal";
+
+    // A sample function that returns our specific error.
+    fn find_path() -> Result<Vec<usize>, GraphError> {
+        Err(GraphError::AlgorithmError(
+            "Invalid start node for traversal",
+        ))
+    }
+
+    let result = find_path();
+    assert!(result.is_err());
+
+    // Match on the error to confirm its type and contents.
+    match result {
+        Err(GraphError::AlgorithmError(msg)) => {
+            assert_eq!(msg, err_msg);
+        }
+        _ => panic!("Expected an AlgorithmError variant."),
+    }
+}