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

• landice
• ocean

compass framework

Command-line interface

__main__.main()

Entry point for the main script compass

list

list_cases([test_expr, number, verbose])	List the available test cases
list_machines()
list_suites([cores, verbose])

setup

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

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

Set up one or more test cases

suite

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

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
run_step()	Used by the framework to run a step when compass run gets called in the step's work directory

cache

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

mpas_core

MpasCore(name)	The base class for housing all the tests for a given MPAS core, such as ocean, landice or sw (shallow water)
MpasCore.add_test_group(test_group)	Add a test group to the MPAS core

testgroup

TestGroup(mpas_core, name)	The base class for test groups, which are collections of test cases with a common purpose (e.g.
TestGroup.add_test_case(test_case)	Add a test case to the test group

testcase

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
TestCase.configure()	Modify the configuration options for this test case.
TestCase.run()	Run each step of the test case.
TestCase.validate()	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

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.
Step.setup()	Set up the test case in the work directory, including downloading any dependencies.
Step.run()	Run the step.
Step.add_input_file([filename, target, ...])	Add an input file to the step (but not necessarily to the MPAS model).
Step.add_output_file(filename)	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.
Step.add_model_as_input()	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.
Step.update_namelist_pio([out_name])	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.

config

duplicate_config(config)	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
ensure_absolute_paths(config)	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

io

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.

logging

log_method_call(method, logger)

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

model

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

mpas_cores

get_mpas_cores()

Get a list of all collections of tests for MPAS cores

parallel

get_available_cores_and_nodes(config)

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

provenance

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

validate

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.