Configuration Of Model for Prediction Across Scales Setups (Compass) is a python package that provides an automated system to set up test cases for Model for Prediction Across Scales (MPAS) components. The development version of Compass will be kept closely synchronized with the E3SM repo and MALI-Dev repo. Release versions will be compatible with specific tags of the MPAS components.

Many compass test cases are idealized, and are used for things like performing convergence tests or regression tests on particular parts of the MPAS code. Many compass test cases, such as those under the global_ocean test group, are “realistic” in the sense that they use data sets from observations to create create global and regional meshes, initial conditions, and boundary conditions.

Compass will be the tool used to create new land-ice and ocean meshes and initial conditions for future versions of E3SM, just as Legacy COMPASS has been used to create meshes and initial conditions for E3SM v1 and v2. We note that Compass does not provide the tools for creating many of the files needed for full E3SM coupling, a process that requires expert help from the E3SM development team.

The compass python package defines the test cases along with the commands to list and set up both test cases and test suites (groups of test cases). Compass currently supports the landice and ocean dynamical cores for MPAS. Nearly all test cases include calls that launch one of these dynamical cores. These runs are configured with namelists and streams files, and one of the benefits of using Compass over attempting to run one of the MPAS components directly is that Compass begins with default values for all namelists and streams, modifying only those options where the default is not appropriate. In this way, compass requires little alteration as the MPAS components themselves evolves and new functionality is added.

Compass makes extensive use of the Jigsaw and Jigsaw-Python tools to make all but the simplest meshes for our test cases and E3SM initial conditions. These tools, without which Compass’ mesh generation capabilities would not be possible, are developed primarily by Darren Engwirda.



The legacy version of COMPASS is controlled by 4 scripts (,,, and, and test cases are defined by a series of XML files with a strict directory structure. Over the years, we have found this structure to be confusing for both new and experienced developers, with serious limitations on flexibility of test case design and code reuse. We do not anticipate any new test cases being added to the legacy version but it will take time for legacy test cases to be ported to the new compass python package. Therefore, the legacy framework and test cases are expected to persist for the medium term.

Documentation for legacy COMPASS can be found at:

the code can be found in the legacy branch on the COMPASS GitHub repo: