MPTRAC

A Lagrangian particle dispersion model for the analysis of atmospheric transport processes in the free troposphere and stratosphere.
https://github.com/slcs-jsc/mptrac

Category: Atmosphere
Sub Category: Atmospheric Dispersion and Transport

Keywords

atmospheric-modelling atmospheric-science climate climate-science dispersion dispersion-model high-performance-computing meteorology stratosphere trajectories troposphere

Keywords from Contributors

measurements

Last synced: about 12 hours ago
JSON representation

Repository metadata

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

Host: GitHub
URL: https://github.com/slcs-jsc/mptrac
Owner: slcs-jsc
License: gpl-3.0
Created: 2019-12-27T13:02:15.000Z (over 5 years ago)
Default Branch: master
Last Pushed: 2025-04-19T15:38:12.000Z (7 days ago)
Last Synced: 2025-04-19T15:57:29.743Z (7 days ago)
Topics: atmospheric-modelling, atmospheric-science, climate, climate-science, dispersion, dispersion-model, high-performance-computing, meteorology, stratosphere, trajectories, troposphere
Language: C
Homepage:
Size: 1.06 GB
Stars: 40
Watchers: 10
Forks: 15
Open Issues: 20
Releases: 19
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: COPYING
- Code of conduct: CODE_OF_CONDUCT.md
- Citation: CITATION.cff

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 from global reanalyses or forecasts.
Mesoscale diffusion and subgrid-scale wind fluctuations are simulated using the Langevin equation to add stochastic perturbations to the trajectories. A new inter-parcel exchange module represents mixing of air.
Additional modules are implemented to simulate convection, sedimentation, exponential decay, gas and aqueous phase chemistry, and wet and dry deposition.
Meteorological data pre-processing code provides estimates of the boundary layer, convective available potential energy, geopotential heights, potential vorticity, and tropopause data.
Various output methods for particle, grid, ensemble, profile, sample, and station data. Gnuplot and ParaView interfaces for visualization.
MPI-OpenMP-OpenACC hybrid parallelization and distinct code optimizations for efficient use from single workstations to HPC and GPU systems.
Distributed open source under the terms of the GNU GPL.

Getting started

Prerequisites

This README file describes how to install MPTRAC on a Linux system.

The following software dependencies are required to compile MPTRAC:

the GNU make build tool
the C compiler of the GNU Compiler Collection (GCC)
the GNU Scientific Library (GSL) for numerical calculations
the netCDF library for file-I/O

The following optional software is required to enable additional features of MPTRAC:

the distributed version control system Git to access the code repository
the HDF5 library to enable the netCDF4 file format
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 ParaStationMPI for HPC support
the graphing utility gnuplot for visualization

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

Installation

Start by downloading the latest or one of the previous MPTRAC releases on GitHub. Unzip the release file:

unzip mptrac-x.y.zip

Alternatively, you can get the latest development version of the software from the GitHub repository:

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

Several libraries shipped along with MPTRAC can be compiled and installed by running a build script:

cd [mptrac_directory]/libs
./build.sh -a

Then change to the source directory and edit the Makefile according to your needs:

cd [mptrac_directory]/src
emacs Makefile

In particular, you may want to check:

Edit the LIBDIR and INCDIR paths to point to the directories where the GSL, netCDF, and other libraries are located on your system.
By default, the MPTRAC binaries are linked statically, i.e., they can be copied and used on other machines. However, sometimes static compilation 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 paths to the shared libraries.
To make use of the MPI parallelization of MPTRAC, the MPI flag must be enabled. Further steps will require an MPI library such as OpenMPI to be available on your system. To make use of the OpenACC parallelization, the GPU flag must be enabled. The NVIDIA HPC SDK is required to compile the GPU code. MPTRAC's OpenMP parallelization is always enabled.

Next, try compiling the code:

make [-j]

To run the test cases to check the installation, use

make check

This will run a series of tests sequentially. It will stop if any of the tests fail. Please check the log messages.

Run the example

A simple example is provided to illustrate 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 projects/example/ subdirectory. The projects/ subdirectory can also be used to store the results of your own simulation experiments with MPTRAC.

The example simulation is controlled by a shell script:

cd mptrac/projects/example
./run.sh

