edsger 0.1.3__tar.gz → 0.1.5__tar.gz

{edsger-0.1.3 → edsger-0.1.5}/.github/workflows/docs.yml

@@ -1,10 +1,8 @@
 name: Documentation
 
 on:
-  push:
-    branches: [ release ]
-  pull_request:
-    branches: [ release ]
+  release:
+    types: [created]
 
 jobs:
   build-docs:
@@ -12,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
@@ -22,6 +23,7 @@ jobs:
       run: |
         python -m pip install --upgrade pip
         pip install -r docs/requirements.txt
+        pip install .
     
     - name: Build documentation
       run: |
@@ -34,8 +36,8 @@ jobs:
         name: documentation-html
         path: docs/build/html/
     
-    - name: Deploy to GitHub Pages (on release branch)
-      if: github.ref == 'refs/heads/release' && github.event_name == 'push'
+    - name: Deploy to GitHub Pages
+      if: github.event_name == 'release'
       uses: peaceiris/actions-gh-pages@v4
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}

{edsger-0.1.3 → edsger-0.1.5}/.github/workflows/publish.yml

@@ -1,9 +1,8 @@
 name: ci-publish  # Publish Python distribution to PyPI
 
 on:
-  push:
-    tags:
-      - 'v[0-9]+.[0-9]+.[0-9]+'
+  release:
+    types: [created]
 
 jobs:
 
@@ -49,7 +48,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [ubuntu-latest, windows-2019, macos-13, macos-14]
+        os: [ubuntu-latest, windows-2022, macos-13, macos-14]
 
     steps:
       - uses: actions/checkout@v4

{edsger-0.1.3 → edsger-0.1.5}/.github/workflows/tests.yml

@@ -4,6 +4,8 @@ on:
   push:
     branches: 
       - release
+  release:
+    types: [created]
 
 jobs:
   test:
@@ -27,16 +29,27 @@ jobs:
         python -m pip install --upgrade pip
         pip install -r requirements-dev.txt
         pip install .
+    - name: Reinstall package with coverage support
+      if: matrix.os == 'ubuntu-22.04' && matrix.python-version == '3.11'
+      run: |
+        pip uninstall -y edsger
+        CYTHON_TRACE=1 pip install -e .
     - name: Format Python code with black
       run: |
         black --check --diff .
     - name: Lint Cython code
       run: |
         cython-lint src/edsger/commons.pyx src/edsger/dijkstra.pyx src/edsger/path_tracking.pyx src/edsger/pq_4ary_dec_0b.pyx src/edsger/spiess_florian.pyx src/edsger/star.pyx src/edsger/commons.pxd src/edsger/pq_4ary_dec_0b.pxd
-    - name: Run tests
+    - name: Run tests with coverage
+      if: matrix.os == 'ubuntu-22.04' && matrix.python-version == '3.11'
       run: |
         pytest --cov=src/edsger --cov-branch --cov-report=xml tests/
+    - name: Run tests without coverage
+      if: matrix.os != 'ubuntu-22.04' || matrix.python-version != '3.11'
+      run: |
+        pytest tests/
     - name: Upload results to Codecov
+      if: matrix.os == 'ubuntu-22.04' && matrix.python-version == '3.11'
       uses: codecov/codecov-action@v5
       with:
         token: ${{ secrets.CODECOV_TOKEN }}

