Compass

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.

User's guide

• Quick Start for Users
  • compass conda environment
  • Building MPAS components
  • Setting up test cases
  • Running a test case
  • Running with a job script
  • Test Suites
• Test Cases
• Config Files
  • A “user” config file
  • Test-case config files
• Test Suites
• Landice core
  • Test Groups
  • Test suites
  • Land-ice Framework
• Ocean core
  • Test groups
  • Framework
  • Test suites
• Machines
  • config options
  • Slurm job queueing
  • Supported Machines
  • Other Machines
  • MPICH
  • OpenMPI
  • No MPI from conda-forge

Developer's guide

• Quick Start for Developers
  • Unix Shell
  • Set up a compass repository: for beginners
  • compass conda environment, compilers and system modules
  • Creating/updating only the compass environment
  • Building MPAS components
  • Running compass from the repo
  • Code style for compass
  • Set up a compass repository with worktrees: for advanced users
• Overview
  • Code Style
  • Packages and Modules
  • Code sharing
• Command-line interface
  • compass list
  • compass setup
  • compass clean
  • compass suite
  • compass run
  • compass cache
• Organization of Tests
  • Directory structure
  • MPAS Cores
  • Test Groups
  • Test cases
  • Steps
  • Test Suites
• Landice core
  • Test groups
  • Land-ice Framework
• Ocean core
  • Test groups
  • Ocean framework
• Framework
  • list module
  • Config files
  • Logging
  • IO
  • Mesh
  • Model
  • Validation
  • Provenance
• Machines
  • Supported Machines
  • Other Machines
  • Adding a New Supported Machine
• Troubleshooting
  • Solver errors when configuring conda environment
  • Proxy on LANL Macs
  • gethostbyname failed
• Documentation
  • Docstrings
• Building the Documentation
• Deploying a new spack environment
  • Where do we update compass dependencies?
  • Mache
  • Updating spack from compass with mache from a remote branch
  • Testing compass
  • Deploying shared spack environments
• API reference
  • MPAS Cores
  • compass framework
• Design Documents
  • compass python package
  • Caching outputs from compass steps
  • Template

Tutorials

• Developer Tutorial: Adding a new test group
• Developer Tutorial: Adding a new ocean/sea ice regionally refined mesh (RRM)
• Developer Tutorial: Adding a parameter study
• Developer Tutorial: Porting a legacy COMPASS test group

Glossary

• Glossary

Versions

• Code and Documentation Versions

Legacy COMPASS

The legacy version of COMPASS is controlled by 4 scripts (list_testcases.py, setup_testcases.py, clean_testcases.py, and manage_regression_suite.py), 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:

http://mpas-dev.github.io/compass/legacy/

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

https://github.com/MPAS-Dev/compass/tree/legacy