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_tests(suite_name[, quiet, is_test_case, ...])	Run the given test suite or test case
run_single_step([step_is_subprocess])	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. global ocean, baroclinic channel, Greenland, or EISMINT2).
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()	This method is deprecated.
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, ...])	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.set_resources([cpus_per_task, ...])	Update the resources for the subtask.
Step.constrain_resources(available_resources)	Constrain cpus_per_task and ntasks based on the number of cores available to this step
Step.setup()	Set up the test case in the work directory, including downloading any dependencies.
Step.runtime_setup()	Update attributes of the step at runtime before calling the run() method.
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

CompassConfigParser()

A "meta" config parser that keeps a dictionary of config parsers and their sources to combine when needed.

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.
package_path(package, resource)	A replacement for deprecated importlib.resources.path(): https://github.com/python/importlib_resources/blob/7e9020a1b84726fdc6ba71ee2893119d1ee61e02/importlib_resources/_legacy.py

logging

log_method_call(method, logger)

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

mesh

spherical.SphericalBaseStep(test_case, name, ...)	A base class for steps that create a JIGSAW spherical mesh
spherical.SphericalBaseStep.setup()	Add output files
spherical.SphericalBaseStep.run()	Finish up the step.
spherical.SphericalBaseStep.save_and_plot_cell_width(...)	Save the cell width field on a lon/lat grid to self.cell_width_filename and plot
QuasiUniformSphericalMeshStep(test_case[, ...])	A step for creating a quasi-uniform JIGSAW mesh with a constant approximate cell width.
QuasiUniformSphericalMeshStep.setup()	Add JIGSAW options based on config options
QuasiUniformSphericalMeshStep.run()	Run this step of the test case
QuasiUniformSphericalMeshStep.build_cell_width_lat_lon()	A function for creating cell width array for this mesh on a regular latitude-longitude grid.
QuasiUniformSphericalMeshStep.make_jigsaw_mesh(...)	Build the JIGSAW mesh.
IcosahedralMeshStep(test_case[, name, ...])	A step for creating an icosahedral JIGSAW mesh
IcosahedralMeshStep.setup()	Add JIGSAW options based on config options
IcosahedralMeshStep.run()	Run this step of the test case
IcosahedralMeshStep.make_jigsaw_mesh(...)	Make the JIGSAW mesh.
IcosahedralMeshStep.build_subdivisions_cell_width_lat_lon()	A function for creating cell width array for this mesh on a regular latitude-longitude grid.
IcosahedralMeshStep.get_subdivisions(cell_width)	Find the number of subdivisions of an icosahedron to achieve a resolution as close as possible to cell_width.
IcosahedralMeshStep.get_cell_width(subdivisions)	Get the approximate cell width for an icosahedral mesh given either a number of subdivisions of the icosahedron.

model

run_model(step[, update_pio, ...])	Run the model after determining the number of tasks and threads
partition(ntasks, config, logger[, graph_file])	Partition the domain for the requested number of tasks
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_parallel_resources(config)	Get the number of total cores and nodes available for running steps
set_cores_per_node(config, cores_per_node)	If the system has Slurm, find out the cpus_per_node and set the config option accordingly.
run_command(args, cpus_per_task, ntasks, ...)	Run a subprocess with the given command-line arguments and resources

provenance

write(work_dir, test_cases[, config])

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.