{edsger-0.1.3/src/edsger.egg-info → edsger-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edsger
-Version: 0.1.3
+Version: 0.1.5
 Summary: Graph algorithms in Cython.
 Author-email: François Pacull <francois.pacull@architecture-performance.fr>
 Maintainer-email: François Pacull <francois.pacull@architecture-performance.fr>
@@ -42,6 +42,7 @@ Dynamic: license-file
 
 ![Tests Status](https://github.com/aetperf/edsger/actions/workflows/tests.yml/badge.svg?branch=release)
 [![codecov](https://codecov.io/gh/aetperf/edsger/branch/release/graph/badge.svg)](https://codecov.io/gh/aetperf/edsger)
+[![Documentation Status](https://readthedocs.org/projects/edsger/badge/?version=latest)](https://edsger.readthedocs.io/en/latest/?badge=latest)
 [![PyPI version](https://img.shields.io/pypi/v/edsger.svg?refresh=1)](https://pypi.org/project/edsger/)
 [![Downloads](https://static.pepy.tech/badge/edsger)](https://pepy.tech/project/edsger)
 [![Python 3.9 | 3.10 | 3.11 | 3.12 | 3.13](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://pypi.org/project/edsger/)
@@ -53,7 +54,7 @@ Dynamic: license-file
 
 *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/)
 
@@ -97,14 +98,77 @@ 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
+
+```bash
+pip install edsger
+```
+
 ## Why Use Edsger?
 
-Edsger is designed to be **dataframe-friendly**, providing seamless integration with pandas workflows for graph algorithms. Also it is rather efficient. Our benchmarks on the USA road network (23.9M vertices, 57.7M edges) demonstrate nice performance:
+Edsger is designed to be **dataframe-friendly**, providing seamless integration with pandas workflows for graph algorithms. Also it is rather efficient on Linux. Our benchmarks on the USA road network (23.9M vertices, 57.7M edges) demonstrate nice performance:
 
 <img src="https://raw.githubusercontent.com/aetperf/edsger/release/docs/source/assets/dijkstra_benchmark_comparison.png" alt="Dijkstra Performance Comparison" width="700">
 
-*Benchmark performed on Intel i9-12900H Linux laptop.*
-
 ## Contributing
 
 We welcome contributions to the Edsger library. If you have any suggestions, bug reports, or feature requests, please open an issue on our [GitHub repository](https://github.com/aetperf/Edsger).

{edsger-0.1.3 → edsger-0.1.5}/README.md

@@ -1,6 +1,7 @@
 
 ![Tests Status](https://github.com/aetperf/edsger/actions/workflows/tests.yml/badge.svg?branch=release)
 [![codecov](https://codecov.io/gh/aetperf/edsger/branch/release/graph/badge.svg)](https://codecov.io/gh/aetperf/edsger)
+[![Documentation Status](https://readthedocs.org/projects/edsger/badge/?version=latest)](https://edsger.readthedocs.io/en/latest/?badge=latest)
 [![PyPI version](https://img.shields.io/pypi/v/edsger.svg?refresh=1)](https://pypi.org/project/edsger/)
 [![Downloads](https://static.pepy.tech/badge/edsger)](https://pepy.tech/project/edsger)
 [![Python 3.9 | 3.10 | 3.11 | 3.12 | 3.13](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://pypi.org/project/edsger/)
@@ -12,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/)
 
@@ -56,14 +57,77 @@ 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
+
+```bash
+pip install edsger
+```
+
 ## Why Use Edsger?
 
-Edsger is designed to be **dataframe-friendly**, providing seamless integration with pandas workflows for graph algorithms. Also it is rather efficient. Our benchmarks on the USA road network (23.9M vertices, 57.7M edges) demonstrate nice performance:
+Edsger is designed to be **dataframe-friendly**, providing seamless integration with pandas workflows for graph algorithms. Also it is rather efficient on Linux. Our benchmarks on the USA road network (23.9M vertices, 57.7M edges) demonstrate nice performance:
 
 <img src="https://raw.githubusercontent.com/aetperf/edsger/release/docs/source/assets/dijkstra_benchmark_comparison.png" alt="Dijkstra Performance Comparison" width="700">
 
-*Benchmark performed on Intel i9-12900H Linux laptop.*
-
 ## Contributing
 
 We welcome contributions to the Edsger library. If you have any suggestions, bug reports, or feature requests, please open an issue on our [GitHub repository](https://github.com/aetperf/Edsger).

edsger-0.1.5/docs/source/api.md

@@ -0,0 +1,248 @@
+# API Reference
+
+This section provides detailed documentation for all public classes and functions in Edsger.
+
+## edsger.path Module
+
+### Dijkstra Class
+
+The main class for performing Dijkstra's shortest path algorithm.
+
+#### 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, heap_length_ratio=1.0)
+```
+
+Runs the shortest path 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)
+- `heap_length_ratio`: Heap size as fraction of vertices (default: 1.0)
+
+**Returns:**
+- Array or Series of shortest path lengths
+
+##### 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
+
+```python
+from edsger.path import Dijkstra
+import pandas as pd
+
+# Create a graph
+edges = pd.DataFrame({
+    'tail': [0, 0, 1],
+    'head': [1, 2, 2],
+    'weight': [1, 4, 2]
+})
+
+# Initialize Dijkstra
+dijkstra = Dijkstra(edges)
+
+# Find shortest paths from vertex 0
+paths = dijkstra.run(vertex_idx=0)
+```
+
+#### With Path Tracking
+
+```python
+# Enable path tracking
+paths = dijkstra.run(vertex_idx=0, path_tracking=True)
+
+# Get the actual path to vertex 2
+path = dijkstra.get_path(vertex_idx=2)
+```
+
+#### Custom Parameters
+
+```python
+# Create with custom settings
+dijkstra = Dijkstra(
+    edges,
+    orientation='in',
+    check_edges=True,
+    permute=True
+)
+
+# Run with custom parameters
+paths = dijkstra.run(
+    vertex_idx=2,
+    return_series=True,
+    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 |

{edsger-0.1.3 → edsger-0.1.5}/docs/source/index.md

@@ -6,21 +6,19 @@ 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?
 
-Edsger is designed to be **dataframe-friendly**, providing seamless integration with pandas workflows for graph algorithms. Also it is rather efficient. Our benchmarks on the USA road network (23.9M vertices, 57.7M edges) demonstrate nice performance:
+Edsger is designed to be **dataframe-friendly**, providing seamless integration with pandas workflows for graph algorithms. Also it is rather efficient on Linux. Our benchmarks on the USA road network (23.9M vertices, 57.7M edges) demonstrate nice performance:
 
 <img src="assets/dijkstra_benchmark_comparison.png" alt="Dijkstra Performance Comparison" width="700">
 
-*Benchmark performed on Intel i9-12900H Linux laptop.*
-
 ### Pandas Integration Made Simple
 
 ```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({
@@ -29,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