API reference

This page provides an auto-generated summary of the compass API. For more details and examples, refer to the relevant sections in the main part of the documentation.

MPAS Cores

compass framework

Command-line interface


Entry point for the main script compass


list_cases([test_expr, number, verbose])

List the available test cases


list_suites([cores, verbose])


setup_cases([tests, numbers, config_file, ...])

Set up one or more test cases

setup_case(path, test_case, config_file, ...)

Set up one or more test cases


clean_cases([tests, numbers, work_dir, ...])

Set up one or more test cases


setup_suite(mpas_core, suite_name[, ...])

Set up a test suite

clean_suite(mpas_core, suite_name[, work_dir])

Clean up a test suite by removing its test cases and run script


run_suite(suite_name[, quiet])

Run the given test suite

run_test_case([steps_to_run, steps_not_to_run])

Used by the framework to run a test case when compass run gets called in the test case's work directory


Used by the framework to run a step when compass run gets called in the step's work directory


update_cache(step_paths[, date_string, dry_run])

Cache one or more compass output files for use in a cached variant of the test case or step

Base Classes



The base class for housing all the tests for a given MPAS core, such as ocean, landice or sw (shallow water)


Add a test group to the MPAS core


TestGroup(mpas_core, name)

The base class for test groups, which are collections of test cases with a common purpose (e.g.


Add a test case to the test group


TestCase(test_group, name[, subdir])

The base class for test cases---such as a decomposition, threading or restart test---that are made up of one or more steps


Modify the configuration options for this test case.


Run each step of the test case.


Test cases can override this method to perform validation of variables and timers

TestCase.add_step(step[, run_by_default])

Add a step to the test case


Step(test_case, name[, subdir, cores, ...])

The base class for a step of a test cases, such as setting up a mesh, creating an initial condition, or running the MPAS core forward in time.


Set up the test case in the work directory, including downloading any dependencies.


Run the step.

Step.add_input_file([filename, target, ...])

Add an input file to the step (but not necessarily to the MPAS model).


Add the output file that must be produced by this step and may be made available as an input to steps, perhaps in other test cases.


make a link to the model executable and add it to the inputs

Step.add_namelist_file(package, namelist[, ...])

Add a file with updates to namelist options to the step to be parsed when generating a complete namelist file if and when the step gets set up.

Step.add_namelist_options(options[, ...])

Add the namelist replacements to be parsed when generating a namelist file if and when the step gets set up.

Step.update_namelist_at_runtime(options[, ...])

Update an existing namelist file with additional options.


Modify the namelist so the number of PIO tasks and the stride between them consistent with the number of nodes and cores (one PIO task per node).

Step.add_streams_file(package, streams[, ...])

Add a streams file to the step to be parsed when generating a complete streams file if and when the step gets set up.

Step.update_streams_at_runtime(package, ...)

Update the streams files during the run phase of this step using the given template and replacements.



Make a deep copy of config to changes can be made without affecting the original

add_config(config, package, config_file[, ...])

Add the contents of a config file within a package to the current config parser


make sure all paths in the paths, namelists and streams sections are absolute paths

get_source_file(source_path, source, config)

Get an absolute path given a tag name for that path


download(url, dest_path, config[, exceptions])

Download a file from a URL to the given path or path name

symlink(target, link_name[, overwrite])

From https://stackoverflow.com/a/55742015/7728169 Create a symbolic link named link_name pointing to target.


log_method_call(method, logger)

Log the module path and file path of a call to a method, e.g..


run_model(step[, update_pio, ...])

Run the model after determining the number of cores

partition(cores, config, logger[, graph_file])

Partition the domain for the requested number of cores

make_graph_file(mesh_filename[, ...])

Make a graph file from the MPAS mesh for use in the Metis graph partitioning software



Get a list of all collections of tests for MPAS cores



Get the number of total cores and nodes available for running steps


write(work_dir, test_cases[, mpas_core, ...])

Write a file with provenance, such as the git version, conda packages, command, and test cases, to the work directory


compare_variables(test_case, variables, ...)

Compare variables between files in the current test case and/or with the baseline results.

compare_timers(test_case, timers, rundir1[, ...])

Compare variables between files in the current test case and/or with the baseline results.