leopath 0.1.3

A user-friendly, extensible Python-based simulator for analyzing routing algorithms in LEO satellite constellations.

LEOPath

Research-grade LEO satellite routing simulator with dynamic topology, routing-state evaluation, and CesiumJS constellation visualization.

LEOPath helps researchers and network engineers study how routing algorithms behave when the network itself is moving. It generates synthetic LEO constellations, builds time-varying inter-satellite and ground-to-satellite links, computes forwarding state, and exports metrics for scalability studies.

The short version: use LEOPath when you want to compare routing strategies under realistic orbital dynamics without building a full packet-level simulator first.

Highlights

• Dynamic LEO topology generation from configurable constellation parameters and SGP4/TLE data.
• Inter-satellite links (ISLs), ground-to-satellite links (GSLs), and nearest-satellite attachment models.
• Pluggable routing algorithms for link-state, topological, predictive, and explicit-path approaches.
• Evaluation harness for stretch, churn, forwarding-state size, and compute-time metrics.
• Browser-based CesiumJS visualization for inspecting constellations, ISLs, GSLs, and orbital motion.
• Docker-first workflow for reproducible runs, plus editable local Python installs for development.

Visualization

One of LEOPath's best features is the interactive constellation viewer:

Open the live Cesium demo: https://fundacio-i2cat.github.io/LEOPath/cesium/

The viewer runs in the browser and lets you inspect satellite motion, ring vs +grid ISL topologies, ground stations, nearest-visible GSL attachments, and dense constellation samples.

Quickstart

Run with Docker

git clone https://github.com/Fundacio-i2CAT/LEOPath.git
cd LEOPath
./run-simulations.sh run -c leopath/config/ether_simple.yaml

Generate a local visualization

./run-simulations.sh visualise -c leopath/config/ether_simple.yaml

Open http://localhost:8080.

Run from source

python -m venv .venv
source .venv/bin/activate
pip install -e .
leopath --config leopath/config/ether_simple.yaml

What You Can Study

Question	LEOPath output
How much stretch does a routing strategy introduce?	Hop and distance stretch vs shortest-path baseline
How often does forwarding state change?	Per-step churn metrics
How much state does each satellite need?	Forwarding-state size metrics
How expensive is route recomputation?	Per-step compute-time metrics
How does topology shape behavior?	Ring and +grid ISL scenarios

Routing Algorithms

LEOPath currently includes:

• shortest_path_link_state: Dijkstra baseline over each dynamic topology snapshot.
• topological_routing: 6G-RUPA-inspired forwarding using structured satellite addresses.
• predictive_link_state: link-state computed on a predicted future topology snapshot.
• explicit_path_routing: centrally planned explicit-path routing with pinned satellite paths.

New routing algorithms can be added under leopath/network_state/routing_algorithms/ and registered in the routing algorithm factory.

Evaluation Workflow

Run a compact evaluation matrix:

./run-quick-eval.sh

Generate paper-oriented evaluation outputs:

./run-paper-eval.sh

Common outputs include CSV metrics, logs, plots, and metadata describing algorithm parameters and topology scenarios.

Documentation

• Documentation site: https://fundacio-i2cat.github.io/LEOPath/
• Cesium constellation viewer: https://fundacio-i2cat.github.io/LEOPath/cesium/
• Quickstart: https://fundacio-i2cat.github.io/LEOPath/quickstart/
• Routing algorithms: https://fundacio-i2cat.github.io/LEOPath/algorithms/
• Evaluation guide: https://fundacio-i2cat.github.io/LEOPath/evaluation/

Build and serve docs locally:

bash scripts/build-docs-site.sh
python -m http.server -d site

Then open http://localhost:8000.

Project Scope

LEOPath focuses on topology, routing state, and scalability metrics. It is not a packet-level simulator and does not model TCP/IP stacks, queues, PHY behavior, or detailed link-layer effects.

For packet-level studies, use LEOPath to generate forwarding-state artifacts and connect them to tools such as NS-3.

Development

python -m venv .venv
source .venv/bin/activate
pip install -e .
pytest
flake8
black .

Contributing

Contributions are welcome. Good first areas are new routing algorithms, additional constellation presets, visualization improvements, evaluation metrics, and documentation examples.

Before opening a pull request, run tests and formatters, and include a short note explaining the scenario or metric affected by the change.

License

LEOPath is released under the AGPL-3.0 license.