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
results.TaskResult(path, steps_to_run, log, ...)	The outcome of running a task as part of a suite
results.write_suite_results(filename, ...)	Write the machine-readable results of a suite run

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_config(filepath)	Get a shared config from the component if it exists, otherwise build and add it.
Component.configure(config, steps)	Configure the component
Component.has_model()	Whether this component has a model executable, and therefore whether options like the path to that executable apply to it.
Component.build_model(config, machine)	Build the model for this component.
Component.check_model_version(config)	Check that the model this component will run is compatible with this version of polaris.
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([placement])	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.work_path(*filenames)	Get the absolute path to a file or directory in the step's work directory
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 to the step
Step.add_property_check(filename, ...[, ...])	Add a single conservation comparison for an output file
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()	Check conservation properties of the output files of this step.
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

analysis

analysis.manifest

Product(plot, group, gallery, title[, data])	One published product: a plot, the data behind it, and the facets that identify it
Product.to_dict()	Get the product as a dictionary ready to be written to JSON
Product.from_dict(entry)	Build a product from a dictionary read back from JSON
Manifest(step_name)	The products one step made, written beside its outputs so that a collector can find them without knowing how the work was divided into steps
Manifest.add(plot, group, gallery, title[, data])	Describe one product this step has just made
Manifest.write(path)	Write the fragment describing everything this step made
range_key(facets)	Get the zero-padded range of years a product covers, if it covers one
read_fragment(filename)	Read one manifest fragment written by a step

analysis.publish

publish(fragment_filenames, output_path[, ...])	Publish every product the fragments describe into the staging tree
published_basename(product, filename)	Get the name one of a product's files is published under
write_merged_manifest(published, output_path)	Write the merged manifest that defines the published set

analysis.thumbnail

make_thumbnail(plot_filename, thumbnail_filename)	Render the thumbnail for one plot, unless it is already up to date
thumbnail_name(basename[, image_format])	Get the name of the thumbnail for a published file
image_size(filename)	Get the size of an image in pixels

analysis.site

generate_site(published, output_path, ...[, ...])	Generate the static site over the products that have been published
gallery_filename(group, gallery[, key])	Get the name of the page holding one gallery

attrs

set_attrs(da[, long_name, units])

Replace the attributes of da in place with the given metadata.

component_graph

get_components_in_use(tasks)	Get the components referenced by the given tasks: the component of each task, of each step in those tasks and, recursively, of each step dependency.
get_steps_by_component(tasks)	Get the steps in the given tasks and in their dependencies, grouped by the component that owns each step.

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

coriolis

add_coriolis_to_dataset(config, ds_mesh)	Add Coriolis fields to a mesh dataset based on the type option in the [coriolis] config section.
add_beta_plane_coriolis(ds_mesh, f0, beta)	Add beta-plane Coriolis fields to a horizontal mesh dataset.
add_constant_coriolis(ds_mesh, ...)	Add constant Coriolis fields to a horizontal mesh dataset.
add_rotated_sphere_coriolis(ds_mesh, alpha)	Add Coriolis fields for a sphere rotated by angle alpha.
add_spherical_coriolis(ds_mesh[, omega])	Add Coriolis fields for the Earth's rotation axis.
add_zero_coriolis(ds_mesh)	Add zero-valued Coriolis fields to a horizontal mesh dataset.

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

info.is_planar(ds[, default])	Whether an MPAS mesh is planar, based on the on_a_sphere global attribute of ds
info.is_spherical(ds[, default])	Whether an MPAS mesh is on a sphere, based on the on_a_sphere global attribute of ds
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.
connectivity.active_edge_masks(ds_mesh, ...)	Find, for each local edge of each cell, whether the neighboring cell across that edge and across the next and previous edges around the same cell belong to the domain.
connectivity.count_active_edges(ds_mesh, ...)	Count the active edges of each cell.
connectivity.has_active_vertex(ds_mesh, ...)	Find the cells with at least one active vertex, meaning a vertex all of whose surrounding cells are in the domain.
connectivity.transport_link_mask(ds_mesh, ...)	Find the active edges across which a B-grid can move sea ice.
connectivity.connected_to_seeds(ds_mesh, ...)	Find the cells of the domain that are connected to at least one seed cell.
connectivity.seed_mask_from_points(ds_mesh, ...)	Find the cells nearest to a set of seed points.
vector.get_coordinate_matrix(ds[, location])	Get the Cartesian coordinates of the mesh elements at a given location as a single array
vector.compute_edge_normal_vec(ds)	Compute the normal vector for each edge in a mesh
reconstruct.compute_reconstruction_weights(ds)	Compute the weights and stencil indices needed for reconstruction a edge normal vector field at cell or vertex centers
reconstruct.add_reconstruction_weights_to_dataset(ds_mesh)	Add vector-reconstruction stencil and weight fields to a mesh dataset.
reconstruct.tangential_reconstruction(ds, ...)	Reconstruct a tangential vector field from an edge-normal vector field.
reconstruct.cartesian_to_local_geographic(ds, ...)	Convert a vector field from Cartesian coordinates to local geographic coordinates (zonal, meridional, radial) at the reconstruction point.
reconstruct.get_reconstruction_validate_vars([...])	Get the variables in a reconstruction-weights file that should be compared against a baseline
validate.MPAS_MESH_VALIDATE_VARS	Variables in an MPAS mesh file to compare against a baseline.
validate.CELL_WIDTH_VALIDATE_VARS	Variables in a lon/lat cell-width file to compare against a baseline
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.recompute_angle_edge(ds_mesh)
spherical.calc_edge_normal_vector(ds_mesh)
spherical.calc_vector_east_north(x, y, z)	Compute the local east and north vectors at a given point on the sphere
spherical.quality.check_cell_polygon_quality(...)	Check MPAS cell polygons for nearly duplicate or collinear vertices.

