Release notes for MPAS-Atmosphere

MPAS-Atmosphere Version 5.2
1 August 2017

This minor release of MPAS corrects issues when using the PIO 2.x library versions. With the changes in this release, it should be possible to use the latest PIO release from

When compiling MPAS with a PIO 2.x library version, the USE_PIO2=true option should be added to the MPAS build command.

The PIO 2.x library versions support integrated performance timing with the GPTL library; however, the MPAS infrastructure does not currently provide calls to initialize this library before it is used in PIO. Therefore, it is recommended to add -DPIO_ENABLE_TIMING=OFF to the options in the cmake command used to build PIO.

The following steps may be used as a rough guide to obtaining and installing the latest PIO code:

  git clone
  cd ParallelIO
  export PIOSRC=`pwd`
  cd ..
  mkdir build
  cd build
  export CC=mpicc
  export FC=mpif90
  make install
In the above steps, /somewhere/writable/pio2 should be changed to the installation path for PIO, and after successfully installing, the PIO environment variable should be set to this path as well.

MPAS-Atmosphere Version 5.1
12 May 2017
This minor release of MPAS introduces fixes for several issues in the MPAS v5.0 major release of the atmosphere core, including:
  • Re-engineering of the 3-d divergence damping mechanism to improve model stability in some variable-resolution simulations
  • Making the upper gravity-wave absorbing layer scale aware, which is necessary to effectively damp vertically propagating waves in the coarse part of variable-resolution meshes
  • A fix for patches of high 2-m theta sometimes found in simulations with the MYNN surface layer scheme (part of the 'convection_permitting' suite)
  • A new initialization option to extrapolate temperature below the first-guess surface with a lapse rate, needed for usable initialization in some cases
  • A fix for an issue in which writing 'mslp', but not an isobaric temperature field, to an output stream lead to garbage for MSLP field
  • Changes to fix compilation issues on macOS case-insensitive filesystems with GEN_F90=true
  • Changes to properly handle the ECMWF 100-289 cm soil layer
  • A fix for initializing with hybrid-level first-guess data that provides a 3-d 'PRESSURE' field
  • A fix for compiling on BlueGene systems
  • Fixes for various memory issues, mostly related to the expanded use of 'packages' in the v5.0 release
Note that namelist files used with MPAS v5.0 must be modified before they can be used with MPAS v5.1. Specifically, the 'config_smdiv_p_forward' namelist option has been removed, and the default value for 'config_smdiv' has been changed to 0.1.
MPAS-Atmosphere Version 5.0
7 January 2017
This major release of MPAS introduces new capabilities, options, and enhancements to MPAS-Atmosphere, as well as many small improvements in the MPAS framework.

Significant changes to MPAS-Atmosphere include:
  • A new physics suite, 'convection_permitting', that is suitable for applications where convection-permitting meshes (dx < 10 km) are employed, including variable-resolution meshes spanning hydrostatic to nonhydrostatic resolutions
  • Updates to the versions of existing physics schemes
  • A new vertical level distribution (selected by default when running init_atmosphere_model) that has been used in several MPAS-Atmosphere real-time experiments, including the prediction of tropical cyclones
  • The ability to initialize the water vapor mixing ratio directly from specific humidity rather than relative humidity
  • An option to compute sub-grid-scale orography statistics for use by the GWDO scheme directly on the native MPAS mesh from the 30-arc-second topography used for the model terrain field
  • The use of "packages" to save memory by selectively allocating fields based on run-time choices of physics suite or schemes
  • Substantial performance optimizations to the dynamical solver (with contributions from Thomas Henderson (then at NOAA), Robert Sinkovits (SDSC), John Dennis (NCAR), and Ryan Cabell (NCAR))
  • The ability to obtain bit-identical results for any MPI task count (though this may require the addition of compiler flags, e.g., '-fp-model precise' for the ifort compiler)
  • An experimental hybrid-parallel capability to allow execution with MPI and OpenMP; note that this ability does not currently offer a performance advantage and is being released for further development by collaborators
  • Complete documentation for all namelist options and fields in the Registry file; units and description for all fields are also written as variable attributes to all model output files
  • The introduction of a new framework for including diagnostics modules in MPAS-Atmosphere
  • New diagnostics: Ertel PV diagnostics (thanks to Nick Szapiro (OU)), and convective diagnostics including CAPE and CIN
  • The ability to write soundings for a specified list of locations at any specified interval during model integration
  • For data assimilation, an Incremental Analysis Update (IAU) module to reduce initial noise by adding analysis increments over a time window (thanks to Soyoung Ha (NCAR))
