This repository contains artifacts for the accepted Mobicom'23 paper "Transmitting, Fast and Slow: Scheduling Satellite Traffic through Space and Time".
We provide the environment using conda
.
To install the dependencies manually, run the following command:
conda env create -f umbra.yml
This will create a conda environment named umbra
with all the dependencies installed. To activate the environment, run the following command:
conda activate umbra
To download the Planet metadata, you have to first create an account on the Planet website. Then, you can download the metadata using the following command:
export PLANET_API_KEY=<your_api_key>
python preprocessing/download_planet_metadata.py --geojson_file data/california.geojson --output_pickle_file <output_file_name> \
--year <YEAR> --month <MONTH> --days <Number of days you want to download>
This will download the metadata for the Planet images that we used in our experiments and store it in the path you specified as the output file name.
If you don't have an API key, you can download the metadata gathered by us from this link. We provide the metadata for the first 4 days of June, July and August of 2021, which is the data we used in our experiments.
Disclaimer: The metadata is downloaded from the Planet website and is subject to their terms and conditions.
Planet has made a re-arrangement of its image assets in March 2022 and deprecated the metadata we used for experiments in the paper. The downloading script we provide uses the new scheme, so that you can download other dates to explore. However, the metadata downloaded using the script will be different from the one used in the experiment. If you want to replicate our experiment results, please use the metadata file we provide.
During preprocessing, you need to do 2 things (in order):
- Convert the Planet metadata to the format that can be used by the simulator
- Pre-calculate the satellite visibility and bandwidth traces
To convert the metadata, run the following command:
export PYTHONPATH=<path_to_umbra_repo>
python preprocessing/convert_planet_metadata.py --input_pickle_file <metadata_file> --output_pickle_file <mapping_file>
The export
command is to add the path to the umbra
repository to the PYTHONPATH
environment variable. This is required so that the script can import the dependencies within the umbra
repository. Make sure to have this environment variable set before running any python script in this repository.
The pre-processed metadata will be stored in the path you specified as the output file name. This file will be used in the next step. You can also download the pre-processed metadata from this link.
To pre-calculate the satellite visibility and bandwidth traces, you would need a DarkSky API key to get the weather information which is required for calculating the bandwidth. After getting your API key, run the following command:
export DARKSKY_KEY=<your_api_key>
python preprocessing/calculate_bandwidth.py --gs_config <gs_config_file> --satellite_mapping_file <satellite_mapping_file> --start_time YYYY-MM-DDTHH:MM:SS --end_time YYYY-MM-DDTHH:MM:SS --output_file <output_file>
Please make sure to calculate at least a 40-day-long trace for each month.
Note: We used DarkSky API to get the weather data. However, the DarkSky API is deprecated and is no longer available. You can run the calculation script which will assume clear weather for all the days since it cannot obtain weather info.
Then pre-computed bandwidth files are available here.
The next step is to run the main experiments and generate the raw results. Our main experiments can be devided into several parts
The main experiment produces results in Table 2, Figure 11 and 12. In the experiment, you need to run Umbra
together with all the baselines.
To run Umbra, run the following command:
python experiments/binary_search.py --image_mapping_info <mapping_file> --gs_config <ground_station_config> --start_time YYYY-MM-DDTHH:MM:SS --cache_file <bandwidth_file> --result_dir <result_directory>
Make sure that the start_time
matches the mapping_file
and bandwidth_file
matches the ground_station_config
and start_time
. Some raw simulation results will be stored in the result_directory
you specified. Each simulation instance will generate a folder containing multiple files as the results. These files will be used to generate the plos in the paper.
You can find the ground station config files we used in the paper in the config
folder of this repository.
To run the baselines, use the files experiments/basic_heuristic.py
, experiments/smart_heristic.py
and the same arguments as the Umbra
command. binary_search.py
generates results for both Umbra
and the greedy
baseline, and basic_heuristic.py
generates results for the naive
baseline. smart_heuristic.py
generates results for the smart
baseline.
For heterogeneous backhaul, modify the ground station config json file, change half of the ground stations to have a 1Gbps backhaul link and the other half to have a 2Gbps backhaul link. Then, run the main experiment.
Network crash experiment corresponds to Figure 13(b). To run the experiment, use files experiments/network_crash.py
, experiments/network_crash_oracle.py
and experiments/network_crash_baseline.py
. The arguments are the same as the main experiment.
Distributed Ground Station experiment corresponds to Table 5 and Figure 14. To run the experiment, you need to use the DGS ground station config files and bandwidth cache files. The experiment is otherwise the same as the main experiment.
The result files for the Main experiment & DGS experiment can be found here.
The SLURM scripts: If you have access to SLURM and a SLURM cluster, you can run most of the experiments using the scripts in the slurm/
folder. You will need to make sure that the path names in those scripts as well as the relay scripts (in scripts
folder) corresponds to the intermediate files you downloaded. Even if you don't have access to SLURM, you might find some of the scripts helpful for specifying the arguments to the experiments.
- Table 2 To generate table 2, use the code in
postprocessing/throughput.py
. You might need to change the path names in the code and run it multiple times to generate the entire table. - Figure 11 To generate figure 11, use the code in
postprocessing/latency.py
. You might need to change the path names in the code and run it multiple times to generate the 3 subfigures
To generate Table 4, use postprocessing/througput.py
to calculate the throughput for the heterogeneous backhaul experiment.
To generate Figure 13(b), use postprocessing/throughput_vs_time.py
to plot the throughput vs time for the network crash experiment. You might need to change the path names in the code.
Generate the results of this part using the same code as the main results. You might need to change the path names in the code.
Figure 12 was plotted manually using the results from the main experiment. We do not have a script to generate this figure. Follow the instructions in the paper to generate the figure.
- Figure 12(a): Compare the
best_flow_result.pkl
andassignment.pkl
in each result folder. Plot the cdf of the ratios of the optimized flow rate to the link capacity for each flow. You might findpostprocessing/queue.ipynb
helpful. - Figure 12(b): Look at
maxflow_gs_queue_record.pkl
andbaseline_gs_queue_record.pkl
in each result folder ofbinary_search.py
, and thegs_queue_record.pkl
in the result folder ofsmart_heuristic.py
andbasic_heuristic.py
. Plot the queue sizes of different ground stations over time.
For Figure 13(a), run experiments/binary_search.py
and specify the noise levels. Then, use postprocessing/latency.py
to get the percentile latency for each noise level. Plot the figure manually.