polaris.Step

class polaris.Step(component, name, subdir=None, indir=None, cpus_per_task=1, min_cpus_per_task=1, ntasks=1, min_tasks=1, cores=None, min_cores=None, may_span_nodes=None, openmp_threads=1, memory=None, min_memory=None, cached=False, run_as_subprocess=False, gpus=None, min_gpus=None, gpus_per_task=0, min_gpus_per_task=0)

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. The step is the smallest unit of work in polaris that can be run on its own by a user, though users will typically run full tasks or suites.

Below, the terms “input” and “output” refer to inputs and outputs to the step itself, not necessarily the MPAS model. In fact, the MPAS model itself is often an input to the step.

Variables:

• name (str) – the name of the step

• component (polaris.Component) – The component the step belongs to

• subdir (str) – the subdirectory for the step

• path (str) – the path within the base work directory of the step, made up of component and the step’s subdir

• cpus_per_task (int, optional) – the number of cores per task the step would ideally use. If fewer cores per node are available on the system, the step will run on all available cores as long as this is not below min_cpus_per_task

• min_cpus_per_task (int, optional) – the number of cores per task the step requires. If the system has fewer than this number of cores per node, the step will fail

• ntasks (int, optional) – the number of tasks the step would ideally use. If too few cores are available on the system to accommodate the number of tasks and the number of cores per task, the step will run on fewer tasks as long as as this is not below min_tasks

• min_tasks (int, optional) – the number of tasks the step requires. If the system has too few cores to accommodate the number of tasks and cores per task, the step will fail

• openmp_threads (int) – the number of OpenMP threads to use

• gpus (int) – the number of GPUs the step would ideally use, as a total for the step rather than a count per task. A step uses no GPUs unless it says otherwise, so 0 is the common case

• min_gpus (int) – the number of GPUs the step requires, again as a total

• gpus_per_task (int) –

  the number of GPUs per task the step would ideally use

  Deprecated since version 1.1.0: Use gpus instead. A per-task count does not confine a step to those GPUs when steps run at the same time; a total does

• min_gpus_per_task (int) –

  the number of GPUs per task the step requires

  Deprecated since version 1.1.0: Use min_gpus instead

• cores (int) – the number of cores the step needs in total. A non-MPI step says this directly; an MPI step says ntasks and cpus_per_task instead and this is their product

• min_cores (int) – the number of cores the step needs in order to run at all

• memory (int or None) –

  the amount of memory in MB the step declares it needs, or None if it has not said. This stays None for a step that declares nothing: it is never filled in with the default, because the two are treated differently.

  A declared figure is a ceiling as well as a claim. The launcher will hold a step to a memory figure on machines that enforce, so a step author should declare a peak with margin rather than a typical value.

• memory_budget (int or None) –

  the memory in MB to account for this step: what it declared, or its proportional share of a node if it declared nothing. Resolved when resources are constrained, and None where the machine has not said how much memory a node has.

  Use this for accounting and memory for capping. Only a declared figure may be enforced as a cap – capping a step at the framework’s own rough estimate of it would make every step carry a measured number before it could run, which is the burden the default exists to avoid.

• min_memory (int) – the amount of memory in MB the step needs in order to run at all, the minimum to memory’s target, in the same style as min_tasks and min_cpus_per_task

• may_span_nodes (bool) –

  whether this step’s resources – its cores and its GPUs alike – may be drawn from more than one node. True for an MPI step, whose launcher spreads its ranks; false for a step that runs in one process, which has no way to reach another node.

  This is not the same question as whether a step uses MPI. A single process that hands its work to a distributed pool spans nodes perfectly well, and one that does its work in its own threads cannot; both are “not MPI”. Nothing in Polaris sets this true today beyond the MPI default.

• placement (mache.parallel.ResourcePlacement or None) –

  the part of the allocation this step is confined to – which nodes, which cores on each and how many GPUs – or None to run on the whole allocation, as steps have always done.

  Nothing assigns this yet. Deciding which subset a step should get needs a scheduler, and there is not one: the only caller is the serial path, which assigns no placement.

• input_data (list of dict) – a list of dict used to define input files typically to be downloaded to a database and/or symlinked in the work directory

• inputs (list of str) – a list of absolute paths of input files produced from input_data as part of setting up the step. These input files must all exist at run time or the step will raise an exception

• outputs (list of str) – a list of absolute paths of output files produced by this step (or cached) and available as inputs to other tasks and steps. These files must exist after the task has run or an exception will be raised

• dependencies (dict of polaris.Step) – A dictionary of steps that this step depends on (i.e. it can’t run until they have finished). Dependencies are used when the names of the files produced by the dependency aren’t known at setup (e.g. because they depend on config options or data read in from files). Under other circumstances, it is sufficient to indicate that an output file from another step is an input of this step to establish a dependency.

• has_shared_config (bool) – Whether this step uses a shared config file.

• is_dependency (bool) – Whether this step is the dependency of one or more other steps.

• tasks (dict) – The tasks this step is used in

• config (polaris.config.PolarisConfigParser) – Configuration options for this step, possibly shared with other tasks and steps

• machine_info (mache.MachineInfo) – Information about E3SM supported machines

• config_filename (str) – The filename or symlink within the step where config is written to during setup and read from during run

• work_dir (str) – The step’s work directory, defined during setup as the combination of base_work_dir and path

• base_work_dir (str) – The base work directory

• baseline_dir (str) – Location of the same task within the baseline work directory, for use in comparing variables and timers

• validate_vars (dict of list) – A list of variables for each output file for which a baseline comparison should be performed if a baseline run has been provided. The baseline validation is performed after the step has run.