Spherical Base Meshes

BASE_MESH_DEFINITIONS	Read-only proxy of a mapping.
BaseMeshDefinition(prefix, min_res[, max_res])	Immutable metadata for one supported simple base mesh.
add_spherical_base_mesh_step(prefix, min_res)	Add one supported spherical base mesh step to a component.
get_base_mesh_definition(mesh_name)	Get metadata for one supported simple base mesh.
get_base_mesh_step_names()	Get the supported simple base-mesh names in registration order.
get_base_mesh_steps()	Get a list of supported base mesh steps from the mesh component
parse_mesh_filepath(mesh_path)
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
so.background.build_southern_ocean_background(...)	Build a Southern Ocean background field on a regular lat-lon grid.

Coastlines and Critical Transects

CONVENTIONS	Built-in immutable sequence.
COASTLINE_VALIDATE_VARS	variables in a coastline file to compare against a baseline
build_coastline_datasets(ds_topo, resolution)	Build coastline datasets from combined topography.
build_coastline_dataset(ds_topo, resolution, ...)	Build a coastline dataset for one coastline convention.
signed_distance_from_ocean_mask(ocean_mask, ...)	Compute the signed distance to the coastline of an ocean mask.
rasterize_critical_transects(...)	Rasterize critical land blockages and passages onto a lat-lon grid.

CRITICAL_LAND_BLOCKAGE_TAG	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
CRITICAL_PASSAGE_TAG	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
CriticalTransects(land_blockages, passages)	Default critical transect collections shared across mesh workflows.
load_default_critical_transects([gf])	Load the default critical transects from geometric_features.

Unified Meshes

UNIFIED_MESH_NAMES	Built-in immutable sequence.
LAT_LON_TARGET_GRID_RESOLUTIONS	Built-in immutable sequence.
RIVER_CONFIG_FILENAME	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
get_unified_mesh_config(mesh_name[, filepath])	Load default, generic workflow and per-mesh unified-mesh configs.
get_unified_mesh_family(config)	Get the unified-mesh family object for a combined mesh config.
get_unified_background_cell_width(config)	Get a representative background ocean cell width from unified config.
get_unified_finest_cell_width(config)	Get the finest configured cell width from unified mesh settings.
UnifiedBaseMeshStep(component[, ...])	A unified spherical mesh step with direct retained-river geometry input.
UnifiedBaseMeshStep.setup()	Link retained-river products in addition to the sizing field.
UnifiedBaseMeshStep.build_cell_width_lat_lon()	Read the cell width, lon, and lat directly from sizing_field.nc.
UnifiedBaseMeshStep.make_jigsaw_mesh(lon, ...)	Build the JIGSAW mesh with river polylines added to the geometry.

UnifiedMeshFamily(*args, **kwargs)
UnifiedMeshFamily.setup_sizing_field_step(step)
UnifiedMeshFamily.build_ocean_background(...)
default.DefaultUnifiedMeshFamily()	The default unified-mesh family for built-in ocean backgrounds.
default.build_ocean_background_from_mode(...)	Build a 2D ocean-background field in km from the default family modes.
so_region.SORegionUnifiedMeshFamily()	The Southern Ocean unified-mesh family.

build_effective_ocean_mask(...[, ...])	Build the effective ocean mask by emulating the MPAS cull.
block_average(field, factor)	Block-average a 2D field by an integer factor in both dimensions.
variable_box_average(frac, lat, resolution, ...)	Box-average a fraction over a local window of width_km, emulating the conservative area fraction on mesh-scale cells.
widen_passages(passages, lat, lon, ...[, ...])	Dilate rasterized passage lines to a swath proportional to the local ocean background cell width.
flood_fill_from_seeds(mask, lat, lon, ...)	Keep the connected components of a mask that contain seed points.
hysteresis_grow(filled, frac, grow_threshold)	Grow a flood-filled ocean mask into connected regions whose fraction is at least grow_threshold.

distance.haversine_distance(lon_a, lat_a, ...)	Compute great-circle distance in meters.
geojson.read_geojson(filename)	Read a GeoJSON file into a dictionary.
geojson.write_geojson(feature_collection, ...)	Write a GeoJSON feature collection.

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.
source_record.read_source_record(build_dir)	Read the record of the source that Polaris built a model from.

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

parallel

set_parallel_systems(tasks, config)	Set the active parallel system on every component referenced by the task and step graph.
check_mache_supports_placement()	Check that the installed mache can confine a launch to part of an allocation.

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.
get_summary([config])	Get a short provenance of the Polaris that is running

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
merge_diff_summary(overall, new)	Merge one diff summary into another in place, keeping the largest l_infinity difference found for each variable

viz

add_fitted_suptitle(fig, title[, y, ...])	Add a title to a figure, sized so that it fits across the figure
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
mplstyle_context([dpi])	A context manager that applies the Polaris matplotlib style for the duration of a plot and restores the previous settings afterwards
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

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