Updates and improvements to the MPAS framework include:
  • A simplified method for building single-precision executables: simply add PRECISION=single to the compilation command-line
  • Minor performance improvements, e.g., in halo communication
  • Fixes to allow the infrastructure to correctly handle large meshes (>10^7 cells)
  • OpenMP threading of memory initialization, buffer copying, etc.
  • Minor cleanup and bug fixes throughout
MPAS-Atmosphere Version 4.0
22 May 2015
This major release includes several significant changes to the atmosphere core, and a small number of minor changes to the shared MPAS infrastructure that are visible to users.

Significant changes in the atmosphere core include the following:
  • A new split dynamics-transport integration scheme has been introduced, allowing scalar transport to take place on a longer timestep than the other dynamics. Real-data testing indicates that the new scheme offers greater model stability. This scheme, selected by default, is controlled by the new namelist options config_split_dynamics_transport, which controls whether the new option is used, and config_dynamics_split_steps, which sets number of dynamics sub-cycles in a timestep.
  • The concept of physics suites has been introduced, allowing groups of physics parameterizations that have been tested together to be selected with a single namelist option; this is an alternative to individually specifying parameterization schemes. By default, MPAS-Atmosphere uses the 'mesoscale_reference' suite, described in Section 6.1 of the Users' Guide.
  • Improved support for initializing with model-level datasets, in particular, ERA-Interim model level data.
  • Scale-adaptive coordinate surface smoothing.
Several minor, though notable, changes have also been included in the MPAS software infrastructure:
  • A new optional keyword, io_type, has been implemented in the XML stream configuration files, allowing the file format and library to be selected on a per-stream basis. More details are available in Section 5.2 of the Users' Guide.
  • In the MPAS 3.x releases, fields and global attributes showed up in output files in random order; now, the order of the file contents is based on the order that fields and namelist options were declared in the Registry.xml file of a core.
  • A few minor improvements have been made to enable MPAS-Atmosphere to run more reliably in single-precision and at high-resolution, especially on large MPI task counts.
MPAS-Atmosphere Version 3.3
21 January 2015
This bugfix release corrects an number of issues in the shared MPAS infrastructure:
  • Fix an issue in the timekeeping library when comparing time intervals with different numbers of years or months
  • Fix a memory leak when setting times in the time manager
  • Add improved error messages when attempting to read from non-existent files
  • Correctly catch error conditions produced by open() when opening XML files
  • Fix bug in merging var_struct and var_array elements in Registry.xml files
  • Set the s_d variable within time manager to avoid potential division by zero
  • Remove an extra if-test to handle r0a field destruction in pools
  • Avoid allocating memory for inactive package variables
  • Fix for directory creation for streams when directories are nested within non-writable directories
  • Permit input streams to have the same filename template
  • Update infrastructure bootstrapping process to properly handle stream attributes
  • Fix an issue with interval division when resetting alarms
MPAS-Atmosphere Version 3.2
17 December 2014
This bugfix release only affects MPAS-Ocean.

MPAS-Atmosphere Version 3.1
24 November 2014
This bugfix release corrects an error in the downward extrapolation of RH for model levels that lie below the surface of the initial condition dataset (e.g., GFS). Without this fix, the RH field used to compute the initial water vapor mixing ratio field may contain zero (or possible garbage) values in the lowest model levels.

This bug was only present in v3.0, and not in earlier releases of MPAS-Atmosphere.

MPAS-Atmosphere Version 3.0
18 November 2014
This major release includes only minor changes to the atmosphere core, and more substantial changes to the shared MPAS infrastructure.

Changes to atmosphere-specific code include:
  • Support for soil moisture and soil temperature from ERA-I levels (0-7, 7-28, 28-100, and 100-25 cm);
  • a significant reduction in the print statements written to the log files;
  • a reduction in the set of fields written to the default model history files; and
  • miscellaneous minor bugfixes.
This release of MPAS includes two major changes to the MPAS software infrastructure, the second of which significantly changes the model user interface.
  • As a significant step in preparing the MPAS framework for support of multiple MPAS cores being compiled together in the same executable, the internal storage of fields and namelist options has been rewritten; this change principally affects model developers who need to access fields inside the MPAS code.
  • To enable full run-time control over file input and output, a new I/O layer has been developed for MPAS. In past releases of MPAS, control over input, restart, and history files took place in the namelist file. Now, all configuration of model input, restart, and history files makes use of separate XML configuration files. A new chapter (Chapter 5) has been added to the MPAS-Atmosphere Users' Guide to describe the use of this new I/O system.
New features in the MPAS-Ocean and MPAS-Land Ice cores may be found in the documentation for these cores.

