Table of Contents

Quickstart

Docker

NEW! Docker versions are now available for:

  • the command line interface (CLI) version: mercury_cli;

  • the notebook version: mercury_nb;

  • the GUI version: (coming soon).

Docker allows you to use the model on any OS without installing anything except a docker environment (see https://www.docker.com/get-started/). With a terminal (e.g. PowerShell in Windows), you can download the docker images like this:

docker pull ghcr.io/uow-atm/mercury/mercury_nb:latest
docker tag ghcr.io/uow-atm/mercury/mercury_nb:latest mercury_nb
docker pull ghcr.io/uow-atm/mercury/mercury_cli:latest
docker tag ghcr.io/uow-atm/mercury/mercury_cli:latest mercury_cli

In a terminal, you can then use the docker image like this:

  • for the CLI:

docker run mercury_cli -id -1 -cs -1

  • for the notebook:

docker run -p 8888:8888 mercury_nb

You probably need to copy the URL appearing in the terminal after this command and copy/paste it into your browser.

  • for the GUI: (coming soon)

Installation

Mercury has been tested on Ubuntu-like machines and, to a lesser extent, Windows, using minicoonda/anaconda. Python 3.10 is recommended, Python 3.12 will raise issues.

Quick install

A bash script is available for quick installations in Linux. You can download it from `here https://github.com/UoW-ATM/Mercury/blob/master/mercury_quick_install_stable.sh`_ for the stable version (master branch) and `here https://github.com/UoW-ATM/Mercury/blob/dev/mercury_quick_install_dev.sh`_ for the dev version. You need to download them first and then run them in a terminal like this:

./mercury_quick_install_dev.sh

This might or might not work depending on your specific environment, particularly your virtual environment setting. If it fails, you can follow the steps below.

Full install

  • Start by cloning the repository, for instance:

git clone https://github.com/UoW-ATM/Mercury

  • Use this to download the third-party libraries:

cd Mercury
git submodule update --recursive --remote --init

  • In a fresh Python environment, install all the required packages:

In Linux, use:

sudo apt-get install libproj-dev libgeos-dev build-essential python3-dev proj-data proj-bin
python -m pip install shapely cartopy --no-binary shapely --no-binary cartopy
pip install -r requirements.txt

In Windows, you need to install the requirements in the dedicated environment:

pip install -r requirements.txt

You may also need to install Visual Studio C++-built tools if that’s not the case already.

wget https://zenodo.org/records/11384379/files/Mercury_data_sample.zip?download=1 -O ../mercury_public_dataset.zip
unzip ../mercury_public_dataset.zip -d ../input/
rm ../mercury_public_dataset.zip

By default, Mercury uses the OpenAP model for aircraft performance. However, Mercury also supports the BADA models developed by EUROCONTROL. If you want to use it, you can request a licence from EUROCONTROL (here: https://www.eurocontrol.int/model/bada), then use the script generate_bada3_input.py to transform the AFP, OFP and PTD files from BADA3 into tables (parquet files) that Mercury will read. In the following command, replace BADA3_FILES_PATH with the location of the downloaded bada files:

python generate_bada3_input.py -s BADA3_FILES_PATH -d .

Ensure you copy the generated parquet files into Mercury/libs/performance_models/bada3/data/.

If you want to use BADA4, please contact us directly, and we’ll offer general guidance. We are also working on a support for EUROCONTROL’s pyBADA library.

Running the CLI version

You can test the model by running:

./mercury.py -id -1 -cs -1

Use -h to have list of all the possible arguments.

Programmatic use of Mercury

Mercury can be used as an object. An example of its use and some examples to run can be found in the Mercury.ipynb Jupyter notebook. The notebook shows the possible uses of Mercury in terms of parameter setting, scenarios, case study, etc.

Graphical interface

You can use a GUI to explore the data input and output structure, create new scenarios, case studies, etc. Use the following command to start it:

python mercury_gui.py