See the run.sh script for how to invoke MPTRAC programs such as atm_init and atm_split to initialize the trajectory seeds and trac to compute the trajectories.

The script generates simulation output in the examples/data subdirectory. The corresponding reference data can be found in examples/data.ref.

A set of plots of the simulation output at different time steps after the eruption, generated by means of the gnuplot plotting tool, can be found in examples/plots. The plots should look similar to the output provided in examples/plots.ref.

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

Further information

These are the main scientific publications that provide information about MPTRAC:

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.

Additional references are collected on the references web page.

More detailed information for users of MPTRAC is provided in the user manual.

Information for developers of MPTRAC can be found in the doxygen manual.

Contributing

We are interested in supporting operational and research applications with MPTRAC.

You can submit bug reports or feature requests on the issue tracker.

Proposed code changes and fixes can be submitted as pull requests.

Please do not hesitate to contact us if you have any questions or need assistance.

License

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

Please see the citation file for more information about citing the MPTRAC model in scientific publications.

Contact

Dr. Lars Hoffmann

Jülich Supercomputing Centre, Forschungszentrum Jülich

e-mail: [email protected]

Citation (CITATION.cff)

# This CITATION.cff file was generated with cffinit.
# Visit https://bit.ly/cffinit to generate yours today!

cff-version: 1.2.0
title: Massive-Parallel Trajectory Calculations (MPTRAC)
message: >-
  If you use this software, please cite it using the
  metadata from this file.
type: software
authors:
  - given-names: Lars
    family-names: Hoffmann
    email: [email protected]
    affiliation: Forschungszentrum Jülich
    orcid: 'https://orcid.org/0000-0003-3773-4377' 
  - given-names: Jan
    family-names: Clemens
    email: [email protected]
    affiliation: Forschungszentrum Jülich
    orcid: 'https://orcid.org/0000-0002-2422-9454'
  - given-names: Sabine
    family-names: Griessbach
    email: [email protected]
    affiliation: Forschungszentrum Jülich
    orcid: 'https://orcid.org/0000-0003-3792-3573'
  - given-names: Kaveh
    family-names: Haghighi Mood
    email: [email protected]
    affiliation: Forschungszentrum Jülich
    orcid: 'https://orcid.org/0000-0002-8578-4961'
  - given-names: Farahnaz
    family-names: Khosrawi
    email: [email protected]
    affiliation: Forschungszentrum Jülich
    orcid: 'https://orcid.org/0000-0002-0261-7253'
  - given-names: Mingzhao
    family-names: Liu
    email: [email protected]
    affiliation: Forschungszentrum Jülich
    orcid: 'https://orcid.org/0000-0001-7314-9568'
  - given-names: Yen-Sen
    family-names: Lu
    email: [email protected]
    affiliation: Forschungszentrum Jülich
    orcid: 'https://orcid.org/0000-0002-3255-824X'
  - given-names: Jonas
    family-names: Sonnabend
    email: [email protected]
    affiliation: Forschungszentrum Jülich
  - given-names: Ling
    family-names: Zou
    email: [email protected]
    affiliation: Forschungszentrum Jülich
    orcid: 'https://orcid.org/0000-0001-6563-9815'
identifiers:
  - type: doi
    value: 10.5194/gmd-15-2731-2022
    description: Reference paper.
  - type: doi
    value: 10.1002/2015JD023749
    description: Reference paper.
  - type: doi
    value: 10.5281/zenodo.4400597
    description: Latest release on Zenodo.
  - type: url
    value: 'https://github.com/slcs-jsc/mptrac'
    description: Software repository on GitHub.
abstract: >-
  Massive-Parallel Trajectory Calculations (MPTRAC)
  is a Lagrangian particle dispersion model for the
  analysis of atmospheric transport processes in the
  free troposphere and stratosphere.
keywords:
  - atmospheric science
  - meteorology
  - transport model
  - trajectories
  - dispersion
  - troposphere
  - stratosphere
license: GPL-3.0

Owner metadata

Name: Simulation and Data Laboratory Climate Science
Login: slcs-jsc
Email: [email protected]
Kind: organization
Description:
Website: http://www.fz-juelich.de/ias/jsc/slcs
Location: Forschungszentrum Jülich, Germany
Twitter:
Company:
Icon url: https://avatars.githubusercontent.com/u/14200814?v=4
Repositories: 4
Last ynced at: 2023-03-05T19:36:56.465Z
Profile URL: https://github.com/slcs-jsc