MPAS-Atmosphere Version 2.1
6 June 2014
This bugfix release corrects two issues in MPAS-Atmosphere:
  • The double-precision RRTMG long-wave table, RRTMG_LW_DATA.DBL, was inconsistent with the version of the RRTMG code that was included in MPAS-Atmosphere. The RRTMG_LW_DATA.DBL has been updated in the MPAS-Data repository, and the source code includes changes in the data checkout script to download the latest version of all WRF physics tables from this repository.
  • In two places in the MPAS-Atmosphere solver, the upwinding coefficient for the 3rd-order advection scheme, config_coef_3rd_order, was incorrectly declared as an integer rather than a real. The bug affects the diagnosis of the covariant vertical velocity omega, resulting in the use of a fourth-order diagnosis as opposed to the third-order diagnosis consistent with the horizontal transport.
MPAS-Atmosphere Version 2.0
15 November 2013
The 2.0 release represents a relatively minor increment in functionality for MPAS-Atmosphere. Improvements and new features of MPAS-Atmosphere include:
  • the option to run the RRTMG long-wave and short-wave radiation codes with climatologically varying ozone profiles
  • improved interpolation of surface update fields (sea-surface temperatures and fractional seaice)
  • the ability to run MPAS-A in single-precision. This capability has received very limited testing, and the MPAS-A group would be interested in receiving any feedback based on user experiences with this feature. For information on building and running MPAS-A for single-precision execution, please see this page.
  • other minor corrections to code, including:
    • logic changes to compute simulated radar reflectivity and other diagnostic fields at the proper time in high-frequency diagnostic files
    • fix for the lower bound of a loop in the computation of horizontal advection of w when config_w_adv_order=3 (no impact on results); thanks to Bill Gustafson Jr. and Matus Martini of PNNL
    • turning off the inclusion of moisture by default in the initialization for the Jablonowski and Williamson test case

The MPAS 2.0 release is the first public release to include the MPAS Land-Ice core. For information on MPAS-Land Ice, please see Information about new features in the MPAS-Ocean core can be found in the MPAS-Ocean documentation.

MPAS-Atmosphere Version 1.5
4 September 2013
This release corrects an indexing error in the computation of horizontal mixing for w.
Thanks to Matus Martini for finding this bug.

MPAS-Atmosphere Version 1.4
27 August 2013
This bugfix release introduces corrections to the hydrostatic balancing in MPAS-A real-data initialization to properly account for vertical grid stretching.

MPAS-Atmosphere Version 1.3
23 July 2013
This bugfix release corrects syntax in the Bourne shell script used to check out physics lookup tables at build-time.

MPAS-Atmosphere Version 1.2
23 July 2013
This bugfix release modifies Fortran USE statements to be compatible with older as well as current versions of the pg90 compiler.

MPAS-Atmosphere Version 1.1
15 July 2013
This bugfix release only affects MPAS-Ocean.

MPAS-Atmosphere Version 1.0
14 June 2013
MPAS Version 1.0 was released on 14 June 2013.  This is the first public release of MPAS, including the atmosphere model.  MPAS-A has undergone limited testing for NWP time-scale integrations (days to weeks) and seasonal to year-long integrations for regional climate applications, in addition to idealized testing including dry and moist idealized baroclinic waves, squall-lines, supercells, and mountain-wave simulations in 2D and 3D Cartesian geometries.

Considerations regarding this initial release:
  • We have not tested the model for deep-atmosphere configurations; our model top has typically been set at 30 km in real-data simulations.
  • The current physics suite, taken from the WRF-NRCM configuration with a few additional options, had not been developed for coarse meshes [dx ~ O(100 km)].  We have observed a number of MPAS-A failures related to physics on coarse meshes for long-term integrations with surface updates.
  • We have only used GFS, CFSR, and NNRP data for initialization of full-physics real-world cases. Real case initializations using other data, like ERA-Interim data, are currently being tested.
  • We have only limited post-processing capabilities at present, particularly with respect to visualization.
  • While we have begun testing methods for interpolating the MPAS output to latitude-longitude meshes (which would greatly expand our post-processing capabilities), these packages are not available in this release.  We expect to make them available in the near future.
  • MPAS must be run under MPI because MPAS uses PIO.  We understand that there would be some utility to having a serial build, and this capability may appear in a later release.
  • MPAS does not currently support running MPAS-Atmosphere coupled to MPAS-Ocean.  We anticipate that most coupled-model work using MPAS-A will occur in CESM.  We are, however, open to working with others exploring coupling with other modeling systems.
  • MPAS-A and MPAS-O are standalone models; this release does not contain the CESM configurations for MPAS-A or MPAS-O, both of which are currently under development.
  • Data assimilation using the Data Assimilation Research Testbed (DART) with MPAS-A is under development.  This capability is not available in this release.
We welcome comments, contributions, bug reports, bug fixes, and any other feedback.