edsger 0.1.2__tar.gz → 0.1.4__tar.gz

{edsger-0.1.2 → edsger-0.1.4}/.github/workflows/docs.yml

@@ -1,10 +1,8 @@
 name: Documentation
 
 on:
-  push:
-    branches: [ release ]
-  pull_request:
-    branches: [ release ]
+  release:
+    types: [created]
 
 jobs:
   build-docs:
@@ -34,8 +32,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.2 → edsger-0.1.4}/.github/workflows/publish.yml

@@ -1,9 +1,9 @@
-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]+'
+  release:
+    types: [created]
+
 jobs:
 
   test:
@@ -13,45 +13,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
@@ -62,27 +48,24 @@ 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
-
-      - 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 +73,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.4/.github/workflows/tests.yml

@@ -0,0 +1,52 @@
+name: Run tests and upload coverage
+
+on:
+  release:
+    types: [created]
+
+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:
+    - name: Checkout
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 2
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      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: 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 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.2 → edsger-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edsger
-Version: 0.1.2
+Version: 0.1.4
 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,8 @@ 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/)
+[![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/)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
@@ -75,14 +76,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
@@ -97,13 +98,19 @@ 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.
 
-## Why Use Edsger?
+## Installation
+
+### Standard Installation
 
-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:
+```bash
+pip install edsger
+```
+
+## Why Use Edsger?
 
-<img src="docs/source/assets/dijkstra_benchmark_comparison.png" alt="Dijkstra Performance Comparison" width="700">
+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:
 
-*Benchmark performed on Intel i9-12900H laptop.*
+<img src="https://raw.githubusercontent.com/aetperf/edsger/release/docs/source/assets/dijkstra_benchmark_comparison.png" alt="Dijkstra Performance Comparison" width="700">
 
 ## Contributing
 

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

@@ -1,7 +1,8 @@
 
 ![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/)
+[![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/)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
@@ -34,14 +35,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
@@ -56,13 +57,19 @@ 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.
 
-## Why Use Edsger?
+## Installation
+
+### Standard Installation
 
-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:
+```bash
+pip install edsger
+```
+
+## Why Use Edsger?
 
-<img src="docs/source/assets/dijkstra_benchmark_comparison.png" alt="Dijkstra Performance Comparison" width="700">
+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:
 
-*Benchmark performed on Intel i9-12900H laptop.*
+<img src="https://raw.githubusercontent.com/aetperf/edsger/release/docs/source/assets/dijkstra_benchmark_comparison.png" alt="Dijkstra Performance Comparison" width="700">
 
 ## Contributing
 

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

@@ -10,12 +10,10 @@ Welcome to the Edsger documentation! Edsger is a Python library for efficient gr
 
 ## 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 laptop.*
-
 ### Pandas Integration Made Simple
 
 ```python
@@ -32,7 +30,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.4}/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.4/scripts/README_benchmark_os.md

@@ -0,0 +1,72 @@
+# OS-Specific Benchmarking Scripts
+
+These scripts allow you to run benchmarks on different operating systems and combine the results into comparison plots.
+
+## Scripts
+
+1. **benchmark_comparison_os.py** - Runs benchmarks and creates OS-specific JSON files
+2. **plot_benchmark_comparison.py** - Creates comparison plots from the JSON files
+
+## Usage
+
+### Step 1: Run benchmarks on each OS
+
+On Linux:
+```bash
+cd scripts/
+python benchmark_comparison_os.py [-d DATA_DIR] [-n NETWORK] [-r REPEAT]
+```
+This creates: `benchmark_dimacs_USA_linux.json` (or with different network name)
+
+On Windows:
+```bash
+cd scripts/
+python benchmark_comparison_os.py [-d DATA_DIR] [-n NETWORK] [-r REPEAT]
+```
+This creates: `benchmark_dimacs_USA_windows.json` (or with different network name)
+
+On macOS:
+```bash
+cd scripts/
+python benchmark_comparison_os.py [-d DATA_DIR] [-n NETWORK] [-r REPEAT]
+```
+This creates: `benchmark_dimacs_USA_darwin.json` (or with different network name)
+
+#### Arguments:
+- `-d, --dir`: Data folder with network sub-folders (default: from DIMACS_DATA_DIR env var or `/home/francois/Data/DIMACS_road_networks/`)
+- `-n, --network`: Network name - 'NY', 'BAY', 'COL', 'FLA', 'NW', 'NE', 'CAL', 'LKS', 'E', 'W', 'CTR', 'USA' (default: USA)
+- `-r, --repeat`: Number of benchmark iterations per library (default: 5)
+
+### Step 2: Create comparison plots
+
+After collecting results from one or more operating systems:
+```bash
+python plot_benchmark_comparison.py
+```
+
+This will create:
+- Combined comparison plot: `dijkstra_benchmark_comparison.png`
+
+## Features
+
+- **Graceful handling of missing packages**: Graph-tool is automatically skipped on Windows
+- **OS detection**: Automatically names output files based on the operating system
+- **Multi-OS comparison**: Can compare results across Linux, Windows, and macOS
+- **Version tracking**: Records package versions for each benchmark run
+
+## Output Files
+
+### JSON files
+- `benchmark_dimacs_{NETWORK}_{OS}.json` - Benchmark results for specific network and OS
+  - Examples: `benchmark_dimacs_USA_linux.json`, `benchmark_dimacs_COL_windows.json`
+
+### Plot files
+- `dijkstra_benchmark_comparison.png` - Comparison plot (shows all available OS results)
+
+## Notes
+
+- **Graph-tool**: Not available on Windows and will be automatically skipped
+- **SciPy benchmarking**: Runs `dijkstra_dimacs.py` with Edsger + comparison (`-c` flag) multiple times to collect SciPy timing statistics, since SciPy only runs once per call in comparison mode
+- **Package detection**: Scripts detect available packages before running benchmarks
+- **Metadata**: Results include system information, Python version, and package versions
+- **Statistical reliability**: Benchmarks run 5 iterations by default for each library