Skip to content

Commit

Permalink
Update README and documentation.
Browse files Browse the repository at this point in the history
  • Loading branch information
@lars2015
lars2015 committed Jan 17, 2024
1 parent 631e8c9 commit 912253f
Show file tree
Hide file tree
Showing 3 changed files with 50 additions and 50 deletions.
52 changes: 26 additions & 26 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,16 +30,16 @@ Massive-Parallel Trajectory Calculations (MPTRAC) is a Lagrangian particle dispe

### Prerequisites

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

The following software dependencies are mandatory for the compilation of MPTRAC:
The following software dependencies are required to compile MPTRAC:

* the [GNU make](https://www.gnu.org/software/make) build tool
* the C compiler of the [GNU Compiler Collection (GCC)](https://gcc.gnu.org)
* the [GNU Scientific Library (GSL)](https://www.gnu.org/software/gsl) for numerical calculations
* the [netCDF library](http://www.unidata.ucar.edu/software/netcdf) for file-I/O

Optionally, the following software is required to enable further capabilities of MPTRAC:
The following optional software is required to enable additional features of MPTRAC:

* the distributed version control system [Git](https://git-scm.com/) to access the code repository
* the [HDF5 library](https://www.hdfgroup.org/solutions/hdf5) to enable the netCDF4 file format
Expand All @@ -52,92 +52,92 @@ Some of the software is provided along with the MPTRAC repository, please see ne

### Installation

Start by downloading the most recent or any of the earlier [MPTRAC releases on GitHub](https://github.com/slcs-jsc/mptrac/releases). Unzip the release file:
Start by downloading the latest or one of the previous [MPTRAC releases on GitHub](https://github.com/slcs-jsc/mptrac/releases). Unzip the release file:

unzip mptrac-x.y.zip

Alternatively, you can retrieve the most recent development version of the software from the GitHub repository:
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 provided along with MPTRAC can be compiled and installed by running a build script:
Several libraries shipped along with MPTRAC can be compiled and installed by running a build script:

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

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

cd [mptrac_directory]/src
emacs Makefile

In particular, you might want to check:
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 will be linked statically, i.e., they can be copied and used on other machines. However, sometimes static compilations causes issues, 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.
* 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 needs to 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 needs to be enabled. The NVIDIA HPC SDK is required to compile the GPU code. The OpenMP parallelization of MPTRAC is always enabled.
* 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 to compile the code:
Next, try compiling the code:

make [-j]

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

make check

This will run sequentially through a set of tests. The execution of the tests will stop if any of the tests fails. Please inspect the log messages.
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, illustrating how to simulate the dispersion of volcanic ash from the eruption of the Puyehue-Cordón Caulle volcano, Chile, in June 2011.
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 `project` subdirectory can also be used to store the results of your own simulation experiments with MPTRAC.
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

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.
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` graphing tool can be found `examples/plots`. The plots should look similar to the output provided in `examples/plots.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:
<p align="center"><img src="projects/example/plots.ref/atm_2011_06_06_00_00.tab.png" width="45%"/> &emsp; <img src="projects/example/plots.ref/grid_2011_06_06_00_00.tab.png" width="45%"/></p>
<p align="center"><img src="projects/example/plots.ref/atm_2011_06_08_00_00.tab.png" width="45%"/> &emsp; <img src="projects/example/plots.ref/grid_2011_06_08_00_00.tab.png" width="45%"/></p>

## Further information

More detailed information for users of MPTRAC is provided in the [user manual](https://slcs-jsc.github.io/mptrac).

These are the main scientific publications providing information on MPTRAC:
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 site](https://slcs-jsc.github.io/mptrac/references/).
Additional references are collected on the [references web page](https://slcs-jsc.github.io/mptrac/references/).

More detailed information for users of MPTRAC is provided in the [user manual](https://slcs-jsc.github.io/mptrac).

Information for developers of MPTRAC is provided in the [doxygen manual](https://slcs-jsc.github.io/mptrac/doxygen).
Information for developers of MPTRAC can be found in the [doxygen manual](https://slcs-jsc.github.io/mptrac/doxygen).

## Contributing

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

You can submit bug reports or feature requests on the [issue tracker](https://github.com/slcs-jsc/mptrac/issues).

Proposed code modifications can be submitted as [pull requests](https://github.com/slcs-jsc/mptrac/pulls).
Proposed code changes and fixes can be submitted as [pull requests](https://github.com/slcs-jsc/mptrac/pulls).

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

## License

MPTRAC is distributed under the [GNU General Public License v3.0](https://github.com/slcs-jsc/mptrac/blob/master/COPYING).
MPTRAC is distributed under the terms of the [GNU General Public License v3.0](https://github.com/slcs-jsc/mptrac/blob/master/COPYING).

Please see the [citation file](https://github.com/slcs-jsc/mptrac/blob/master/CITATION.cff) for further information on citing the MPTRAC model in scientific publications.
Please see the [citation file](https://github.com/slcs-jsc/mptrac/blob/master/CITATION.cff) for more information about citing the MPTRAC model in scientific publications.

## Contact

Expand Down
46 changes: 23 additions & 23 deletions docs/manual/code-development.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,16 +4,16 @@ Please follow these guidelines when developing new code for MPTRAC.

## Compilation

To remove old binaries, backup files, etc., and to clean the source code directory, use:
To remove old binaries, backup files, etc., and to clean up the source code directory, use:

```
make clean
```

For faster compilation, you can apply parallel compilation with `make`, e.g.:
For faster compilation, you can use parallel compilation with `make`:

```
make -j4
make -j
```

You can compile only a single binary, e.g.:
Expand All @@ -22,75 +22,75 @@ You can compile only a single binary, e.g.:
make trac
```

You can modify the variables of the Makefile at the command line, e.g.:
You can change Makefile variables at the command line:

```
make DEFINES="-DNP=100000" GPU=1 STATIC=0
```

## Testing

Always run all the tests to check the revised code:
Always run all the tests to verify the revised code:

```
make check
```

Please do not execute tests in parallel (option `-j` of `make`), you may overlook failed tests in this case.
Please do not execute tests in parallel (`-j` option of `make`), you might miss seeing failed tests.

You can run only selected tests, e.g.:

```
make trac_test
```

If a test fails, please carefully compare the test results with the reference data. The Linux tool `xxdiff` might be used to compare test data and reference data number by number. The graphing utility `gnuplot` may be used to visualize any differences. The reference data of a test should only be updated if the new test results are considered correct.
If a test fails, please carefully compare the test results with the reference data. The Linux tool `xxdiff` can be used to compare test data and reference data number by number. The graphing utility `gnuplot` can be used to visualize any differences. The reference data of a test should only be updated if the new test results are considered correct.

Use the `indent` tool on Linux to apply the given format style to the source code:
On Linux, use the `indent` tool to apply a selected formatting style to the source code:

```
make indent
```

Only use `indent`, when the code was compiled correctly. You may have to rerun the `indent` command 2-3 times to get proper results.
Only use `indent` if the code has been compiled correctly. You may need to re-run the `indent` command 2-3 times to get proper results.

You can apply static code analysis to automatically identify potential issues with the code:
You can use static code analysis to automatically detect potential problems in the code:

```
make cppcheck
make lizard
```

You can run a coverage analysis to identify the parts of code which are covered by tests:
You can perform a coverage analysis to determine which parts of the code are covered by tests:

```
make COV=1
make coverage
```

If you find parts of the code are not covered in the coverage analysis, please consider adding a new test.
If you find that parts of the code are not covered by the coverage analysis, please consider adding a new test.

After pushing revised code to the GitHub repository, please check the [GitHub Actions page](https://github.com/slcs-jsc/mptrac/actions) to see whether the automatic tests were successfully passed.
After committing revised code to the GitHub repository, please check the [GitHub Actions page](https://github.com/slcs-jsc/mptrac/actions) to see if the automated tests were successfully passed.

Please also check the [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) and [Codecov](https://codecov.io/gh/slcs-jsc/mptrac) websites to see the test results.
Please also check the [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) and [Codecov](https://codecov.io/gh/slcs-jsc/mptrac) websites for test results.

Please check the [nightly build website](https://datapub.fz-juelich.de/slcs/mptrac/nightly_builds) to see whether checks on the Juelich supercomputers were passed.
Please check the [nightly build website](https://datapub.fz-juelich.de/slcs/mptrac/nightly_builds) to see if the tests passed on the Juelich supercomputers, especially for the GPU code. User at the Juelich Supercomputing Centre can also check the test results at the [ESM Buildbot](https://esm-buildbot.fz-juelich.de).

## Documentation

To update the [Doxygen documentation](https://slcs-jsc.github.io/mptrac/) (HTML and pdf files) from the source code:
To update the [Doxygen documentation](https://slcs-jsc.github.io/mptrac/) (HTML and pdf files) from the source code, use:

```
make doc
```

Please update the [GitHub wiki pages](https://github.com/slcs-jsc/mptrac/wiki/) to describe any changes and new code.
Please update the [GitHub wiki pages](https://github.com/slcs-jsc/mptrac/wiki/) to describe all changes and new code.

Please update the [README file](https://github.com/slcs-jsc/mptrac/blob/master/README.md) as needed.

## Installation

To copy the executables from the source directory to the directory `DESTDIR` (default `../bin/`):
To copy the executables from the source directory to the `DESTDIR` directory (default `../bin/`):

```
make install
Expand All @@ -102,15 +102,15 @@ To remove the executables from the installation directory:
make uninstall
```

To create a zip file of the current state of the repository, including the compiled binaries:
To create a zip file of the current state of the repository, including the compiled binaries, run

```
make dist
```

## Releases

A new release of MPTRAC is typically created every six months.
A new release of MPTRAC is usually made every six months.

To create a new release, first define a version tag ("vX.Y") in the local repository:

Expand All @@ -132,13 +132,13 @@ Get a list of short log messages from the previous to the current version of the

Using the log messages, [draft a new release](https://github.com/slcs-jsc/mptrac/releases/new) on GitHub using the newly created tag.

Check the [Zenodo the website](https://doi.org/10.5281/zenodo.4400597) to publish the new release and to receive a DOI.
Check the [Zenodo the website](https://doi.org/10.5281/zenodo.4400597) to publish the new release and to get a DOI.

## Cleaning the git repository

Always test the procedures described below on a fresh copy of the repository!
Always test the following procedures on a fresh copy of the repository!

Files can be removed completely from the git repository by means of `git-filter-repo`: https://github.com/newren/git-filter-repo
Files can be completely removed from the git repository using `git-filter-repo`: https://github.com/newren/git-filter-repo

Analyze the current git repository:

Expand Down
2 changes: 1 addition & 1 deletion src/trac.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2010,7 +2010,7 @@ void module_mixing_help(
cmean[idx] += atm->q[qnt_idx][ip];
count[idx]++;
}
#ifndef __GNUC__
#ifdef __NVCOMPILER
#pragma novector
#endif
{
Expand Down

0 comments on commit 912253f

Please sign in to comment.