API reference

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

Components

• e3sm/init
• mesh
• ocean
• seaice

polaris framework

Command-line interface

__main__.main()

Entry point for the main script polaris

list

list_cases([task_expr, number, verbose])	List the available tasks
list_machines()
list_suites([components, verbose])

setup

setup_tasks(work_dir[, task_list, numbers, ...])	Set up one or more tasks
setup_task(path, task, machine, work_dir, ...)	Set up one or more tasks

suite

setup_suite(component, suite_name, work_dir, ...)

Set up a suite of tasks

run

unpickle_suite(suite_name)	Unpickle the suite
setup_config(base_work_dir, config_filepath)	Set up the config object from the config file
load_dependencies(step)	Load each dependency from its pickle file to pick up changes that may have happened since it ran
complete_step_run(step)	Write a file to indicate that the step has completed.
serial.run_tasks(suite_name[, quiet, ...])	Run the given suite or task
serial.run_single_step([step_is_subprocess, ...])	Used by the framework to run a step when polaris serial gets called in the step's work directory

cache

update_cache(step_paths[, date_string, dry_run])

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

mpas_to_yaml

main_mpas_to_yaml()

Base Classes

Component

Component(name)	The base class for housing all the tasks for a given component, such as ocean, landice, or seaice
Component.add_task(task)	Add a task to the component
Component.add_step(step)	Add a step to the component
Component.remove_step(step)	Remove the given step from this component
Component.add_config(config)	Add a shared config to the component
Component.get_or_create_shared_step(...[, ...])	Get a shared step from the component if it exists, otherwise create and add it.
Component.set_parallel_system(config)	Construct and store the active parallel system for this component
Component.get_available_resources()	Get available resources from the active parallel system
Component.run_parallel_command(args, ...[, ...])	Run a command using the active parallel system

Task

Task(component, name[, subdir, indir])	The base class for tasks---such as a decomposition, threading or restart test---that are made up of one or more steps
Task.configure()	Modify the configuration options for this task.
Task.add_step([step, subdir, symlink, ...])	Add a step to the task and component (if not already present)
Task.remove_step(step)	Remove the given step from this task and the component
Task.set_shared_config(config[, link])	Replace the task's config parser with the shared config parser

Step

