Massive-Parallel Trajectory Calculations (MPTRAC) is a Lagrangian particle dispersion model for the analysis of atmospheric transport processes in the free troposphere and stratosphere.
Massive-Parallel Trajectory Calculations (MPTRAC) is a Lagrangian particle dispersion model for simulating atmospheric transport in the free troposphere and stratosphere. The model is designed to run on parallel computing systems and supports large ensembles of trajectory calculations.
MPTRAC uses meteorological input data to compute air parcel motion and includes parameterizations for processes such as advection, diffusion, and convection. These capabilities allow the simulation of transport over a wide range of spatial and temporal scales.
Typical applications include studies of long-range pollutant transport, volcanic ash dispersion, tracer experiments, and atmospheric chemistry. MPTRAC is used in both research and operational contexts to investigate atmospheric transport processes.
To support easier access, especially for teaching and exploratory use, MPTRAC is also available through the MPTRAC Web Runner, which allows simulations to be run via a web browser without local installation.
MPTRAC provides various capabilities for Lagrangian atmospheric transport simulations, including:
-
Trajectory calculations: Air parcel trajectories are computed by solving the kinematic equation of motion using horizontal wind and vertical velocity fields from global reanalysis or forecast data. The model supports simulations in the free troposphere and stratosphere.
-
Stochastic perturbations and mixing: Mesoscale diffusion and subgrid-scale wind variability are represented using a Langevin formulation. An inter-parcel exchange scheme is available to model mixing between neighboring particles.
-
Physical and chemical process modules: MPTRAC includes optional parameterizations for convection, sedimentation, exponential decay, gas-phase and aqueous-phase chemistry, as well as wet and dry deposition processes.
-
Meteorological data preprocessing: Input meteorological data can be preprocessed to derive additional variables such as boundary layer height, convective available potential energy (CAPE), geopotential height, potential vorticity, and tropopause diagnostics.
-
Output and analysis options: The model supports multiple output formats, including particle trajectories, gridded fields, ensemble statistics, vertical profiles, point samples, and station data. Visualization is supported through interfaces to Gnuplot and ParaView.
-
Parallel execution: MPTRAC supports hybrid parallelization using MPI, OpenMP, and OpenACC, enabling execution on systems ranging from single workstations to HPC clusters and GPU-enabled platforms.
-
Web-based access: A browser-based interface, the MPTRAC Web Runner, is available for running simulations without local installation, primarily intended for educational and exploratory use.
-
Open-source development: MPTRAC is distributed under the GNU General Public License (GPL) and developed in an open repository, allowing users to inspect, modify, and contribute to the codebase.
To build and run MPTRAC, you will need some basic tools and libraries, including Git, GNU Make, GCC, GSL, HDF5, and netCDF.
For additional features such as HPC and GPU support, optional dependencies like OpenMPI and the NVIDIA HPC SDK are required.
Some of the required dependencies are included with the MPTRAC repository. See the next section for more details.
For a complete list of dependencies, including specific versions and installation instructions, refer to the dependencies file.
To install MPTRAC, follow these steps:
1. Download MPTRAC
Get the latest or a previous version from the MPTRAC releases page. After downloading, extract the release file:
unzip mptrac-x.y.zip
Alternatively, to get the latest development version, clone the GitHub repository:
git clone https://github.com/slcs-jsc/mptrac.git
2. Install required libraries
The MPTRAC git repository includes several libraries that can be compiled and installed using a build script:
cd [mptrac_directory]/libs
./build.sh -a
Alternatively, if you prefer to use existing system libraries, install the dependencies manually.
3. Configure the Makefile
Navigate to the source directory and adjust the Makefile as needed:
cd [mptrac_directory]/src
emacs Makefile
Pay special attention to the following settings:
-
Edit the
LIBDIRandINCDIRpaths to point to the directories where the GSL, netCDF, and other required libraries are located on your system. -
By default, the MPTRAC binaries are linked dynamically. Ensure that the
LD_LIBRARY_PATHis properly configured to include the paths to the shared libraries. If you prefer static linking, you can enable it by setting theSTATICflag, which allows you to copy and use the binaries on other machines. However, in some cases, either static or dynamic linking may not be feasible or could cause specific issues. -
To enable MPI parallelization in MPTRAC, you must set the
MPIflag. Additionally, an MPI library, such as OpenMPI, must be installed on your system. To utilize OpenACC parallelization, enable theGPUflag, and ensure the NVIDIA HPC SDK is installed to compile the GPU code. OpenMP parallelization is always enabled. -
Some options in the Makefile are labeled as experimental. These features are still under development and may not be fully functional or tested. Use them at your own risk.
4. Compile and test the installation
Once the Makefile is configured, compile the code using:
make [-j]
To verify the installation, run the test suite:
make check
This will execute a series of tests sequentially. If any test fails, check the log messages for further details.
To demonstrate how MPTRAC can simulate the dispersion of volcanic ash, we provide an example based on the eruption of the Puyehue-Cordón Caulle volcano in Chile in June 2011. This example illustrates the setup and execution of a typical simulation.
The example is located in the projects/example/ subdirectory. You
can also use the projects/ folder to store results from your own
simulation experiments with MPTRAC.
Follow these steps to run the example simulation:
- Navigate to the example directory:
cd [mptrac_directory]/projects/example
- Execute the
run.shscript to start the simulation:
./run.sh
The run.sh script outlines the necessary steps to invoke MPTRAC
programs such as atm_init (for initializing trajectory seeds),
atm_split (for splitting particle groups), and trac (for computing
the trajectories). This script automates the simulation process,
ensuring a smooth workflow.
The output of the simulation will be stored in the
projects/example/data subdirectory. For comparison, reference data
is available in the projects/example/data.ref folder.
Additionally, the simulation generates several plots at different time
steps, which are stored in projects/example/plots. These plots show
the results of the volcanic plume dispersion over time and can be
visualized using the gnuplot plotting tool.
For example, particle positions and grid outputs at different time steps (June 6th and June 8th, 2011) are shown below:
In addition to the example simulation, MPTRAC provides several utility
scripts and resources in the projects/ directory to support your work:
-
projects/meteo/: Contains scripts for downloading meteorological input data from various data centers (e.g., ECMWF, NOAA), which are required for trajectory simulations. -
projects/python/: Includes Python scripts to read, analyze, and visualize MPTRAC output data, such as air parcel trajectories and gridded fields. These can be helpful for creating custom plots and diagnostics. -
projects/paraview/: Provides examples and guidelines for using ParaView to visualize MPTRAC air parcel data in an interactive 3D environment.
These directories offer helpful tools and examples for extending your use of MPTRAC beyond the basic workflow and adapting it to your specific research needs.
To learn more about MPTRAC and its scientific background, please refer to the following key publications:
-
Hoffmann, L., Clemens, J., Griessbach, S., Haghighi Mood, K., Heng, Y., Khosrawi, F., Liu, M., Lu, Y.-S., Meyer, C., Nobre Wittwer, N., Wu, X., Zou, L., MPTRAC: A high-performance Lagrangian transport model for atmospheric air parcel dispersion, Journal of Open Source Software, 10(111), 8177, https://doi.org/10.21105/joss.08177, 2025.
-
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.
For a complete list of related publications and references, please visit the references page.
The user manual provides detailed instructions on how to install, configure, and run MPTRAC, along with example workflows and practical tips.
Developer-oriented documentation, including code structure and API references, can be found in the Doxygen manual.
For additional information, please also refer to the MPTRAC Wiki.
We welcome contributions from the community to help improve and expand MPTRAC, supporting both operational and research applications.
If you encounter any issues, bugs, or have suggestions for new features, please let us know by submitting a report on the issue tracker. Your feedback helps us make MPTRAC better for everyone.
If you would like to contribute code, fix bugs, or enhance existing features, feel free to submit a pull request. We appreciate well-documented and tested contributions.
Before getting started, please take a moment to read the contributing guidelines. They include helpful information on setting up your development environment and best practices for submitting contributions.
If you have any questions or need assistance during the process, don't hesitate to reach out. We are happy to help and collaborate!
MPTRAC is developed at the Jülich Supercomputing Centre, Forschungszentrum Jülich, Germany.
The project is released as open-source software to support transparent use and collaborative development.
MPTRAC is distributed under the terms of the GNU General Public License v3.0. This license ensures that the software remains free and open, while also allowing for modifications and redistribution under the same terms.
If you use MPTRAC in scientific publications or research work, please make sure to cite it appropriately. Detailed citation information can be found in the citation file.
Thank you for supporting open science and helping to advance MPTRAC!
For inquiries, support, or collaboration opportunities, please reach out to:
Dr. Lars Hoffmann
Jülich Supercomputing Centre, Forschungszentrum Jülich, Germany
e-mail: l.hoffmann@fz-juelich.de
Feel free to get in touch if you have questions about MPTRAC, need assistance, or are interested in contributing to the project.
