Massive-Parallel Trajectory Calculations

Massive-Parallel Trajectory Calculations (MPTRAC) is a Lagrangian particle dispersion model for the analysis of atmospheric transport processes in the free troposphere and stratosphere.

Features

• MPTRAC calculates air parcel trajectories by solving the kinematic equation of motion using given horizontal wind and vertical velocity fields.
• Mesoscale diffusion and sub-grid scale wind fluctuations are simulated using the Langevin equation to add stochastic perturbations to the trajectories.
• Additional modules are implemented to simulate convection, sedimentation, radioactive decay, hydroxyl chemistry, dry deposition, and wet deposition.
• Various output methods for particle, ensemble, gridded, sample, and station data. Gnuplot interface for direct visualization.
• MPTRAC features an MPI-OpenMP-OpenACC hybrid parallelization for efficient use on HPC and GPU systems.

Getting started

Prerequisites

This README file describes the installation of MPTRAC on a Linux system.

The following software dependencies are mandatory:

• the distributed version control system Git
• the C compiler of the GNU Compiler Collection
• the GNU Make build tool
• the GNU Scientific Library for numerical calculations
• the netCDF library for file-I/O

Optionally, the following software is required to enable further capabilities of MPTRAC:

• the graphing utility gnuplot for visualization
• the HDF5 library to support netCDF4
• the Zstandard library and the zfp library for compressed meteo data
• the NVIDIA HPC Software Development Kit for GPU support
• an MPI library such as OpenMPI or ParaStation MPI for HPC support

Some of the software is provided along with the MPTRAC repository, please see next section.

Installation

Start by downloading the MPTRAC source code from the git repository:

git clone https://github.com/slcs-jsc/mptrac.git

To update an existing installation, please use:

git pull https://github.com/slcs-jsc/mptrac.git

Several libraries provided along with MPTRAC can be compiled and installed by running the build script:

cd mptrac/libs
./build.sh

Next, change to the source directory and edit the Makefile according to your needs.

cd mptrac/src
emacs Makefile

In particular, you might want to check:

• Edit the LIBDIR and INCDIR paths to point to the directories where the GSL and netCDF libraries are located on your system.

• By default, the MPTRAC binaries will be linked statically, i.e., they can be copied and used on other machines. However, sometimes static compilations causes problems, e.g., in combination with dynamically compiled GSL and netCDF libraries or when using MPI and OpenACC. In this case, disable the STATIC flag and remember to set the LD_LIBRARY_PATH to include the libraries.

• To make use of the MPI parallelization of MPTRAC, the MPI flag needs to be enabled. Further steps will require an MPI library such as OpenMPI to be available. To make use of the OpenACC parallelization, the GPU flag needs to be enabled. The NVIDIA HPC SDK is required to compile the GPU code. The OpenMP parallelization of MPTRAC is always enabled.

Next, try to compile the code:

make

To run the test cases to check the installation, please use:

make check

Run the example

A simple example is provided, illustrating how to simulate the dispersion of volcanic ash from the eruption of the Puyehue-Cordón Caulle volcano, Chile, in June 2011.

The example can be found in the project directory. The project directory also be used to store results of other simulation and experiments with MPTRAC. The simulation is controlled by a shell script:

cd mptrac/projects/example
./run.sh

Please see the script run.sh on how to invoke MPTRAC programs such as atm_init and atm_split to initialize trajectory seeds and trac to calculate the trajectories.

The script generates a number of plots of the simulation output at different time steps after the eruption by means of the gnuplot graphing tool. These plots should look similar to the output already provided in the repository.

This is an example showing the particle position and grid output on 6th and 8th of June 2011:

Further information

More detailed information for new users and developers of MPTRAC is collected in the GitHub wiki.

These are the main references for citing the MPTRAC model in scientific publications:

• Hoffmann, L., Baumeister, P. F., Cai, Z., Clemens, J., Griessbach, S., Günther, G., Heng, Y., Liu, M., Haghighi Mood, K., Stein, O., Thomas, N., Vogel, B., Wu, X., and Zou, L.: Massive-Parallel Trajectory Calculations version 2.2 (MPTRAC-2.2): Lagrangian transport simulations on graphics processing units (GPUs), Geosci. Model Dev., 15, 2731–2762, https://doi.org/10.5194/gmd-15-2731-2022, 2022.

• Hoffmann, L., T. Rößler, S. Griessbach, Y. Heng, and O. Stein, Lagrangian transport simulations of volcanic sulfur dioxide emissions: Impact of meteorological data products, J. Geophys. Res. Atmos., 121, 4651-4673, https://doi.org/10.1002/2015JD023749, 2016.

• You can cite the source code of MPTRAC by using the DOI https://doi.org/10.5281/zenodo.4400597. This DOI represents all versions, and will always resolve to the latest one. Specific DOIs for each release of MPTRAC can be found on the zenodo web site.

Please see the citation file for further information.

Contributing

We are interested in sharing MPTRAC for operational and research applications. Please do not hesitate to contact us, if you have any further questions or need support.

License

MPTRAC is distributed under the GNU General Public License v3.0.

Contact

Dr. Lars Hoffmann

Jülich Supercomputing Centre, Forschungszentrum Jülich

e-mail: [email protected]

website: https://www.fz-juelich.de/ias/jsc/slcs