Hypatia

Hypatia is a low earth orbit (LEO) satellite network simulation framework. It pre-calculates network state over time, enables packet-level simulations using ns-3 and provides visualizations to aid understanding. This repository details my extensions to get the framework working with up-to-date tooling and the adaptions made to suit my Master's final year project.

Plots can be found on my personal site.

It consists of four main components:

• satgenpy : Python framework to generate LEO satellite networks and generate routing over time over a period of time. It additionally includes several analysis tools to study individual cases. It makes use of several Python modules among which: numpy, astropy, ephem, networkx, sgp4, geopy, matplotlib, statsmodels, cartopy (and its dependent (data) packages: libproj-dev, proj-data, proj-bin, libgeos-dev), and exputil. More information can be found in satgenpy/README.md. (license: MIT)

• ns3-sat-sim : ns-3 based framework which takes as input the state generated by satgenpy to perform packet-level simulations over LEO satellite networks. It makes use of the satellite ns-3 module by Pedro Silva to calculate satellite locations over time. It uses the basic-sim ns-3 module to make e.g., running end-to-end TCP flows easier, which makes use of several Python modules (e.g., numpy, statsmodels, exputil) as well as several other packages (e.g., OpenMPI, lcov, gnuplot). More information can be found in ns3-sat-sim/README.md. (license: GNU GPL version 2)

• satviz : Cesium visualization pipeline to generate interactive satellite network visualizations. It makes use of the online Cesium API by generating CesiumJS code. The API calls require its user to obtain a Cesium access token (via https://cesium.com/). More information can be found in satviz/README.md. (license: MIT)

• paper : Experimental and plotting code to reproduce the experiments and figures which are presented in the paper. It makes use of several Python modules among which: satgenpy, numpy, networkload, and exputil. It uses the gnuplot package for most of its plotting. More information can be found in paper/README.md. (license: MIT)

(there is a fifth folder called integration_tests which is used for integration testing purposes)

This is the code repository introduced and used in "Exploring the “Internet from space” with Hypatia" by Simon Kassing*, Debopam Bhattacherjee*, André Baptista Águas, Jens Eirik Saethre and Ankit Singla (*equal contribution), which is published in the Internet Measurement Conference (IMC) 2020.

BibTeX citation:

@inproceedings {hypatia,
    author = {Kassing, Simon and Bhattacherjee, Debopam and Águas, André Baptista and Saethre, Jens Eirik and Singla, Ankit},
    title = {{Exploring the “Internet from space” with Hypatia}},
    booktitle = {{ACM IMC}},
    year = {2020}
}

Getting started

1. System requirements:

   • Python version 3.10
   • C++17 compiler (gcc)
   • Recent Linux operating system (e.g., Ubuntu 18+)
     • My personal setup was on Fedora Workstation 40. I have not tested the below instructions on other distributions.
   • A pretty powerful computer.
     • The simulations are demanding.

2. Create Python virtual environment:

   Create and activate a virtual environment:

   python3.10 -m venv venv
   source venv/bin/activate
   

   Install dependencies:

   pip install -r requirements.txt
   

3. Install system dependencies:

   For Fedora-based distros:

   sudo dnf update
   sudo dnf install proj-devel proj-data geos-devel openmpi openmpi-devel lcov gnuplot 
   

   For Ubuntu/Debian-based distros:

   sudo apt-get update && sudo apt-get install -y libproj-dev proj-data proj-bin libgeos-dev openmpi-bin openmpi-common openmpi-doc libopenmpi-dev lcov gnuplot
   

4. Build all four modules (as far as possible):

   Make sure your shell is using C++17 and able to find the MPI installation. This assumes you are using bash as a shell.

   export CXXFLAGS="-std=c++17"
   export PATH=/usr/lib64/openmpi/bin:$PATH
   source ~/.bashrc
   

   Now try to build Hypatia.

   bash hypatia_build.sh
   

5. Run tests:

   bash hypatia_run_tests.sh
   

6. The reproduction of the paper is essentially the tutorial for Hypatia. Please navigate to paper/README.md and follow the steps described.

Visualizations

Most of the visualizations in the paper are available here. All of the visualizations can be regenerated using scripts available in satviz as discussed above.

Below are some examples of visualizations:

• SpaceX Starlink 5-shell side-view (left) and top-view (right). To know the configuration of the shells, click here.

  

• Amazon Kuiper 3-shell side-view (left) and top-view (right). To know the configuration of the shells, click here.

  

• RTT changes over time between Paris and Luanda over Starlink 1st shell. Left: 117 ms, Right: 85 ms. Click on the images for 3D interactive visualizations.

  

• Link utilizations change over time, even with the input traffic being static. For Kuiper 1st shell, path between Chicago and Zhengzhou at 10s (top) and 150s (bottom). Click on the images for 3D interactive visualizations.