Merge branch 'main' into release

Author: djfrancesco

.github/workflows/docs.yml

@@ -10,6 +10,9 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0  # Fetch all history for all tags and branches
+        ref: ${{ github.event.release.tag_name }}
 
     - name: Set up Python
       uses: actions/setup-python@v5
@@ -20,6 +23,7 @@ jobs:
       run: |
         python -m pip install --upgrade pip
         pip install -r docs/requirements.txt
+        pip install .
     
     - name: Build documentation
       run: |

README.md

@@ -13,7 +13,7 @@
 
 *Graph algorithms in Cython*
 
-Welcome to our Python library for graph algorithms. So far, the library only includes Dijkstra's algorithm but we should add a range of common path algorithms later. It is also open-source and easy to integrate with other Python libraries. To get started, simply install the library using pip, and import it into your Python project.
+Welcome to our Python library for graph algorithms. The library includes both Dijkstra's and Bellman-Ford's algorithms, with plans to add more common path algorithms later. It is also open-source and easy to integrate with other Python libraries. To get started, simply install the library using pip, and import it into your Python project.
 
 Documentation : [https://edsger.readthedocs.io/en/latest/](https://edsger.readthedocs.io/en/latest/)
 
@@ -57,6 +57,63 @@ print("Shortest paths:", shortest_paths)
 
 We get the shortest paths from the source node 0 to all other nodes in the graph. The output is an array with the shortest path length to each node. A path length is the sum of the weights of the edges in the path.
 
+## Bellman-Ford Algorithm: Handling Negative Weights
+
+The Bellman-Ford algorithm can handle graphs with negative edge weights and detect negative cycles, making it suitable for more complex scenarios than Dijkstra's algorithm.
+
+```python
+from edsger.path import BellmanFord
+
+# Create a graph with negative weights
+edges_negative = pd.DataFrame({
+    'tail': [0, 0, 1, 1, 2, 3],
+    'head': [1, 2, 2, 3, 3, 4],
+    'weight': [1, 4, -2, 5, 1, 3]  # Note the negative weight
+})
+edges_negative
+```
+
+|    |   tail |   head |   weight |
+|---:|-------:|-------:|---------:|
+|  0 |      0 |      1 |      1.0 |
+|  1 |      0 |      2 |      4.0 |
+|  2 |      1 |      2 |     -2.0 |
+|  3 |      1 |      3 |      5.0 |
+|  4 |      2 |      3 |      1.0 |
+|  5 |      3 |      4 |      3.0 |
+
+```python
+# Initialize and run Bellman-Ford
+bf = BellmanFord(edges_negative)
+shortest_paths = bf.run(vertex_idx=0)
+print("Shortest paths:", shortest_paths)
+```
+
+    Shortest paths: [ 0.  1. -1.  0.  3.]
+
+The Bellman-Ford algorithm finds the optimal path even with negative weights. In this example, the shortest path from node 0 to node 2 has length -1 (going 0→1→2 with weights 1 + (-2) = -1), which is shorter than the direct path 0→2 with weight 4.
+
+### Negative Cycle Detection
+
+Bellman-Ford can also detect negative cycles, which indicate that no shortest path exists:
+
+```python
+# Create a graph with a negative cycle
+edges_cycle = pd.DataFrame({
+    'tail': [0, 1, 2],
+    'head': [1, 2, 0],
+    'weight': [1, -2, -1]  # Cycle 0→1→2→0 has total weight -2
+})
+
+bf_cycle = BellmanFord(edges_cycle)
+try:
+    bf_cycle.run(vertex_idx=0)
+except ValueError as e:
+    print("Error:", e)
+```
+
+    Error: Negative cycle detected in the graph
+
 ## Installation
 
 ### Standard Installation

docs/source/api.md

@@ -114,3 +114,135 @@ paths = dijkstra.run(
     heap_length_ratio=0.5
 )
 ```
+
+### BellmanFord Class
+
+The class for performing Bellman-Ford shortest path algorithm, which handles graphs with negative edge weights and detects negative cycles.
+
+#### Constructor Parameters
+
+- `edges`: pandas.DataFrame containing the graph edges
+- `tail`: Column name for edge source nodes (default: 'tail')
+- `head`: Column name for edge destination nodes (default: 'head')
+- `weight`: Column name for edge weights (default: 'weight')
+- `orientation`: Either 'out' (single-source) or 'in' (single-target) (default: 'out')
+- `check_edges`: Whether to validate edge data (default: False)
+- `permute`: Whether to optimize node indexing (default: False)
+
+#### Methods
+
+##### run
+
+```python
+def run(self, vertex_idx, path_tracking=False, return_inf=True, 
+        return_series=False, detect_negative_cycles=True)
+```
+
+Runs the Bellman-Ford algorithm from/to the specified vertex.
+
+**Parameters:**
+- `vertex_idx`: Source/target vertex index
+- `path_tracking`: Whether to track paths for reconstruction (default: False)
+- `return_inf`: Return infinity for unreachable vertices (default: True)
+- `return_series`: Return results as pandas Series (default: False)
+- `detect_negative_cycles`: Whether to detect negative cycles (default: True)
+
+**Returns:**
+- Array or Series of shortest path lengths
+
+**Raises:**
+- `ValueError`: If a negative cycle is detected and `detect_negative_cycles=True`
+
+##### get_path
+
+```python
+def get_path(self, vertex_idx)
+```
+
+Reconstructs the shortest path to/from a vertex (requires `path_tracking=True`).
+
+**Parameters:**
+- `vertex_idx`: Destination/source vertex index
+
+**Returns:**
+- Array of vertex indices forming the path
+
+##### get_vertices
+
+```python
+def get_vertices(self)
+```
+
+Returns all vertices in the graph.
+
+**Returns:**
+- Array of vertex indices
+
+#### Examples
+
+##### Basic Usage with Negative Weights
+
+```python
+from edsger.path import BellmanFord
+import pandas as pd
+
+# Create a graph with negative weights
+edges = pd.DataFrame({
+    'tail': [0, 0, 1, 1, 2, 3],
+    'head': [1, 2, 2, 3, 3, 4],
+    'weight': [1, 4, -2, 5, 1, 3]  # Note the negative weight
+})
+
+# Initialize Bellman-Ford
+bf = BellmanFord(edges)
+
+# Find shortest paths from vertex 0
+paths = bf.run(vertex_idx=0)
+print(paths)  # [ 0.  1. -1.  0.  3.]
+```
+
+##### Negative Cycle Detection
+
+```python
+# Create a graph with a negative cycle
+edges_cycle = pd.DataFrame({
+    'tail': [0, 1, 2],
+    'head': [1, 2, 0],
+    'weight': [1, -2, -1]  # Cycle 0→1→2→0 has total weight -2
+})
+
+bf_cycle = BellmanFord(edges_cycle)
+try:
+    bf_cycle.run(vertex_idx=0)
+except ValueError as e:
+    print(f"Error: {e}")  # Error: Negative cycle detected in the graph
+```
+
+##### Path Tracking with Negative Weights
+
+```python
+# Enable path tracking
+paths = bf.run(vertex_idx=0, path_tracking=True)
+
+# Get the actual path to vertex 2 (using negative weight path)
+path = bf.get_path(vertex_idx=2)
+print(path)  # Path using the negative weight edge
+```
+
+##### Performance: Disabling Cycle Detection
+
+```python
+# For performance when you know there are no negative cycles
+paths = bf.run(vertex_idx=0, detect_negative_cycles=False)
+```
+
+## Algorithm Comparison
+
+| Feature | Dijkstra | BellmanFord |
+|---------|----------|-------------|
+| **Negative weights** | ❌ No | ✅ Yes |
+| **Negative cycle detection** | ❌ No | ✅ Yes |
+| **Time complexity** | O((V + E) log V) | O(VE) |
+| **Space complexity** | O(V) | O(V) |
+| **Use case** | Positive weights only | Any weights, cycle detection |
+| **Performance** | Faster | Slower but more versatile |

docs/source/index.md

@@ -6,7 +6,7 @@ github_url: https://github.com/aetperf/Edsger
 
 *Graph algorithms in Cython*
 
-Welcome to the Edsger documentation! Edsger is a Python library for efficient graph algorithms implemented in Cython. The library currently focuses on shortest path algorithms, with Dijkstra's algorithm fully implemented and additional algorithms planned for future releases.
+Welcome to the Edsger documentation! Edsger is a Python library for efficient graph algorithms implemented in Cython. The library focuses on shortest path algorithms, featuring so far both Dijkstra's algorithm for positive-weight graphs and Bellman-Ford algorithm for graphs with negative weights and cycle detection.
 
 ## Why Use Edsger?
 
@@ -18,7 +18,7 @@ Edsger is designed to be **dataframe-friendly**, providing seamless integration
 
 ```python
 import pandas as pd
-from edsger.path import Dijkstra
+from edsger.path import Dijkstra, BellmanFord
 
 # Your graph data is already in a DataFrame
 edges = pd.DataFrame({
@@ -27,19 +27,21 @@ edges = pd.DataFrame({
     'weight': [1.0, 2.0, 1.5, 1.0]
 })
 
-# No conversion needed - use directly!
-dijkstra = Dijkstra(edges, orientation="out")
+# Use Dijkstra for positive weights (faster)
+dijkstra = Dijkstra(edges)
 distances = dijkstra.run(vertex_idx=0)
-distances
+
+# Use Bellman-Ford for negative weights or cycle detection
+bf = BellmanFord(edges)
+distances = bf.run(vertex_idx=0)
 ```
-    array([0., 1., 2., 3.])
 
 ## Key Features
 
 - **Native pandas DataFrame support** - No graph object conversion required
-- **High performance** - Cython implementation with aggressive optimizations
-- **Memory efficient** - Optimized for large-scale real-world datasets
-- **Easy integration** with NumPy and pandas workflows
+- **High performance** - Cython implementation
+- **Memory efficient** - Optimized for real-world datasets
+- **Easy integration** with NumPy and Pandas workflows
 - **Production ready** - Comprehensive testing across Python 3.9-3.13
 
 ## Quick Links