Step(component, name[, subdir, indir, ...])	The base class for a step of a tasks, such as setting up a mesh, creating an initial condition, or running the component 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 task 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 tasks.
Step.add_dependency(step[, name])	Add step as a dependency of this step (i.e. this step can't run until the dependency has finished).
Step.validate_baselines()	Compare variables between output files in this step and in the same step from a baseline run if one was provided.
Step.check_properties()	This method should be overridden to check properties of step outputs
Step.set_shared_config(config[, link])	Replace the step's config parser with the shared config parser

ModelStep

ModelStep(component, name[, subdir, indir, ...])
ModelStep.setup()	Setup the command-line arguments
ModelStep.set_model_resources([ntasks, ...])	Update the resources for the step.
ModelStep.add_model_config_options(options)	Add the replacement model config options to be parsed when generating a namelist or yaml file if and when the step gets set up.
ModelStep.add_yaml_file(package, yaml[, ...])	Add a file with updates to yaml config options to the step to be parsed when generating a complete yaml file if and when the step gets set up.
ModelStep.map_yaml_options(options, config_model)	A mapping between model config options from different models.
ModelStep.map_yaml_configs(configs, config_model)	A mapping between model config options from different models.
ModelStep.map_yaml_to_namelist(options)	A mapping from yaml model config options to namelist options.
ModelStep.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.
ModelStep.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.
ModelStep.dynamic_model_config(at_setup)	Add model config options, namelist, streams and yaml files using config options or template replacements that need to be set both during step setup and at runtime
ModelStep.runtime_setup()	Update IO task model config options, make graph file, and partition graph file (if any of these are requested)
ModelStep.process_inputs_and_outputs()	Process the model as an input, then call the parent class' version
ModelStep.update_io_tasks_config([config_model])	Modify model config options so the number of IO tasks and the stride between them are consistent with how MPI tasks are distributed across nodes (one IO task per node).
ModelStep.partition([graph_file])	Partition the domain for the requested number of tasks

config

PolarisConfigParser([filepath])	A "meta" config parser that keeps a dictionary of config parsers and their sources to combine when needed.
PolarisConfigParser.setup()	A method that can be overridden to add config options during polaris setup

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.

job

write_job_script(config, machine, work_dir)

logging

log_method_call(method, logger)

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

constants

get_constant(name)

Get constants from the Physical Constants Dictionary (PCD) if available, otherwise from the temporary dictionary of constants.

constants.pcd

get_constant(name)	Get a constant from the Physical Constants Dictionary (PCD).
get_pcd_version()	Get the PCD version from Polaris' packaged pcd.yaml.
get_pcd_version_from_file(filename)	Get the PCD version from a pcd.yaml file.
check_pcd_version_matches_branch(branch, model)	Check that the PCD version in Polaris matches the version in a branch.

mesh

planar.compute_planar_hex_nx_ny(lx, ly, ...)	Compute number of grid cells in each direction for the uniform, hexagonal planar mesh with the given physical sizes and resolution.
spherical.SphericalBaseStep(component, 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(component[, ...])	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 task
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(component[, 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 task
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.

Spherical Base Meshes

add_spherical_base_mesh_step(prefix, min_res)	Add one supported spherical base mesh step to a component.
get_base_mesh_steps()	Get a list of supported base mesh steps from the mesh component
rrs.RRSBaseMesh(component[, name, subdir, ...])	A step for creating Rossby Radius Scaled (RRS) variable resolution meshes
rrs.RRSBaseMesh.build_cell_width_lat_lon()	Create cell width array for this mesh on a regular latitude-longitude grid
so.SOBaseMesh(component[, name, subdir, ...])	A step for creating Southern Ocean (SO) regionally refined meshes
so.SOBaseMesh.build_cell_width_lat_lon()	Create cell width array for this mesh on a regular latitude-longitude grid

model_step

make_graph_file(mesh_filename[, ...])

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

build

mpas_ocean.build_mpas_ocean(branch, ...[, ...])	Build MPAS-Ocean on the current machine.
mpas_ocean.make_build_script(machine, ...)	Make a shell script for checking out MPAS-Ocean and its submodules and building MPAS-Ocean.
omega.build_omega(branch, build_dir, clean, ...)	Build Omega on the current machine.
omega.make_build_script(machine, compiler, ...)	Make a shell script for checking out Omega and its submodules and building Omega.

mpas

area_for_field(ds_mesh, field)	Get the appropriate area (on cells, vertices or edges) for the given field
cell_mask_to_edge_mask(ds_mesh, cell_mask)	Convert a cell mask to edge mask using mesh connectivity information
time_index_from_xtime(xtime, dt_target[, ...])	Determine the time index closest to the target time

namelist

parse_replacements(package, namelist)	Parse the replacement namelist options from the given file
ingest(defaults_filename)	Read the defaults file
replace(namelist, replacements)	Replace entries in the namelist using the replacements dict
write(namelist, filename)	Write the namelist out

provenance

write(work_dir, tasks[, config, machine, ...])

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

remap

MappingFileStep(component, name[, subdir, ...])	A step for creating a mapping file between grids
MappingFileStep.run()	Create the mappping file

resolution

resolution_to_string(resolution)	Convert a resolution to a subdirectory name (e.g. '240km', '30m', '0.1cm').
resolution_to_string_and_units(resolution)	Convert a resolution to a string and its units

streams

read(package, streams_filename[, tree, ...])	Parse the given streams file
write(streams, out_filename)	write the streams XML data to the file
update_defaults(new_child, defaults)	Update a stream or its children (sub-stream, var, etc.) starting from the defaults or add it if it's new.
update_tree(tree, new_tree)	Parse the given streams file

validate

compare_variables(component, variables, ...)

compare variables in the two files

viz

determine_time_variable(ds)	Identify the variable prefix and time variable for MPAS datasets
get_projection(name, **kwargs)	Return a Cartopy projection by string name.
get_viz_defaults()	Return the whole dictionary of MPAS variables and default viz properties
plot_horiz_field(ds_mesh, field[, ...])	Plot a horizontal field from a planar domain using x,y coordinates at a single time and depth slice.
plot_global_lat_lon_field(lon, lat, ...[, ...])	Plots a data set as a longitude-latitude map
plot_global_mpas_field(da, out_filename, ...)	Plots a data set as a longitude-latitude map
use_mplstyle()	Use the Polaris matplotlib style file

yaml

PolarisYaml()	A class for reading writing and combining config files in yaml format (e.g. as used in Omega).
PolarisYaml.read(filename[, package, ...])	Add config options from a yaml file
PolarisYaml.update([configs, options, quiet])	Add config options from a dictionary
PolarisYaml.write(filename)	Write config options to a yaml file
mpas_namelist_and_streams_to_yaml(model[, ...])	Add config options from a yaml file
yaml_to_mpas_streams(...)	Add config options from a yaml file