Added Dijkstra's algorithm to UltraGraph (#263)

* Updated docstring

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

* Fixed a memory leak in the ultragraph benchmark.

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

* Fixed typo in Rustdoc.

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

* Added Dijkstra's algorithm to UltraGraph.

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

* Removed problematic check in Dijkstra's algorithm

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

* Improved test coverage for Dijkstra's algorithm. Improved docstring.

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

---------

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

Author: marvin-hansen

ultragraph/src/traits/graph_algo.rs

@@ -50,4 +50,27 @@ pub trait GraphAlgorithms<N, W>: GraphView<N, W> {
         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>;
+
+    // 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>;
 }

ultragraph/src/types/storage/graph_csm/graph_csm_algo.rs

@@ -270,4 +270,73 @@ where
         path.reverse();
         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,
+        stop_index: usize,
+    ) -> Result<Option<(Vec<usize>, W)>, GraphError>
+    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);
+        }
+
+        if start_index == stop_index {
+            return Ok(Some((vec![start_index], W::default())));
+        }
+
+        let num_nodes = self.number_nodes();
+        let mut distances: Vec<Option<W>> = vec![None; num_nodes];
+        let mut predecessors: Vec<Option<usize>> = vec![None; num_nodes];
+        let mut pq: BinaryHeap<(Reverse<W>, usize)> = BinaryHeap::new();
+
+        distances[start_index] = Some(W::default());
+        pq.push((Reverse(W::default()), start_index));
+
+        while let Some((Reverse(dist), u)) = pq.pop() {
+            if u == stop_index {
+                let mut path = Vec::new();
+                let mut current = Some(stop_index);
+                while let Some(node) = current {
+                    path.push(node);
+                    if node == start_index {
+                        break;
+                    }
+                    current = predecessors[node];
+                }
+                path.reverse();
+
+                return Ok(Some((path, dist)));
+            }
+
+            if let Some(known_dist) = distances[u] {
+                if dist > known_dist {
+                    continue;
+                }
+            }
+
+            let start_offset = self.forward_edges.offsets[u];
+            let end_offset = self.forward_edges.offsets[u + 1];
+
+            for i in start_offset..end_offset {
+                let v = self.forward_edges.targets[i];
+                let weight = self.forward_edges.weights[i];
+                let new_dist = dist + weight;
+
+                if distances[v].map_or(true, |d| new_dist < d) {
+                    distances[v] = Some(new_dist);
+                    predecessors[v] = Some(u);
+                    pq.push((Reverse(new_dist), v));
+                }
+            }
+        }
+
+        Ok(None)
+    }
 }

ultragraph/src/types/ultra_graph/graph_algo.rs

@@ -111,4 +111,32 @@ where
             GraphState::Dynamic(_) => Err(GraphError::GraphNotFrozen),
         }
     }
+
+    /// Finds the shortest path (as a sequence of node indices) between two nodes, considering edge weights.
+    ///
+    /// # Preconditions
+    /// This high-performance operation is only available when the graph is in a `Static` (frozen) state.
+    ///
+    /// # Type Parameters
+    /// - `W`: The weight type, which must implement `Copy`, `Ord`, `Default`, and `std::ops::Add`.
+    ///
+    /// # Errors
+    ///
+    /// - Returns `GraphError::GraphNotFrozen` if the graph is in a `Dynamic` state.
+    /// - Returns an error if either node index is invalid.
+    /// - Returns an error if the graph contains negative cycles (for algorithms like Dijkstra's).
+    ///
+    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>,
+    {
+        match &self.state {
+            GraphState::Static(g) => g.shortest_weighted_path(start_index, stop_index),
+            GraphState::Dynamic(_) => Err(GraphError::GraphNotFrozen),
+        }
+    }
 }

ultragraph/tests/types/ultra_graph/graph_algo_tests.rs

@@ -162,3 +162,53 @@ fn test_shortest_path_on_static_graph() {
     assert_eq!(g.shortest_path(0, 3).unwrap(), Some(vec![0, 1, 2, 3]));
     assert_eq!(g.shortest_path(3, 0).unwrap(), None);
 }
+
+#[test]
+fn test_shortest_weighted_path_on_static_graph() {
+    let mut g = UltraGraphWeighted::new();
+    g.add_node(0).unwrap();
+    g.add_node(1).unwrap();
+    g.add_node(2).unwrap();
+    g.add_node(3).unwrap();
+    g.add_node(4).unwrap();
+    g.add_edge(0, 1, 1).unwrap();
+    g.add_edge(0, 2, 4).unwrap();
+    g.add_edge(1, 2, 2).unwrap();
+    g.add_edge(1, 3, 5).unwrap();
+    g.add_edge(2, 3, 1).unwrap();
+    g.add_edge(3, 4, 1).unwrap();
+
+    let result = g.shortest_weighted_path(0, 4);
+    // triggers GraphNotFrozen error.
+    assert!(result.is_err());
+
+    // Freeze the graph to enable all algos.
+    g.freeze();
+
+    // Path 0 -> 1 -> 2 -> 3 -> 4, weight 1 + 2 + 1 + 1 = 5
+    let result = g.shortest_weighted_path(0, 4).unwrap().unwrap();
+    assert_eq!(result.0, vec![0, 1, 2, 3, 4]);
+    assert_eq!(result.1, 5);
+
+    // Path 0 -> 1 -> 2 -> 3, weight 1 + 2 + 1 = 4
+    let result = g.shortest_weighted_path(0, 3).unwrap().unwrap();
+    assert_eq!(result.0, vec![0, 1, 2, 3]);
+    assert_eq!(result.1, 4);
+
+    // Path 1 -> 2 -> 3, weight 2 + 1 = 3
+    let result = g.shortest_weighted_path(1, 3).unwrap().unwrap();
+    assert_eq!(result.0, vec![1, 2, 3]);
+    assert_eq!(result.1, 3);
+
+    // No path from 4 to 0
+    assert!(g.shortest_weighted_path(4, 0).unwrap().is_none());
+
+    // Invalid nodes
+    assert!(g.shortest_weighted_path(0, 99).unwrap().is_none());
+    assert!(g.shortest_weighted_path(99, 0).unwrap().is_none());
+
+    // Start and stop are the same
+    let result = g.shortest_weighted_path(0, 0).unwrap().unwrap();
+    assert_eq!(result.0, vec![0]);
+    assert_eq!(result.1, 0);
+}