MAM Code Structure

MAM code is being developed to demonstrate the possibility of applying a common interface for aerosol packages that host models can use to maintan the state of an aerosol system, retrieve aerosol properties required by other model components, and advance the aerosol state during a simulation.

It is also being developed to apply contemporary best practice for design and testing. This document lays out the science requirements and design principles for MAM, provides an overview of the refactored codebase, and describes in more detail specific parts of the code where object-oriented design patterns have been applied to components of the MAM codebase.

Software Requirements

Aerosol–Radiation Interface

• Permit radiation schemes to use whatever wavelength grid they want and not have to be aware of the native wavelength grid of the aerosol package
• Perform expensive setup for optical property calculations during initialization (reading files, setting up interpolations, etc.)
• Remove assumptions of the way aerosols are represented from the radiation code (mode number, size, shape, sectional schemes, etc.)
• Allow radiation schemes interested in optical properties to maintain their own wavelength grids (i.e., not have aerosol packages maintain grids for every scheme that needs aerosol optical properties)

Design Principles

MAM is being developed according to the recommendations for MUSICA contributors and following the MUSICA style guide. Here we outline some specific design principles from these guides that are particularly relevant to the MAM code structure, and briefly describe how they are acheived.

• An aerosol package shoud compile as a library with a clearly defined application programming interface (API).
  • The MAM GitHub repository includes CMake configurations that allow a user to build the MAM library. Interactions with MAM primarily occur through instances of the mam_core::core_t class. Documentation for the mam_core::core_t class acts as the MAM API. Integration tests included in the repository can be used as examples of how to use the MAM API.
• An aerosol package should be comprised of functions that are of limited, clearly defined scope and purpose for readability and testability.
  • Functions are almost all less than 40 lines long. Functions are designed to do one specific task, with clear documentation. Function arguments are clearly defined with units.
• An aerosol package should employ automated testing with a combination of integration and unit tests, with a goal of 100% code coverage by unit tests.
  • The MAM library, along with the aerosol and musica-core libraries it links to, use CMake with CTest to maintain the suite of tests. GitHub Actions automates testing, document generation, and code coverage assessment using gcov. CodeCov.io is used to visualize the coverage reports.
• An aerosol package should employ data and implementation hiding to the extent possible to facilitate the interoperability of aerosol packages with distinct parameterizations and ways of representing aerosol systems.
  • The MAM code base is object-oriented with almost entirely private class data members. Aerosol information and functionality are exposed through type-bound procedures of each class.

Codebase Overview

Library Structure

The MAM software packages comprises three libraries, each of which provides specific functionality required to simulate the modal aerosol system.

• musica-core: The musica-core library includes a set of classes that perform general, reusable tasks and are applicable to a variety of MUSICA software components, including MAM. Some musica-core classes used by MAM are string_t, config_t, io_t, grid_t, and interpolator_t. These are described in more detail below and in the musica-core documentation
• aerosol-interface: The aerosol-interface library defines the common aerosol API used for MUSICA aerosol packages including MAM. The aerosol-interface library also includes some classes for general use by aerosol packages that expose the API. These include the wavelength_grid_t, optics_t, and environmental_state_t classes.
• mam: The mam library provides the core functionality needed to simulate the modal aerosol system exposed through the common aerosol API. The primary interactions through instances of the mam_core::core_t class, which manages MAM aerosol configuration, and instances of the mam_core::state_t class, which maintains the state of a MAM aerosol.

Object Structure

The MAM class diagram including classes from the aerosol-interface and musica-core libraries is shown below

The boxes of various color indicate general functionality provided by sets of related classes.

Things to note in the class structure:

• both the whole MAM aerosol and individual modes extend the aerosol API. This would allow a radiation or other package work with the full set of modes or a single mode interchangeably, similar to the effect of applying the Composite Pattern.
• Interpolators apply the Strategy Pattern, whereby you can specify how you want an interpolation to be calculated when you create an interpolator_t object. See here for an example of how to use interpolator_t objects.
• Reusable components, like interpolator_t, lookup_axis_t, lookup_2D_axis_t, and grid_t, are included in the musica-core library and can be extended if needed for specific applications, as in the case of wavelength_grid_t.
• Class data members are private.
• Class, variable, and function names are meaningful and include units where applicable

Workflow

The over workflow for MAM interactions with radiaion are show below.

Initialization

Run-Time

Testing

Tests are stored in the test/ folder with integration tests in test/integration/ and unit tests in test/unit/. There are currently two integration tests:

• current_cam: This test was extracted from the CAM code base and used to test against during development of the refactored MAM–RRTMG interactions.
• radiation: This test serves as an example of how an arbitrary radiation package can interact with MAM. The results of the optical property calculations are not evaluated.

The unit tests are organized into files of the same name as those in src/ with additional mock classes and configuration files.