edsger 0.1.2__tar.gz → 0.1.3__tar.gz

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

@@ -1,9 +1,10 @@
-name: ci-publish  #  Publish Python distribution to PyPI
+name: ci-publish  # Publish Python distribution to PyPI
 
 on:
   push:
     tags:
       - 'v[0-9]+.[0-9]+.[0-9]+'
+
 jobs:
 
   test:
@@ -13,45 +14,31 @@ jobs:
         python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
     runs-on: ${{ matrix.os }}
     steps:
-    - uses: actions/checkout@v4
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v4
-      with:
-        python-version: ${{ matrix.python-version }}
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install -r requirements-dev.txt
-        pip install .
-    - name: Testing
-      run: |
-        python -m pytest tests
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements-dev.txt
+          pip install .
+      - name: Testing
+        run: python -m pytest tests
 
   build_source_dist:
     name: Build source distribution
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      # - if: github.event.ref_type != 'tag'
-      #   run: |
-      #     git fetch --prune --unshallow
-      #     git tag -d $(git tag --points-at HEAD)
-      - if: github.event.ref_type == 'tag'
-        uses: actions/checkout@v3
-      - if: github.event_name == 'workflow_dispatch'
-        uses: actions/checkout@v3
-        with:
-          fetch-depth: 0
       - uses: actions/setup-python@v4
         with:
           python-version: "3.11"
-
       - name: Install build
         run: python -m pip install build
-
       - name: Run build
         run: python -m build --sdist
-
       - uses: actions/upload-artifact@v4
         with:
           name: cibw-sdist
@@ -66,23 +53,20 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
-
-      - uses: actions/setup-python@v3
-
+      - uses: actions/setup-python@v4
       - name: Install cibuildwheel
         run: python -m pip install cibuildwheel==2.16.5
-
       - name: Build wheels
+        env:
+          CIBW_BUILD: "cp39-* cp310-* cp311-* cp312-* cp313-*"
         run: python -m cibuildwheel --output-dir wheelhouse
