Mercury is a research-oriented air transportation mobility simulator with a strong agent-based paradigm.

Table of Contents

• Quickstart

  • Docker
  • Installation
  • Running the CLI version
  • Programmatic use of Mercury
  • Graphical interface

• Manual and references
• Software Architecture

• About

  • Authorship
  • Licence and copyright

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.

• Download the sample data here: https://zenodo.org/records/11384379/files/Mercury_data_sample.zip?download=1. Extract the data. Put the results "input" folder outside the main Mercury root folder (side by side). You can also use the following commands from inside the Mercury root folder to achieve the same result:

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

Manual and references

A more complete manual is in construction and can be found here.

The following articles can also be consulted to learn more about Mercury:

• the one included in the repo, presenting the general approach to Mercury,
• the one available there showing some details of Mercury and some examples of its uses, from a few years back.

Software Architecture

Mercury is organised in three packages:

1. agents: This is the main package containing the implementation of different agents in Mercury. The agents are developed following an object-oriented approach. Each agent type is a Class containing its memory (attributes) and Roles. The Roles are independent Classes contained within the Agents. All agent types inherit from a generic Agent class, which provides the shared functionalities of initialisation, mailbox and functionalities required to modify their behaviour through the application of Modules. Two sub-packages are located inside the agents' package:

• Modules:

  This package stores different modules that can be loaded into Mercury. A Module is composed of three files:

  • the Python code implementing the functionalities that need to be added and/or replaced in the different Roles,
  • a configuration file indicating which functions need to be added/replaced for which roles, and
  • an optional configuration file with any additional parameters needed for the new functionalities implemented in the module.

• Commodities:

  Contains different objects used and manipulated by the agents, such as the definition of aircraft, alliance, slots, etc. Each one of these concepts will be represented by one or several classes.

2. libs: The libs package contains functionalities required by Mercury, such as the implementation of the Delivery system, World builder (to create the agents at the instantiation of a simulation), Simulation manager (to manage the execution of Mercury), Case study loader, etc. Functionalities to manage the input and output of Mercury are also provided here (Input and Output managers). Finally, external libraries are also included here.
3. config: The config package contains the configuration files of Mercury and the simulations.

About

Authorship

Up to the open-source release, all Mercury code has been written by Gérald Gurtner and Luis Delgado, to the exception of:

• The Dynamic Cost Indexing module, written by Damir Valput
• The GUI, written by Michal Weiszer

We also thank Tanja Bolic for many waves of testing.

Licence and copyright

Mercury is released under the GPL v3 licence. The licence can be found in LICENCE.TXT

Mercury uses the Hotspot library (https://github.com/andygaspar/Hotspot) and the uow-belt-tools library (https://github.com/UoW-ATM/uow_tool_belt), both released under GPL v3 licence, and the OpenAP library (https://github.com/TUDelft-CNS-ATM/openap), released under the LGPL v3 licence.

Copyright 2023 Gérald Gurtner, Luis Delgado, University of Westminster, and Innaxis.

All subsequent copyright belongs to the respective contributors.