/mam4xx

A C++ implementation of MAM4

Primary LanguageC++OtherNOASSERTION

MAM4xx

Build Status Code Coverage

This repository contains the source code for a performance-portable C++ implementation of the MAM4 modal aerosol model (with 4 fixed modes).

Required Software

To build MAM4xx, you need:

  • CMake v3.17+
  • GNU Make
  • reliable C and C++ compilers
  • optionally, a working MPI installation (like OpenMPI or Mpich), if you want to use MAM4xx in a multi-node parallel environment
  • the HAERO aerosol package interface, which provides necessary libraries and settings.

You can obtain all of these freely on the Linux and Mac platforms. On Linux, just use your favorite package manager. On a Mac, you can get the Clang C/C++ compiler by installing XCode, and then use a package manager like Homebrew or MacPorts to get the rest.

For example, to download the relevant software on your Mac using Homebrew, type

brew install cmake openmpi

Building MAM4xx

Installing HAERO

Before you get started with MAM4xx, you'll need a working installation of the HAERO high-performance aerosol interface library. For your convenience, we have provided the build-haero.sh script, which can be used to quickly and easily install HAERO in a desired configuration. The script allows you to set a number of parameters. Check out the comments at the top of build-haero.sh.

You can build a CPU-capable version of HAERO with some defaults set by typing

./build-haero.sh <path>

where <path> is a directory to which HAERO will be installed. If you'd rather install HAERO yourself, you can follow the instructions in the HAERO repository. Make sure you run all the steps, including make install.

If you're on a machine that requires modules to get access to compilers, etc, use

source build-haero.sh <path>

to make sure your environment is updated.

Initializing submodules

Before you start working with the repo, make sure you initialize its submodules:

git submodule update --init --recursive

Configuring and Building MAM4xx

To build MAM4xx:

  1. Create a build directory by running the setup script from the top-level source directory: 
    ./setup build
  2. Change to your build directory and edit the config.sh file to select configuration options. Then run ./config.sh to configure the model. MAM4xx gets most of its configuration information from HAERO, so there aren't many options here.
  3. From the build directory, type make -j to build the library. (If you're building MAM4xx for GPUs, place a number after the -j flag, as in make -j 8).
  4. To run tests for the library (and the driver, if configured), type make test.
  5. To install the model to the location indicated by PREFIX in your config.sh script, type make install. By default, products are installed in include, lib, bin, and share subdirectories within your build directory.

Making code changes and rebuilding

This project uses build trees that are separate from source trees. This is standard practice in CMake-based build systems, and it allows you to build several different configurations without leaving generated and compiled files all over your source directory. However, you might have to change the way you work in order to be productive in this kind of environment.

When you make a code change, make sure you build from the build directory that you created in step 1 above:

cd /path/to/mam4xx/build
make -j

You can also run tests from this build directory with make test.

This is very different from how some people like to work. One method of making this easier is to use an editor in a dedicated window, and have another window open with a terminal, sitting in your build directory.

The build directory has a structure that mirrors the source directory, and you can type make in any one of its subdirectories to do partial builds. In practice, though, it's safest to always build from the top of the build tree.

Checking C++ formatting, and auto-formatting

Our C++ style rules are described in the MAM4xx developer guide. We enforce them using clang-format. If you have the correct version of clang-format installed, you can use the following targets to check and fix all C++ code in the src subdirectory:

  • make format-cxx-check: checks C++ formatting in all source files and reports any non-conforming code
  • make format-cxx: applies C++ formatting rules to all source files, editing them in place. Try to do this in a separate commit from your other work.

You can run either of these targets from your build directory. If you have a different version of clang-format than the one we support, you'll get an error message telling you the correct version to install when you use either of these targets.

Analyzing code coverage

You can get a code coverage report if you've enabled mam4xx to build with code coverage instrumentation. This option is configurable in your config.sh script if you uncomment the COVERAGE=ON line, or if you run CMake directly with the -DENABLE_COVERAGE=ON flag. You must have the LCOV tool installed to generate reports.

To generate a code coverage report:

  1. Build mam4xx with make -j
  2. Run the unit tests and validation tests with make test
  3. Generate the coverage report with make coverage

You will see a file named coverage.info in your build directory. This can be used with LCOV to visualize source files and functions that do and don't have coverage.

Our automated testing system generates code coverage reports and uploads them to codecov.io so they appear in the message feed for relevant pull requests.

Continuous Integration

See the PNNL CI REAMDE for more detailed information.

There is a GitLab instance at PNNL that is configured as a push mirror, where new merge requests commits update the mirror in a GitHub action. This action also triggers a pipeline in PNNL GitLab. This pipeline eventually posts the status to GitHub through the relevent API.

If CI is failing, you might require CI to re-build HAERO in order to get changes there into the CI pipelines. Since CI pipelines all share the same HAERO build, make sure that you do not attempt to re-build on top of another developer.

In order to rebuild HAERO in PNNL CI, either:

  • Add [haero-rebuild] or [rebuild-haero] somewhere into your commit message when pushing to a PR
  • Log onto the PNNL GitLab, and manually trigger the pipeline yourself.

Pushing with the commit message [haero-rebuild] or [rebuild-haero] will build HAERO and run tests, however if you trigger the rebuild manually, you may have to re-run the pipeline again as tests may have already completed.

Generating Documentation

Documentation for MAM4xx can be built using mkdocs. In order to build and view the documentation, you must download mkdocs and its Material theme:

pip3 install mkdocs mkdocs-material

Then, run mkdocs serve from the root directory of your MAM4xx repo, and point your browser to http://localhost:8000.

You can also view the MAM4xx developer guide on GitHub.