GitHub Events

Total

Create event: 4
Release event: 1
Issues event: 7
Watch event: 3
Delete event: 1
Issue comment event: 12
Member event: 1
Push event: 654
Pull request event: 4
Gollum event: 3
Fork event: 2

Last Year

Create event: 4
Release event: 1
Issues event: 7
Watch event: 3
Delete event: 1
Issue comment event: 12
Member event: 1
Push event: 654
Pull request event: 4
Gollum event: 3
Fork event: 2

Committers metadata

Last synced: 4 days ago

Total Commits: 1,733
Total Committers: 31
Avg Commits per committer: 55.903
Development Distribution Score (DDS): 0.186

Commits in past year: 474
Committers in past year: 7
Avg Commits per committer in past year: 67.714
Development Distribution Score (DDS) in past year: 0.12

Name	Email	Commits
Lars Hoffmann	l**n@f**e	1410
Farahnaz Khosrawi	1****i	65
laomangio	l**5@o**m	64
Y.-S. Lu	6****l	28
janhclem	7****m	28
Mingzhao Liu	l**4@j**s	24
Sabine Griessbach	s**h@f**e	19
Catrin	c**r@f**e	18
Kaveh Haghighi Mood	k**d@f**e	11
Mingzhao Liu	l**4@j**s	9
Mingzhao Liu	l**4@j**s	8
Jan Heinrich Clemens	c**1@j**s	6
Jan Heinrich Clemens	c**1@j**s	5
liu14	l**4@j**s	4
Mingzhao Liu	l**4@j**s	4
Mingzhao Liu	l**4@j**s	4
Mingzhao Liu	l**4@j**s	3
Jan Heinrich Clemens	c**1@j**s	3
Jan Heinrich Clemens	c**1@j**s	3
Mingzhao Liu	l**4@j**s	2
Mingzhao Liu	l**4@j**s	2
Mingzhao Liu	l**4@j**s	2
Jan Heinrich Clemens	c**1@j**s	2
Jonas Sonnabend	j**d@f**e	2
Mingzhao Liu	l**4@j**s	1
Jan Heinrich Clemens	c**1@j**s	1
Jan Heinrich Clemens	c**1@j**s	1
Farahnaz Khosrawi	k**1@j**s	1
Bolarinwa O. Saheed	1****d	1
Johannes Holke	j**e@d**e	1
and 1 more...

Committer domains:

Issue and Pull Request metadata

Last synced: 1 day ago

Total issues: 37
Total pull requests: 12
Average time to close issues: 2 months
Average time to close pull requests: 6 days
Total issue authors: 6
Total pull request authors: 9
Average comments per issue: 2.41
Average comments per pull request: 0.67
Merged pull request: 11
Bot issues: 0
Bot pull requests: 0

Past year issues: 13
Past year pull requests: 2
Past year average time to close issues: 3 days
Past year average time to close pull requests: 1 day
Past year issue authors: 3
Past year pull request authors: 2
Past year average comments per issue: 1.54
Past year average comments per pull request: 1.5
Past year merged pull request: 2
Past year bot issues: 0
Past year bot pull requests: 0

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/slcs-jsc/mptrac

Top Issue Authors

lars2015 (24)
janhclem (4)
Tompythonorange (3)
zhangslTHU (3)
hs2112 (2)
hydrogencl (1)

Top Pull Request Authors

BolarinwaSaheed (3)
janhclem (2)
hydrogencl (1)
Kaveh01 (1)
lars2015 (1)
codacy-badger (1)
holke (1)
catrinmey (1)
fkhosrawi (1)

Top Issue Labels

enhancement (20)
bug (11)
question (1)

Top Pull Request Labels

Dependencies

.github/workflows/codecov.yml actions

actions/checkout v3 composite
codecov/codecov-action v3 composite

.github/workflows/docs.yml actions

actions/checkout v3 composite
actions/setup-python v4 composite
mattnotmitt/doxygen-action v1.9.4 composite
peaceiris/actions-gh-pages v3 composite

.github/workflows/tests.yml actions

actions/checkout v3 composite

Score: 7.528331766707247

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Open Sustainable Technology