### MPTRAC Getting Started Guide Source: https://github.com/slcs-jsc/mptrac/blob/master/docs/manual/index.md This section provides guidance on how to start using MPTRAC, directing users to the installation guide for local setup and the quick start guide for basic simulations. It also highlights the MPTRAC Web Runner for browser-based access. ```markdown To begin using MPTRAC, users can refer to the [installation guide](installation.md), which provides detailed steps for setting up the model on a local machine or HPC system. Once installed, the [quick start guide](quickstart.md) offers a streamlined introduction to running basic simulations, helping new users become familiar with the model's core functionality and input structure. For those who prefer not to install any software locally, the [MPTRAC Web Runner](https://mptrac.jsc.fz-juelich.de) provides a convenient, browser-based interface for running trajectory simulations. This web tool is particularly useful for educational purposes, quick tests, and exploratory studies. ``` -------------------------------- ### Navigate and Run MPTRAC Example Source: https://github.com/slcs-jsc/mptrac/blob/master/projects/example/README.md This snippet shows the basic commands to navigate to the MPTRAC example directory and execute the simulation script. It outlines the sequence of MPTRAC binaries used in the simulation: atm_init, atm_split, and trac. ```bash cd [mptrac_directory]/projects/example ./run.sh ``` -------------------------------- ### Test MPTRAC Installation Source: https://github.com/slcs-jsc/mptrac/blob/master/docs/manual/installation.md Command to run the MPTRAC test suite to verify a successful installation. It is recommended to ensure all tests pass before using the model. ```makefile make check ``` -------------------------------- ### Build MPTRAC Libraries Source: https://github.com/slcs-jsc/mptrac/blob/master/docs/manual/installation.md This command builds and installs the libraries included with the MPTRAC repository. The process can be time-consuming, and users may opt to use pre-installed compatible library versions if available. ```bash cd [mptrac_directory]/libs ./build.sh -a ``` -------------------------------- ### Download MPTRAC Source Code Source: https://github.com/slcs-jsc/mptrac/blob/master/docs/manual/installation.md Instructions for obtaining the MPTRAC source code, either by downloading a release archive and extracting it, or by cloning the GitHub repository for the latest development version. It also includes how to update an existing installation. ```bash unzip mptrac-x.y.zip ``` ```bash git clone https://github.com/slcs-jsc/mptrac.git ``` ```bash git pull https://github.com/slcs-jsc/mptrac.git ``` -------------------------------- ### MPTRAC Control File (trac.ctl) Example Source: https://github.com/slcs-jsc/mptrac/blob/master/projects/example/README.md Illustrates the key-value syntax used in the trac.ctl file for configuring MPTRAC simulations. This file defines essential model settings and can be edited for customization. ```plaintext KEY = VALUE ``` -------------------------------- ### Running an Example MPTRAC Simulation Source: https://github.com/slcs-jsc/mptrac/blob/master/README.md Steps to execute a sample simulation for volcanic ash dispersion using the provided example scripts. This involves navigating to the example directory and running the simulation script. ```bash cd [mptrac_directory]/projects/example ./run.sh ``` -------------------------------- ### Configure and Compile MPTRAC Source: https://github.com/slcs-jsc/mptrac/blob/master/docs/manual/installation.md Steps to configure the Makefile with necessary paths and build options, followed by compiling the MPTRAC source code. The compilation can be parallelized using the '-j' flag. ```makefile cd [mptrac_directory]/src emacs Makefile ``` ```makefile make [-j] ``` -------------------------------- ### Makefile Installation and Packaging Source: https://github.com/slcs-jsc/mptrac/blob/master/docs/manual/code-development.md Commands for installing and uninstalling executables, and for creating a distributable zip package of the repository. ```makefile make install make uninstall make dist ``` -------------------------------- ### Run MPTRAC Example Simulation Source: https://github.com/slcs-jsc/mptrac/blob/master/docs/manual/quickstart.md This snippet shows the shell commands to navigate to the example simulation directory and execute the simulation script. It also mentions the use of `atm_init`, `atm_split`, and `trac` programs for initialization and trajectory calculation, and `gnuplot` for visualization. ```shell cd mptrac/projects/example ./run.sh ``` -------------------------------- ### MPTRAC Control Parameter File Example Source: https://github.com/slcs-jsc/mptrac/blob/master/docs/manual/control-parameters.md An example of a control parameter file used to configure MPTRAC applications. Blanks around the equals sign are mandatory, and array indices start from zero. ```config # Quantities... NQ = 3 QNT_NAME[0] = t QNT_NAME[1] = u QNT_NAME[2] = v # Meteo data... METBASE = meteo/ei DT_MET = 86400 # Grid output... GRID_LON0 = -90 GRID_LON1 = 60 GRID_LAT0 = -60 GRID_LAT1 = -15 GRID_NX = 300 GRID_NY = 90 ``` -------------------------------- ### Tropo Application Example Usage Source: https://github.com/slcs-jsc/mptrac/blob/master/docs/manual/apps/tropo.md Provides an example of how to set up a control file and run the tropo application with specific meteorological data inputs. It illustrates the typical workflow for generating a tropopause data set. ```bash # define the control file cat > tropo.ctl < { // Assuming there's a corresponding element in the DOM to update // For example: document.getElementById(field).value = s[field]; }); // Handle specific fields like met_source, plot_region, map_projection // document.getElementById('met_source').value = s.met_source; // document.getElementById('plot_region').value = s.plot_region; // document.getElementById('map_projection').value = s.map_projection; // Update other specific fields as needed // document.getElementById('atm_dt_out').value = s.atm_dt_out; } ``` -------------------------------- ### Minimal trac Input Example Source: https://github.com/slcs-jsc/mptrac/blob/master/docs/manual/apps/trac.md Provides a concrete example of the minimum required input files to successfully execute the trac application. ```bash # minimal required input to run trac $ ./trac data/dirlist trac.ctl atm_split.tab meteo/ei ``` -------------------------------- ### tnat Example Usage and Output Source: https://github.com/slcs-jsc/mptrac/blob/master/docs/manual/apps/tnat.md Provides an example of using the tnat application with specific input values for pressure, water vapor, and nitric acid, along with the corresponding output showing calculated formation temperatures. ```bash # Example: 50 hPa pressure, 5 ppmv H2O, 15 ppbv HNO3 $./tnat 50 5e-6 15e-9 # Expected Output: $ p = 50 hPa $ q_H2O = 5e-06 ppv $ q_HNO3 = 1.5e-08 ppv $ T_dew = 184.543 K $ T_ice = 188.559 K $ T_NAT = 196.312 K ``` -------------------------------- ### atm_conv Control File Example Source: https://github.com/slcs-jsc/mptrac/blob/master/docs/manual/apps/atm_conv.md Provides an example of a control file (atm_conv.ctl) used to configure the atm_conv tool. This example shows how to set the stop time, which is relevant for specific NetCDF output formats. ```bash cat > atm_conv.ctl < data/dirlist $trac/trac data/dirlist trac.ctl atm_split.tab \ ATM_BASENAME atm GRID_BASENAME grid ``` -------------------------------- ### Minimal Input for trac_fortran Source: https://github.com/slcs-jsc/mptrac/blob/master/docs/manual/fortran-wrapper.md A minimal example demonstrating the required input files to execute the 'trac_fortran' program. ```Shell # minimal required input to run trac_fortran $ ./trac_fortran data/dirlist trac.ctl atm_split.tab meteo/ei ``` -------------------------------- ### atm_conv Conversion Example Source: https://github.com/slcs-jsc/mptrac/blob/master/docs/manual/apps/atm_conv.md Illustrates a practical example of converting an ASCII input file to a NetCDF output file using the atm_conv tool, specifying the input and output types. ```bash atm_conv atm_conv.ctl input.tab 0 output.nc 2 ``` -------------------------------- ### Example atm_dist Execution Source: https://github.com/slcs-jsc/mptrac/blob/master/docs/manual/apps/atm_dist.md Provides a concrete example of how to run atm_dist with specific arguments. This includes a control file (trac.ctl), an output file (dist_absdev.tab), the deviation parameter (abs_dev), and two trajectory simulation files. ```bash ./atm_dist trac.ctl dist_absdev.tab abs_dev traj_sim1_2017_01_01_00.tab traj_sim2_2017_01_01_00.tab ``` -------------------------------- ### MPTRAC Compilation and Testing Source: https://github.com/slcs-jsc/mptrac/blob/master/README.md Commands to compile the MPTRAC project after configuration and to run the test suite to verify the installation. ```bash cd [mptrac_directory]/src make [-j] make check ``` -------------------------------- ### Example Wrapper Test Execution Script Source: https://github.com/slcs-jsc/mptrac/blob/master/docs/manual/fortran-wrapper.md An outline of the 'run.sh' script found in 'tests/wrapper_test/'. This script compares the output of the original C 'trac.c' with the Fortran 'trac_fortran.f90' to ensure functional equivalence. ```Shell # Conceptual outline of tests/wrapper_test/run.sh # 1. Compile C code (if not already done) # gcc trac.c -o trac_c # 2. Run original C code # ./trac_c # Store output in data.ref/ # 3. Compile Fortran wrapper # cd ../src # make wrapper # cd ../tests/wrapper_test # 4. Run Fortran code # ../src/trac_fortran # Store output in data/ # 5. Compare outputs # diff -r data/ data.ref/ ``` -------------------------------- ### Calling atm_init Source: https://github.com/slcs-jsc/mptrac/blob/master/docs/manual/apps/atm_init.md Demonstrates how to execute the atm_init application from the command line, specifying control and output file paths. ```bash # calling atm_init $ ./atm_init ``` -------------------------------- ### Hybrid MPI/OpenMP/OpenACC Configuration Example Source: https://github.com/slcs-jsc/mptrac/blob/master/docs/manual/parallelization.md An example scenario illustrating how MPI, OpenMP, and OpenACC can be combined. This setup uses MPI for inter-node parallelism, OpenMP for intra-node CPU parallelism, and OpenACC for GPU acceleration. ```APIDOC Configuration: - MPI: Distribute simulations across N nodes. - OpenMP: Within each node, use M cores per simulation (e.g., 48 cores / 4 simulations = 12 cores/simulation). - OpenACC: Offload compute kernels to GPUs, with one simulation per GPU. Example Scenario: A compute node with 48 cores and 4 GPUs. - Run 4 independent MPI processes (one per GPU). - Each MPI process uses OpenMP to parallelize calculations across 12 CPU cores. - OpenACC directives accelerate the core calculation loops on the assigned GPU. ``` -------------------------------- ### Generate All Plots (plot.sh) Source: https://github.com/slcs-jsc/mptrac/blob/master/projects/python/README.md A shell script that automates the creation of all MPTRAC plots. It handles environment setup and execution of individual plotting scripts. Plots are written to the 'plots' directory. ```shell ./plot.sh ``` -------------------------------- ### Run Fortran Trajectory Calculation Source: https://github.com/slcs-jsc/mptrac/blob/master/docs/manual/fortran-wrapper.md Example command to run the Fortran trajectory calculation program 'trac_fortran'. It requires input files for directories, control parameters, starting points, and meteorological data. ```Shell # calling trac_fortran $ ./trac_fortran ``` -------------------------------- ### Saving and Loading ParaView State Source: https://github.com/slcs-jsc/mptrac/blob/master/projects/paraview/README.md Explains how to save and load the current state of a ParaView visualization to a file, allowing users to preserve their setup and avoid redoing steps. Mentions example state files. ```APIDOC Saving and Loading ParaView State: - Save State: File -> Save State. - Load State: File -> Load State. - Examples: 'example_plane.pvsm' (Cartesian), 'example_sphere.pvsm' (spherical). ``` -------------------------------- ### MPTRAC Example Workflow Snippets Source: https://github.com/slcs-jsc/mptrac/blob/master/docs/manual/high-level-interface.md Code snippets illustrating a typical workflow for using the MPTRAC high-level interface, including memory allocation, model initialization, simulation steps, and memory deallocation. ```c mptrac_alloc(&ctl, &cache, &clim, &met0, &met1, &atm); mptrac_read_ctl(filename, argc, argv, ctl); mptrac_read_clim(ctl, clim); mptrac_read_atm(filename, ctl, atm); mptrac_init(ctl, cache, clim, atm, ntask); mptrac_get_met(ctl, clim, t, &met0, &met1); mptrac_run_timestep(ctl, cache, clim, &met0, &met1, atm, t); mptrac_write_output(dirname, ctl, met0, met1, atm, t); mptrac_free(ctl, cache, clim, met0, met1, atm); ``` -------------------------------- ### Calling tropo_sample Source: https://github.com/slcs-jsc/mptrac/blob/master/docs/manual/apps/tropo_sample.md Demonstrates the command-line usage of the `tropo_sample` tool. It specifies the control file, output file, tropopause data file, the type of tropopause information to extract, and the input atmosphere data file. ```bash # calling tropo_sample $ tropo_sample ``` -------------------------------- ### Install MPTRAC Dependencies on macOS Source: https://github.com/slcs-jsc/mptrac/blob/master/DEPENDENCIES.md Installs essential MPTRAC dependencies using the Homebrew package manager on macOS. ```bash brew install git make gcc gsl netcdf hdf5 zlib ``` -------------------------------- ### Build KPP Chemical Integrator Source: https://github.com/slcs-jsc/mptrac/blob/master/projects/kpp/README.md Automates the generation and compilation of KPP-generated chemical integration code. It takes the directory of the KPP definition files and a GPU compilation switch as arguments. ```bash ./build_KPP.sh <1:GPU on; 0:GPU off> Example: ./build.sh chem 0 ``` -------------------------------- ### met_conv Example Command Source: https://github.com/slcs-jsc/mptrac/blob/master/docs/manual/apps/met_conv.md An example of converting a netcdf meteorological file to zstd format using the met_conv utility. ```bash # An example command line for running met_conv looks like ./met_conv trac.ctl era5_2017_01_08_17.nc 0 era5_2017_01_08_17.zstd 4 ``` -------------------------------- ### Install MPTRAC Dependencies on Ubuntu/Debian Source: https://github.com/slcs-jsc/mptrac/blob/master/DEPENDENCIES.md Installs essential MPTRAC dependencies using the apt-get package manager on Ubuntu or Debian-based systems. ```bash sudo apt-get install git make gcc gfortran libgsl-dev libnetcdf-dev libhdf5-dev zlib1g-dev ``` -------------------------------- ### Install MPTRAC Dependencies on CentOS/RHEL Source: https://github.com/slcs-jsc/mptrac/blob/master/DEPENDENCIES.md Installs essential MPTRAC dependencies using the yum package manager on CentOS or RHEL-based systems. ```bash sudo yum install git make gcc gsl-devel netcdf-devel hdf5-devel zlib-devel ``` -------------------------------- ### MPTRAC Project Documentation and APIs Source: https://github.com/slcs-jsc/mptrac/blob/master/docs/manual/code-development.md References to project documentation including README, user manual, Doxygen manual, and external resources like GitHub Actions, Codacy, Codecov, Zenodo, and JuSER. ```APIDOC README: https://github.com/slcs-jsc/mptrac/blob/master/README.md User Manual: https://slcs-jsc.github.io/mptrac Doxygen Manual: https://slcs-jsc.github.io/mptrac/doxygen GitHub Actions: https://github.com/slcs-jsc/mptrac/actions Codacy: https://app.codacy.com/gh/slcs-jsc/mptrac?utm_source=github.com&utm_medium=referral&utm_content=slcs-jsc/mptrac&utm_campaign=Badge_Grade_Settings Codecov: https://codecov.io/gh/slcs-jsc/mptrac Nightly Builds: https://datapub.fz-juelich.de/slcs/mptrac/nightly_builds ESM Buildbot: https://esm-buildbot.fz-juelich.de Zenodo: https://doi.org/10.5281/zenodo.4400597 JuSER Publication Database: https://juser.fz-juelich.de/ Git Handbook: https://guides.github.com/introduction/git-handbook GitHub Git Cheat Sheet: https://training.github.com/downloads/github-git-cheat-sheet.pdf ``` -------------------------------- ### Install Dependencies Source: https://github.com/slcs-jsc/mptrac/blob/master/projects/meteo/README.md Installs necessary system packages and Python libraries for data retrieval and processing. Also makes shell scripts executable. ```bash sudo apt install wget cdo nco python3-pip pip install cdsapi chmod +x get_*.sh ``` -------------------------------- ### Compile and Test Fortran Wrapper Source: https://github.com/slcs-jsc/mptrac/blob/master/docs/manual/fortran-wrapper.md Commands to compile the Fortran wrapper and execute its tests. Assumes the user is in the 'src' directory. ```Shell $ make wrapper $ make wrapper_test ``` -------------------------------- ### met_zm Example Usage Source: https://github.com/slcs-jsc/mptrac/blob/master/docs/manual/apps/met_zm.md An example demonstrating how to call met_zm to create a global zonal mean with a 10-degree latitude band from ERA5 data. ```bash # Calling met_zm $./met_prof - zm_era5_2017_01_08_17_1_1.tab era5_2017_01_08_17.nc \ ZM_DLAT 10 ``` -------------------------------- ### Calling met_sample Source: https://github.com/slcs-jsc/mptrac/blob/master/docs/manual/apps/met_sample.md Demonstrates how to call the met_sample tool with its required input files. The tool samples meteorological data based on a control file and outputs it to a specified file, using atmospheric input data. ```bash # calling met_sample $ ./met_sample # Calling met_sample $./met_sample sample.ctl new_file.tab volcanoes.tab ``` -------------------------------- ### MPTRAC Command Line Arguments Example Source: https://github.com/slcs-jsc/mptrac/blob/master/docs/manual/control-parameters.md Example of specifying MPTRAC control parameters directly as command-line arguments. These arguments take precedence over values in a control parameter file. ```bash ./atm_init trac.ctl data/atm_init.tab \ INIT_LON0 -72.117 INIT_LON1 -72.117 \ INIT_LAT0 -40.59 INIT_LAT1 -40.59 ``` -------------------------------- ### MPTRAC Prerequisites Source: https://github.com/slcs-jsc/mptrac/blob/master/README.md Lists the essential software and libraries required to build and run the MPTRAC model. Optional dependencies for enhanced features like HPC and GPU support are also mentioned. ```text Required: - Git - GNU Make - GCC - GSL - HDF5 - netCDF Optional (for HPC/GPU): - OpenMPI - NVIDIA HPC SDK ``` -------------------------------- ### met_prof Example with ERA5 Data Source: https://github.com/slcs-jsc/mptrac/blob/master/docs/manual/apps/met_prof.md Provides an example of how to use met_prof to create a 1 km resolution vertical profile from ERA5 data, specifying geographical and altitude ranges. ```bash # Calling met_map $./met_prof - prof_era5_2017_01_08_17_1_1.tab era5_2017_01_08_17.nc PROF_LON0 -180 PROF_LON1 180\ PROF_LAT0 -90 PROF_LAT1 90 PROF_DLON 1 PROF_DLAT 1 PROF_Z0 0 PROF_Z1 25 PROF_DZ 1 ```