-
       - uses: actions/upload-artifact@v4
         with:
           name: cibw-wheels-${{ matrix.os }}-${{ strategy.job-index }}
           path: ./wheelhouse/*.whl
 
   publish-to-pypi:
-    name: >-
-      Publish Python distribution to PyPI
+    name: Publish Python distribution to PyPI
     needs:
       - test
       - build_source_dist
@@ -90,14 +74,13 @@ jobs:
     runs-on: ubuntu-latest
     environment: release
     permissions:
-      id-token: write  # IMPORTANT: mandatory for trusted publishing
-
+      id-token: write  # mandatory for trusted publishing
     steps:
-    - name: Download all the dists
-      uses: actions/download-artifact@v4
-      with:
-        pattern: cibw-*
-        path: ./dist/
-        merge-multiple: true
-    - name: Publish distribution to PyPI
-      uses: pypa/gh-action-pypi-publish@release/v1
+      - name: Download all the dists
+        uses: actions/download-artifact@v4
+        with:
+          pattern: cibw-*
+          path: ./dist/
+          merge-multiple: true
+      - name: Publish distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

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

@@ -1,4 +1,4 @@
-name: ci-test
+name: Run tests and upload coverage
 
 on:
   push:
@@ -7,13 +7,17 @@ on:
 
 jobs:
   test:
+    name: Run tests and collect coverage
     strategy:
       matrix:
         os: [ubuntu-22.04, windows-2022, macos-14]
         python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
     runs-on: ${{ matrix.os }}
     steps:
-    - uses: actions/checkout@v4
+    - name: Checkout
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 2
     - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v5
       with:
@@ -29,13 +33,10 @@ jobs:
     - 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: Testing
+    - name: Run tests
       run: |
-        python -m pytest --cov=src/edsger --cov-report=xml tests/
-    - name: Upload coverage to Codecov
-      uses: codecov/codecov-action@v4
+        pytest --cov=src/edsger --cov-branch --cov-report=xml tests/
+    - name: Upload results to Codecov
+      uses: codecov/codecov-action@v5
       with:
-        file: ./coverage.xml
-        flags: unittests
-        name: codecov-umbrella
-        fail_ci_if_error: false
+        token: ${{ secrets.CODECOV_TOKEN }}

{edsger-0.1.2 → edsger-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edsger
-Version: 0.1.2
+Version: 0.1.3
 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,7 +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)
-[![PyPI version](https://img.shields.io/pypi/v/edsger.svg)](https://pypi.org/project/edsger/)
+[![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/)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
@@ -75,14 +75,14 @@ edges = pd.DataFrame({
 edges
 ```
 
-    |    |   tail |   head |   weight |
-    |---:|-------:|-------:|---------:|
-    |  0 |      0 |      1 |      1.0 |
-    |  1 |      0 |      2 |      4.0 |
-    |  2 |      1 |      2 |      2.0 |
-    |  3 |      2 |      3 |      1.5 |
-    |  4 |      2 |      4 |      3.0 |
-    |  5 |      3 |      4 |      1.0 |
+|    |   tail |   head |   weight |
+|---:|-------:|-------:|---------:|
+|  0 |      0 |      1 |      1.0 |
+|  1 |      0 |      2 |      4.0 |
+|  2 |      1 |      2 |      2.0 |
+|  3 |      2 |      3 |      1.5 |
+|  4 |      2 |      4 |      3.0 |
+|  5 |      3 |      4 |      1.0 |
 
 ```python
 # Initialize the Dijkstra object
@@ -101,9 +101,9 @@ We get the shortest paths from the source node 0 to all other nodes in the graph
 
 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:
 
-<img src="docs/source/assets/dijkstra_benchmark_comparison.png" alt="Dijkstra Performance Comparison" width="700">
+<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 laptop.*
+*Benchmark performed on Intel i9-12900H Linux laptop.*
 
 ## Contributing
 

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

@@ -1,7 +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)
-[![PyPI version](https://img.shields.io/pypi/v/edsger.svg)](https://pypi.org/project/edsger/)
+[![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/)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
@@ -34,14 +34,14 @@ edges = pd.DataFrame({
 edges
 ```
 
-    |    |   tail |   head |   weight |
-    |---:|-------:|-------:|---------:|
-    |  0 |      0 |      1 |      1.0 |
-    |  1 |      0 |      2 |      4.0 |
-    |  2 |      1 |      2 |      2.0 |
-    |  3 |      2 |      3 |      1.5 |
-    |  4 |      2 |      4 |      3.0 |
-    |  5 |      3 |      4 |      1.0 |
+|    |   tail |   head |   weight |
+|---:|-------:|-------:|---------:|
+|  0 |      0 |      1 |      1.0 |
+|  1 |      0 |      2 |      4.0 |
+|  2 |      1 |      2 |      2.0 |
+|  3 |      2 |      3 |      1.5 |
+|  4 |      2 |      4 |      3.0 |
+|  5 |      3 |      4 |      1.0 |
 
 ```python
 # Initialize the Dijkstra object
@@ -60,9 +60,9 @@ We get the shortest paths from the source node 0 to all other nodes in the graph
 
 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:
 
-<img src="docs/source/assets/dijkstra_benchmark_comparison.png" alt="Dijkstra Performance Comparison" width="700">
+<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 laptop.*
+*Benchmark performed on Intel i9-12900H Linux laptop.*
 
 ## Contributing
 

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

@@ -14,7 +14,7 @@ Edsger is designed to be **dataframe-friendly**, providing seamless integration
 
 <img src="assets/dijkstra_benchmark_comparison.png" alt="Dijkstra Performance Comparison" width="700">
 
-*Benchmark performed on Intel i9-12900H laptop.*
+*Benchmark performed on Intel i9-12900H Linux laptop.*
 
 ### Pandas Integration Made Simple
 
@@ -32,7 +32,9 @@ edges = pd.DataFrame({
 # No conversion needed - use directly!
 dijkstra = Dijkstra(edges, orientation="out")
 distances = dijkstra.run(vertex_idx=0)
+distances
 ```
+    array([0., 1., 2., 3.])
 
 ## Key Features
 

{edsger-0.1.2 → edsger-0.1.3}/docs/source/quickstart.md

@@ -22,7 +22,7 @@ edges = pd.DataFrame({
     'head': [1, 2, 2, 3],
     'weight': [1.0, 4.0, 2.0, 1.0]
 })
-edsges
+edges
 ```
 
 |    |   tail |   head |   weight |
@@ -33,6 +33,8 @@ edsges
 |  3 |      2 |      3 |        1 |
 
 
+Note that it is also possible to use a graph with different column names for the tail, head and weight values, but we need then to specify the name mapping, as described in the following.
+
 ## Dijkstra's Algorithm
 
 To use Dijkstra's algorithm, you can import the `Dijkstra` class from the `path` module. The function takes a graph and a source node as input, and returns the shortest path from the source node to all other nodes in the graph.
@@ -49,14 +51,14 @@ edges = pd.DataFrame({
 edges
 ```
 
-    |    |   tail |   head |   weight |
-    |---:|-------:|-------:|---------:|
-    |  0 |      0 |      1 |      1.0 |
-    |  1 |      0 |      2 |      4.0 |
-    |  2 |      1 |      2 |      2.0 |
-    |  3 |      2 |      3 |      1.5 |
-    |  4 |      2 |      4 |      3.0 |
-    |  5 |      3 |      4 |      1.0 |
+|    |   tail |   head |   weight |
+|---:|-------:|-------:|---------:|
+|  0 |      0 |      1 |      1.0 |
+|  1 |      0 |      2 |      4.0 |
+|  2 |      1 |      2 |      2.0 |
+|  3 |      2 |      3 |      1.5 |
+|  4 |      2 |      4 |      3.0 |
+|  5 |      3 |      4 |      1.0 |
 
 
 ```python
@@ -72,7 +74,7 @@ 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.
 
-It is also possible to use a graph with different column names for the tail, head and weight values. The column names can be specified using the `tail`, `head` and `weight` arguments:
+The column names can be specified using the `tail`, `head` and `weight` arguments:
 
 ```python
 other_edges = pd.DataFrame({
@@ -169,11 +171,116 @@ shortest_paths[-5:]
 
     array([0. , 1. , 3. , 4.5, 5.5])
 
+### Early Termination
+
+Early termination is a performance optimization feature that allows Dijkstra's algorithm to stop computing once specific target nodes (termination nodes) have been reached. This can significantly reduce computation time when you only need shortest paths to a subset of vertices in the graph.
+
+When using early termination, the algorithm will:
+1. Stop as soon as all specified termination nodes have been visited
+2. Return **only** the path lengths to the termination nodes (not all vertices)
+3. Return results in the same order as the termination nodes were specified
+
+#### Basic Early Termination Example
+
+```python
+import pandas as pd
+from edsger.path import Dijkstra
+
+# Create a sample graph
+edges = pd.DataFrame({
+    "tail": [0, 0, 0, 1, 1, 2, 2, 3, 3, 4],
+    "head": [1, 2, 3, 2, 4, 3, 5, 4, 5, 5],
+    "weight": [1.0, 4.0, 2.0, 1.0, 3.0, 1.0, 2.0, 1.0, 1.0, 1.0],
+})
+```
+
+**Without early termination** (computes paths to all vertices):
+```python
+dijkstra = Dijkstra(edges, orientation="out")
+distances = dijkstra.run(vertex_idx=0)
+print("All distances:", distances)
+```
+    All distances: [0. 1. 2. 2. 3. 3.]
+
+**With early termination** (computes paths only to specified nodes):
+```python
+# Only compute paths to nodes 3 and 5
+termination_nodes = [3, 5]
+distances = dijkstra.run(vertex_idx=0, termination_nodes=termination_nodes)
+print("Distances to termination nodes:", distances)
+print("Shape of result:", distances.shape)
+```
+    Distances to termination nodes: [2. 3.]
+    Shape of result: (2,)
+
+Notice that:
+- The result array has length 2 (same as number of termination nodes)
+- `distances[0] = 2.0` is the shortest path length from vertex 0 to vertex 3
+- `distances[1] = 3.0` is the shortest path length from vertex 0 to vertex 5
+
+#### Early Termination with Path Tracking
+
+Early termination also works with path tracking enabled:
+
+```python
+dijkstra = Dijkstra(edges, orientation="out")
+distances = dijkstra.run(vertex_idx=0, termination_nodes=[3, 5], path_tracking=True)
+print("Distances:", distances)
+
+# Get paths to termination nodes
+path_to_3 = dijkstra.get_path(vertex_idx=3)
+path_to_5 = dijkstra.get_path(vertex_idx=5)
+print("Path to vertex 3:", path_to_3)
+print("Path to vertex 5:", path_to_5)
+```
+    Distances: [2. 3.]
+    Path to vertex 3: [3 2 1 0]
+    Path to vertex 5: [5 3 2 1 0]
+
+#### Important Notes
+
+1. **Return Array Size**: With early termination, the returned array size equals the number of termination nodes, not the total number of vertices in the graph.
+
+2. **Order Preservation**: Results are returned in the same order as the termination nodes are specified:
+   ```python
+   # Termination nodes [3, 5] → results [distance_to_3, distance_to_5]
+   # Termination nodes [5, 3] → results [distance_to_5, distance_to_3]
+   ```
+
+3. **Orientation Support**: Early termination works with both orientations:
+   ```python
+   # Single-source shortest paths (from source to termination nodes)
+   dijkstra = Dijkstra(edges, orientation="out")
+   distances = dijkstra.run(vertex_idx=0, termination_nodes=[3, 5])
+   
+   # Single-target shortest paths (from termination nodes to target)
+   dijkstra = Dijkstra(edges, orientation="in") 
+   distances = dijkstra.run(vertex_idx=5, termination_nodes=[0, 2])
+   ```
+
+4. **Unreachable Nodes**: If a termination node is unreachable, its distance will be infinity:
+   ```python
+   # If node 10 is unreachable from node 0
+   distances = dijkstra.run(vertex_idx=0, termination_nodes=[3, 10])
+   # Result: [2.0, inf]
+   ```
 
 ### Run Method Options
 
 The `run` method can take the following arguments besides the source/target vertex index:
 
+- `termination_nodes` : list or array-like, optional (default=None)
+
+A list or array of vertex indices where the algorithm should stop early. When specified, the algorithm will terminate as soon as all termination nodes have been reached, and will return only the path lengths to these nodes in the same order they were specified. This can provide significant performance improvements when you only need paths to a subset of vertices.
+
+```python
+dijkstra = Dijkstra(edges)
+# Get distances only to nodes 2 and 4
+distances = dijkstra.run(vertex_idx=0, termination_nodes=[2, 4])
+print("Distances to nodes 2 and 4:", distances)
+```
+    Distances to nodes 2 and 4: [1.5 3.5]
+
 - `path_tracking` : bool, optional (default=False)
 
 Whether to track the shortest path(s) from/to the source/target vertex to all other vertices in the graph.
@@ -194,6 +301,8 @@ dijkstra.get_path(vertex_idx=0)
 
 The path is returned as an array of vertex indices. This is an ordered list of vertices from the source to the target vertex if `orientation` is `'in'`, and from the target to the source vertex if `orientation` is `'out'`. Both the source and target vertices are included in the path.
 
+**Note**: When using `termination_nodes` with `path_tracking=True`, you can still retrieve paths to any vertex that was reached during the computation using `get_path()`, even if it wasn't in the termination nodes list.
+
 - `return_inf` : bool, optional (default=True)
     
 Whether to return path lengths as infinity (np.inf) when no path exists.

edsger-0.1.3/src/edsger/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.3"