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.

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[, validate_vars])	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.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 PIO namelist 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_namelist_pio()	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).
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.
update_permissions(directories, group[, ...])	Fix permissions on the databases where files were downloaded so everyone in the group can read/write to them

job

write_job_script(config, machine, work_dir)
get_slurm_options(config, machine, nodes)	Get Slurm options for job submission.
get_pbs_options(config, machine, nodes)	Get PBS options for job submission.

logging

log_method_call(method, logger)

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

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 a shared step for creating spherical base mesh with the given resolution to the mesh component (if one has not already been added)
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

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

parallel

get_available_parallel_resources(config)
set_cores_per_node(config, cores_per_node)
run_command(args, cpus_per_task, ntasks, ...)
get_parallel_command(args, cpus_per_task, ...)
system.ParallelSystem(config)	Base class for parallel system resource management.
single_node.SingleNodeSystem(config)	Resource manager for single-node parallel execution.
login.LoginSystem(config)	Resource manager for login nodes (no parallel execution).
slurm.SlurmSystem(config)	SLURM resource manager for parallel jobs.
pbs.PbsSystem(config)	PBS resource manager for parallel jobs.

provenance

write(work_dir, tasks[, config])

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(variables, filename1, ...)

compare variables in the two files

viz

use_mplstyle()	Use the Polaris matplotlib style file
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(mesh_filename, da, ...)	Plots a data set as a longitude-latitude map

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