The paper presents three main claims regarding LEOCraft:
LEOCraft is a flow-level LEO network simulator that can rapidly assess a given LEO constellation design’s throughput, coverage, and stretch/latency with specified ground stations and traffic matrices.
LEOCraft employs a search space heuristic that significantly accelerates the optimization of constellation design for specific ground stations and traffic matrices, especially when compared to naive approaches.
LEOCraft can evaluate and simulate designs for multi-shell LEO constellations and inter-shell inter-satellite link connectivity.
LEOCraft features an interactive visualization framework that allows for an intuitive understanding and examination of LEO network designs and their dynamics.
To reproduce the results, follow the steps given below.
Clone the LEOCraft repository.
git clone https://github.com/suvambasak/LEOCraft.git
Change the directory.
cd LEOCraft
Create a conda environment from environment.yml or environment_macOS.yml.
conda env create -f tools/environment.yml
or
conda env create -f tools/environment_macOS.yml
Activate leocraft environment.
conda activate leocraft
Since LEOCraft is a flow-level simulator, it uses Gurobi Optimizer to solve the linear program of throughput maximization. To set Gurobi Optimizer:
Extract the license tools licensetools12.0.1_linux64.tar.gz or download the license tools based on your platform to the binary grbgetkey.
Sign up and generate free Named-User Academic license.
To save the license on your system, execute the following.
./grbgetkey <LICENSE_KEY>
Enter and store the gurobi.lic file in the home directory.
info : grbgetkey version 12.0.1, build v12.0.1rc0
info : Platform is linux64 (linux) - "Linux Mint 22.1"
info : Contacting Gurobi license server...
info : License file for license ID XXXXXXX was successfully retrieved
info : License expires at the end of the day on XXXX-XX-XX
info : Saving license file...
In which directory would you like to store the Gurobi license file?
[hit Enter to store it in /home/suvam]:
Export the LEOCraft project path in the shell, which will allow seamless execution of scripts.
export PYTHONPATH=$(pwd)
Or, for instance, if the repository is cloned at /mnt/Storage/Projects/LEOCraft
export PYTHONPATH="/mnt/Storage/Projects/LEOCraft"
To validate the simulation environment setup, execute example_starlink.py, which simulates the Starlink multi-shell LEO constellation.
python examples/example_starlink.py
The LEOCraft setup is successful if you see something like this.
[LEOConstellation] Building ground stations...
[LEOConstellation] Building shells...
[LEOConstellation] Building ground to satellite links...
[LEOConstellation] GSLs generated in: 0.08m
[LEOConstellation] Adding satellites into network graph...
[LEOConstellation] Adding ISLs into network graph...
[LEOConstellation] Routes generated in: 2.2m
[Throughput] Building throughput...
[Throughput] Computing throughput...
LP formation...Set parameter Username
Academic license - for non-commercial use only - expires XXXX-XX-XX
[Throughput] Optimized in: 0.11m
[Throughput] Throughput: 6144.55 Gbps
[Throughput] Total accommodated flow: 30.562 %
[Throughput] NS path selection: 5.929 %
[Throughput] EW path selection: 3.848 %
[Throughput] NESW path selection: 5.325 %
[Throughput] HG path selection: 2.601 %
[Throughput] LG path selection: 7.466 %
[Coverage] Building coverage...
[Coverage] Computing coverage...
[Coverage] Out of coverage GS: 0
[Coverage] GS coverage metric: 148.79394673481124
[Stretch] Building stretch...
[Stretch] Computing stretch...
[Stretch] NS stretch: 1.357
[Stretch] NS hop count: 7.0
[Stretch] EW stretch: 1.504
[Stretch] EW hop count: 8.0
[Stretch] NESW stretch: 1.253
[Stretch] NESW hop count: 6.0
[Stretch] LG stretch: 1.434
[Stretch] LG hop count: 3.5
[Stretch] HG stretch: 1.181
[Stretch] HG hop count: 11.0
Total simulation time: 2.44m
Here are the steps to run the simulations and then regenerate the figures using the simulation results.
Note: Simulation with thousands of satellites takes time based on the capabilities of the system.
To regenerate the figure. 3, 5, 6, 9, 12 execute simulate_everything_gs_gs.py. This will simulate Starlink’s first shell (by default) while individually varying all the design parameters.
python experiments/simulations/simulate_everything_gs_gs.py
Then execute the exploring_search_space.ipynb to plot the simulation results to reproduce the paper’s figures.
Note: This same script can be used to regenerate the figure. 19, 20, 21, 22 of the paper by changing the values of default orbital parameters given in shell_code_archive.py or Table. 1 of the paper, Ground station locations, and traffic metrics across them.
# Starlink Shell-1 default
o = 72 # orbital planes
n = 22 # satellites per plane
i = 53 # inclination
e = 25 # angle of elevation
h = 550 # altitude
p = 50 # phase offset
t_m = 0 # time in minutes
GS = GroundStationAtCities.TOP_100
TM = InternetTrafficAcrossCities.POP_GDP_100
GS = GroundStationAtCities.TOP_100
TM = InternetTrafficAcrossCities.POP_GDP_100
GS = GroundStationAtCities.TOP_1000
TM = InternetTrafficAcrossCities.POP_GDP_1000
TM = InternetTrafficAcrossCities.COUNTRY_CAPITALS_ONLY_POP
GS = GroundStationAtCities.COUNTRY_CAPITALS
For figure. 23, to simulate with flights, use simulate_everything_gs_gs.py
To regenerate the figure. 14, first executes all the black-box optimization scripts to find the optimized constellation design parameters for given Ground Stations locations and Traffic Matrix across them. Note that each script optimizes all the highlighted budgets in the Table. 1 in the paper twice (i) with the search space heuristic and (ii) without the search space heuristic, and save the optimized parameters and running time in the appropriate CSV files.
python experiments/blackbox_optimization/variable_neighborhood_search.py
python experiments/blackbox_optimization/simulated_annealing.py
python experiments/blackbox_optimization/differential_evolution.py
python experiments/blackbox_optimization/adaptive_particle_swarm_optimization.py
Then, use evaluate_optimized_params.py to generate the network performance metrics of optimized design parameters.
First, set the corresponding CSV files path in evaluate_optimized_params.py.
INPUT_CSV_FILE = 'experiments/results/plot_for_paper/CSVs/blackbox_optimization/VNS/VNS_WDK.csv'
OUTPUT_CSV_FILE = 'experiments/results/plot_for_paper/CSVs/blackbox_optimization/VNS/VNS_WDK_PERF.csv'
Then, execute the file.
python experiments/utilities/evaluate_optimized_params.py
Then execute compare_optimization_techniques.ipynb to reproduce the figures.
To generate the figure. 15, first execute single_vs_multi_shell_design.py. It will simulate all design choices and save their throughput in CSV files.
python experiments/multi_shell_design/single_vs_multi_shell_design.py
Then execute the second and third cells of exploring_multi_shell_designs.ipynb to generate the bar charts.
To generate the figure. 16, first execute variable_neighborhood_search_for_intershell_ISLs.py. It will optimized the design of $(i)$ single shell with +Grid ISLs, $(ii)$ two shell with +Grid inter shell ISLs, $(iii)$ three shells with inter shell ISLs for given GSes and traffic metrics with budget of Starlink Gen1 (S-1, S-2, S-3) in Table.1 in the paper.
python experiments/blackbox_optimization/variable_neighborhood_search_for_intershell_ISLs.py
Then execute throughput_shift_inter_shell_ISL_without_handoff_h24.py to generate throughput metrics without handoff over $24$ hours of these three design, i.e., $(i)$ single shell with +Grid ISLs, $(ii)$ two shell with +Grid inter shell ISLs, $(iii)$ three shells with inter shell ISLs.
python experiments/multi_shell_design/throughput_shift_inter_shell_ISL_without_handoff_h24.py
Then execute the first cell of exploring_multi_shell_designs.ipynb to reproduce the figure.
The paper also includes a handful of visuals to illustrate the nitty gritty of LEO network design, which is generated mainly by the LEOCraft 2D/3D visualization framework. To reproduce these interactive figures, execute the following scripts.
python experiments/visuals_for_paper/kuiper_shells.py
python experiments/visuals_for_paper/routes_categories.py
python experiments/visuals_for_paper/coverage_cone_with_e.py
python experiments/visuals_for_paper/constellation_coverage_change_with_altitude.py
python experiments/visuals_for_paper/GS_locations.py
python experiments/visuals_for_paper/inclination_change_starlink.py
python experiments/visuals_for_paper/routes_view_with_i_e.py
python experiments/visuals_for_paper/topology_view_with_oxn_p.py
python experiments/visuals_for_paper/HC_route_path_diversity.py
python experiments/visuals_for_paper/routes_view_with_h_e_raw.py
python experiments/visuals_for_paper/satellite_ground_track.py
python experiments/visuals_for_paper/ISL_usage.py