Hypatia LEO Satellite Network Simulation Framework

The paper/satellite_networks_state/input_data/ directory contains externally generated data files used for satellite network simulations and modeling. The data includes city population statistics and ground station grid configurations.

Available datasets include:

• Top 1000 Cities: ground_stations_cities_sorted_by_estimated_2025_pop_top_1000.basic.txt (cities sorted by estimated 2025 population).
• Top 100 Cities: ground_stations_cities_sorted_by_estimated_2025_pop_top_100.basic.txt (a subset of the top 1000).
• Paris-Moscow Relay Grid: ground_stations_paris_moscow_grid.basic.txt (contains Paris, Moscow, and a grid of ground stations between them designed to function as relays).

Hypatia performs low earth orbit (LEO) satellite network simulations at packet-level granularity using ns-3. It integrates two primary modules:

• satellite: Handles satellite movement calculation using SGP-4. Hypatia uses this to calculate channel delay for packets traversing Ground-to-Satellite Links (GSL) or Inter-Satellite Links (ISL). The source is located at simulator/src/satellite.
• basic-sim: A simulation framework designed to simplify running end-to-end flows (e.g., TCP). It is included as a git submodule at simulator/contrib/basic-sim.

Hypatia is a low earth orbit (LEO) satellite network simulation framework consisting of four primary modules:

• satgenpy: A Python framework for generating LEO satellite networks and routing over time. It includes analysis tools and relies on modules like numpy, astropy, networkx, and sgp4.
• ns3-sat-sim: An ns-3 based framework for packet-level simulations. It consumes the state generated by satgenpy and uses the satellite and basic-sim ns-3 modules to simulate network traffic (e.g., TCP flows).
• satviz: A Cesium visualization pipeline that generates interactive 3D satellite network visualizations using CesiumJS. Note: Users must obtain a Cesium access token from cesium.com to use the API.
• paper: Experimental and plotting code used to reproduce the results and figures presented in the original IMC 2020 paper.

The scripts/ directory contains several Python scripts for different visualization tasks:

• visualize_constellation.py: Generates visualizations for entire constellations (multiple shells).
• visualize_horizon_over_time.py: Plots satellite positions (azimuth, altitude) relative to a static observer over time.
• visualize_path.py: Visualizes paths between pairs of endpoints at specific time instances.
• visualize_path_no_isl.py: Visualizes paths between pairs of endpoints when no inter-satellite connectivity (ISL) exists.
• visualize_path_wise_utilization.py: Visualizes link utilization for specific end-to-end paths at a specific time instance.
• visualize_utilization.py: Visualizes link utilization for all end-to-end paths at a specific time instance.

satgenpy generates six key components required to analyze or simulate a LEO (Low Earth Orbit) satellite network:

1. ground_stations.txt: Properties and locations of ground stations.
2. tles.txt: Two-Line Element sets describing satellite orbits.
3. isls.txt: Topology of inter-satellite links.
4. gsl_interfaces_info.txt: Number of ground-to-satellite link (GSL) interfaces per node.
5. description.txt: Metadata such as maximum ISL/GSL lengths.
6. dynamic_state/: A directory containing time-varying data, specifically:
   • fstate_*.txt: Forwarding state.
   • gsl_if_bandwidth_*.txt: GSL interface bandwidths.

The full reproduction of the paper results follows a multi-step pipeline. Each step is documented in its respective subdirectory:

1. Generate LEO satellite network dynamic state: See paper/satellite_networks_state/README.md.
2. Build ns-3 simulator: See ns3-sat-sim/README.md.
3. Perform analysis using satgenpy: See paper/satgenpy_analysis/README.md.
4. Run ns-3 experiments: See paper/ns3_experiments/README.md.
5. Generate satviz figures: See satviz/README.md under Visualizations in the paper.
6. Plot figures: See paper/figures/README.md.

After installing dependencies and initializing submodules, use the provided build script to compile the simulation environment with optimizations enabled.

bash build.sh --optimized

Use visualize_constellation.py to generate constellation visualizations.

By default, the script generates a Starlink 5-shell constellation. To visualize other constellations like Kuiper or Telesat, edit the script to uncomment the desired parameter block and comment out the others.

python scripts/visualize_constellation.py

To use Hypatia, ensure your system meets the following requirements:

• Python version: 3.7 or higher
• Operating System: Recent Linux distribution (e.g., Ubuntu 18+)

Follow these steps to install dependencies, build the modules, and verify the installation:

1. Install dependencies: Run the provided dependency installation script.
2. Build modules: Build the four main components (satgenpy, ns3-sat-sim, satviz, and paper).
3. Run tests: Execute the integration tests to ensure everything is working correctly.

For a practical tutorial on using the framework, refer to the reproduction code in the paper/ directory.

# 1. Install dependencies
bash hypatia_install_dependencies.sh

# 2. Build all four modules
bash hypatia_build.sh

# 3. Run tests
bash hypatia_run_tests.sh

Use the perform_full_analysis.py script to analyze satellite network state data. This script processes the data generated in satellite_networks_state to provide an analysis of constellations both as a whole and for specific pairs.

Note: This process is time-consuming.

Prerequisites: Ensure all dependencies are installed as specified in the <hypatia>/satgenpy/README.md file.

python perform_full_analysis.py