MPTRAC (Massive-Parallel Trajectory Calculations) is a high-performance Lagrangian particle dispersion model for simulating atmospheric transport in the free troposphere and stratosphere. The code supports large ensembles of air parcels and combines trajectory calculations with optional modules for diffusion, convection, sedimentation, chemistry, deposition, and diagnostic post-processing.

This Doxygen manual is the API and source-code reference for the MPTRAC core library and command-line tools. It is intended to complement, not replace, the project-level documentation in the repository.

Start here

• For installation, build instructions, and a project overview, see the README.
• For usage guidance, application workflows, and control-file syntax, see the User Manual.
• For source code, issues, and contributions, see the GitHub repository.

API map

Important entry points in this Doxygen manual include:

• mptrac.h: public declarations, constants, data structures, and function prototypes.
• mptrac.c: core implementation of the MPTRAC library routines.
• ctl_t: control parameters used by the command-line applications and library workflows.
• atm_t: air parcel state vectors and associated metadata.
• met_t: meteorological fields and diagnostics.
• clim_t: climatological input data.
• cache_t: interpolation and runtime cache structures.

Command-line applications

MPTRAC provides a set of standalone tools built from the src/ directory. Commonly used entry points are:

• trac: main trajectory calculation program.
• atm_init: initialize air parcel ensembles.
• atm_split: split or duplicate particle sets.
• atm_select: select subsets of particle data.
• atm_stat: compute statistics from particle output.
• met_map, met_prof, and met_zm: meteorological diagnostics and analysis.

These file pages document the corresponding source files and, where available, the command-line entrypoints. The user manual remains the better place for end-to-end examples and application recipes.

Parallel execution

MPTRAC supports OpenMP throughout the core code and can optionally be compiled with MPI and OpenACC/GPU support depending on the selected build configuration. Build flags and external dependencies are documented in the repository README.md, DEPENDENCIES.md, and the developer manual.

Related documentation

• README: installation, build, and project overview.
• User Manual: application usage, configuration, and scientific background.
• Contributing Guide: contribution workflow.
• Code of Conduct: collaboration guidelines.

Citation

If you use MPTRAC in scientific work, please cite the relevant 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., Rößler, T., Griessbach, S., Heng, Y., and Stein, O.: 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.

License

MPTRAC is distributed under the terms of the GNU General Public License v3.0. This open-source license ensures that MPTRAC remains free to use, modify, and distribute, while encouraging community-driven development.

Contributing

We welcome contributions to MPTRAC from both researchers and developers. If you encounter bugs, have suggestions, or want to propose new features, please use the issue tracker to report problems or ideas.

Contributions to the codebase, including bug fixes and enhancements, can be submitted via pull requests. For detailed instructions on contributing, please see the contributing guidelines in the repository.

Contact

For inquiries, support, or collaboration opportunities, please contact:

Dr. Lars Hoffmann

Jülich Supercomputing Centre, Forschungszentrum Jülich, Germany

e-mail: l.hof.nosp@m.fman.nosp@m.n@fz-.nosp@m.juel.nosp@m.ich.d.nosp@m.e