• properties_to_check (list of dict) – A list of conservation comparisons to perform, each a dictionary with the keys filename (the output file), properties (the list of conservation properties to check), baseline (either 'init' or the time index in the output file to compare against) and time_index_end (the time index in the output file at the end of the comparison)

• property_check_results (list of dict) – The results of the conservation checks performed by check_properties(), each a dictionary with at least the keys description, relative_error, tolerance and passed

• logger (logging.Logger) – A logger for output from the step

• log_filename (str) – At run time, the name of a log file where output/errors from the step are being logged, or None if output is to stdout/stderr

• cached (bool) – Whether to get all of the outputs for the step from the database of cached outputs for this component

• default_cached (bool) – If True, this step will read its outputs from the cache by default when set up by a downstream task. Set to True in the __init__ of expensive step classes (e.g. CombineStep, ComputeCoastlineStep) to indicate that their outputs should be reused across tasks without requiring each caller to opt in. Tasks that require free-running execution should add this step’s subdir to self.free_running_steps in their __init__ rather than modifying this flag.

• run_as_subprocess (bool) – Whether to run this step as a subprocess, rather than just running it directly from the task. It is useful to run a step as a subprocess if there is not a good way to redirect output to a log file (e.g. if the step calls external code that, in turn, calls additional subprocesses).

• args ({list of list of str, None}) – A list of lists of command-line arguments to call in parallel. Each inner list represents a single command. All commands must use the same parallel resources.

__init__(component, name, subdir=None, indir=None, cpus_per_task=1, min_cpus_per_task=1, ntasks=1, min_tasks=1, cores=None, min_cores=None, may_span_nodes=None, openmp_threads=1, memory=None, min_memory=None, cached=False, run_as_subprocess=False, gpus=None, min_gpus=None, gpus_per_task=0, min_gpus_per_task=0)

Create a new task

Parameters:

• component (polaris.Component) – The component the step belongs to

• name (str) – the name of the task

• subdir (str, optional) –

  the subdirectory for the step. If neither this nor indir

  are provided, the directory is the name

• indir (str, optional) – the directory the step is in, to which name will be appended

• cpus_per_task (int, optional) – the number of cores per task the step would ideally use. If fewer cores per node are available on the system, the step will run on all available cores as long as this is not below min_cpus_per_task

• min_cpus_per_task (int, optional) – the number of cores per task the step requires. If the system has fewer than this number of cores per node, the step will fail

• ntasks (int, optional) – the number of tasks the step would ideally use. If too few cores are available on the system to accommodate the number of tasks and the number of cores per task, the step will run on fewer tasks as long as as this is not below min_tasks

• min_tasks (int, optional) – the number of tasks the step requires. If the system has too few cores to accommodate the number of tasks and cores per task, the step will fail

• cores (int, optional) – the number of cores the step needs in total. For a non-MPI step this is the direct way to say it; an MPI step says ntasks and cpus_per_task instead

• min_cores (int, optional) – the number of cores the step needs in order to run at all

• may_span_nodes (bool, optional) – whether the step’s cores and GPUs may be drawn from more than one node. Defaults to whether the step has more than one MPI task

• openmp_threads (int) – the number of OpenMP threads to use

• memory (int, optional) – the amount of memory in MB the step needs. Declaring one makes it a ceiling on machines that enforce, so declare a peak with margin rather than a typical value

• min_memory (int, optional) – the amount of memory in MB the step needs in order to run at all

• gpus (int, optional) – the number of GPUs the step would ideally use, as a total for the step rather than a count per task. A step uses no GPUs unless it says otherwise

• min_gpus (int, optional) – the number of GPUs the step requires, again as a total

• gpus_per_task (int, optional) –

  the number of GPUs per task the step would ideally use

  Deprecated since version 1.1.0: Use gpus instead

• min_gpus_per_task (int, optional) –

  the number of GPUs per task the step requires

  Deprecated since version 1.1.0: Use min_gpus instead

• cached (bool, optional) – Whether to get all of the outputs for the step from the database of cached outputs for this component

• run_as_subprocess (bool) – Whether to run this step as a subprocess, rather than just running it directly from the task. It is useful to run a step as a subprocess if there is not a good way to redirect output to a log file (e.g. if the step calls external code that, in turn, calls additional subprocesses).

Methods

__init__(component, name[, subdir, indir, ...])	Create a new task
add_dependency(step[, name])	Add step as a dependency of this step (i.e. this step can't run until the dependency has finished).
add_input_file([filename, target, database, ...])	Add an input file to the step (but not necessarily to the MPAS model).
add_output_file(filename[, validate_vars, ...])	Add the output file to the step
add_property_check(filename, check_properties)	Add a single conservation comparison for an output file
check_properties()	Check conservation properties of the output files of this step.
constrain_resources(available_resources)	Constrain cpus_per_task and ntasks based on the number of cores available to this step
process_inputs_and_outputs()	Process the inputs to and outputs from a step added with polaris.Step.add_input_file() and polaris.Step.add_output_file().
run()	Run the step.
runtime_setup()	Update attributes of the step at runtime before calling the run() method.
set_resources([cpus_per_task, ...])	Update the resources for the subtask.
set_shared_config(config[, link])	Replace the step's config parser with the shared config parser
setup()	Set up the task in the work directory, including downloading any dependencies.
validate_baselines()	Compare variables between output files in this step and in the same step from a baseline run if one was provided.
work_path(*filenames)	Get the absolute path to a file or directory in the step's work directory

Attributes

cores	the number of cores this step needs, in total
gpus	the number of GPUs this step needs, in total
may_span_nodes	whether this step's cores and GPUs may come from several nodes
min_cores	the number of cores this step needs in order to run at all
min_gpus	the number of GPUs this step requires, in total