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

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, component_name, ...)	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

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

components

get_components()

Get a list of components, which in turn contain lists 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, ...[, suite])
`get_slurm_options`(config, machine, nodes)	Get Slurm options
`clean_up_whitespace`(text)	Clean up whitespace after jinja templating

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.

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)	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
`get_parallel_command`(args, cpus_per_task, ...)	Run a subprocess with the given command-line arguments and resources

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.src_from_mpas`(filename, ...)	Set the source grid from an MPAS mesh file
`MappingFileStep.dst_from_mpas`(filename, ...)	Set the destination grid from an MPAS mesh file
`MappingFileStep.src_from_lon_lat`(filename[, ...])	Set the source grid from a file with a longitude-latitude grid.
`MappingFileStep.dst_from_lon_lat`(filename[, ...])	Set the destination grid from a file with a longitude-latitude grid.
`MappingFileStep.dst_global_lon_lat`(dlon, dlat)	Set the destination grid from a file with a longitude-latitude grid.
`MappingFileStep.src_from_proj`(filename, ...)	Set the source grid from a file with a projection grid.
`MappingFileStep.dst_from_proj`(filename, ...)	Set the destination grid from a file with a projection grid.
`MappingFileStep.dst_from_points`(filename, ...)	Set the destination grid from a file with a collection of points.
`MappingFileStep.get_remapper`()	Get the remapper for this step.
`MappingFileStep.runtime_setup`()	Create a remapper and set the command-line arguments

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