spectre.support.Schedule

Functions

schedule(input_file_template, scheduler[, ...])

Schedule executable runs with an input file

scheduler_options(f)

CLI options for the 'schedule' function.
spectre.support.Schedule.schedule(input_file_template: str | Path, scheduler: str | Sequence | None, no_schedule: bool | None = None, executable: str | Path | None = None, run_dir: str | Path | None = None, segments_dir: str | Path | None = None, copy_executable: bool | None = None, job_name: str | None = None, submit_script_template: str | Path | None = None, from_checkpoint: str | Path | Checkpoint | None = None, input_file_name: str | None = None, submit_script_name: str = 'Submit.sh', out_file_name: str = 'spectre.out', context_file_name: str = 'SchedulerContext.yaml', submit: bool | None = None, clean_output: bool = False, force: bool = False, extra_params: dict = {}, **kwargs) → CompletedProcess | None

Schedule executable runs with an input file

Configures the input file, submit script, etc. to the ‘run_dir’, and then invokes the ‘scheduler’ to submit the run (typically “sbatch”). You can also bypass the scheduler and run the executable directly by setting the ‘scheduler’ to ‘None’.

# Selecting the executable

Specify either a path to the executable, or just its name if it’s in the ‘PATH’. If unspecified, the ‘Executable’ listed in the input file metadata is used.

By default, the executable and submit scripts will be copied to the segments directory to support resubmissions (see below). See the ‘copy_executable’ argument docs for details on controlling this behavior.

# Segments and run directories

You can set either the ‘run_dir’ or the ‘segments_dir’ to specify where the executable will run (but not both). If you specify a ‘run_dir’, the executable will run in it directly. If you specify a ‘segments_dir’, a new segment will be created and used as the ‘run_dir’. Segments are named with incrementing integers and continue the run from the previous segment. For example, the following is a typical ‘segments_dir’:

 ```sh # Copy of the executable MyExecutable # Copy of the submit script template (base and machine-specific) SubmitTemplateBase.sh SubmitTemplate.sh # One segment per day Segment_0000/

InputFile.yaml Submit.sh Output.h5 # Occasional checkpoints, and a checkpoint before termination Checkpoints/

Checkpoint_0000/ Checkpoint_0001/…

# Next segment continues from last checkpoint of previous segment Segment_0001/… ```

You can omit the ‘run_dir’ if the current working directory already contains the input file.

# Placeholders

The input file, submit script, ‘run_dir’, ‘segments_dir’, and ‘job_name’ can have placeholders like ‘{{ num_nodes }}’. They must conform to the [Jinja template format](https://jinja.palletsprojects.com/en/3.0.x/templates/). The placeholders are resolved in the following stages. The following parameters are available as placeholders:

  1. ‘job_name’ (if specified):



  • All arguments to this function, including all additional ‘**kwargs’. For example, the additional ‘**kwargs’ can include parameters controlling resolution in the input file.

  • ‘executable_name’: Just the name of the executable (basename of the ‘executable’ path).

  1. ‘run_dir’ and ‘segments_dir’:



  • All parameters from the previous stage.

  • ‘job_name’: Either the resolved ‘job_name’ from the previous stage, or the ‘executable_name’ if unspecified.

  1. Input file & submit script:



  • All parameters from the previous stages.

  • ‘run_dir’: Absolute path to the ‘run_dir’.

  • ‘segments_dir’: Absolute path to the ‘segments_dir’, or ‘None’ if no segments directory is available.

  • ‘input_file’: Relative path to the configured input file (in the ‘run_dir’).

  • ‘out_file’: Absolute path to the log file (in the ‘run_dir’).

  • ‘spectre_cli’: Absolute path to the SpECTRE CLI.

  • Typical additional parameters used in submit scripts are ‘queue’ and ‘time_limit’.

The parameters used to render the submit script are stored in a context file (named ‘context_file_name’) in the ‘run_dir’ to support resubmissions. The context file is used by ‘spectre.support.resubmit’ to schedule the next segment using the same parameters.

# Scheduling multiple runs

You can pass ranges of parameters to the ‘**kwargs’ of this function to schedule multiple runs using the same input file template. For example, you can do an h-convergence test by using a placeholder for the refinement level in your input file:

 `yaml # In the domain creator: InitialRefinement: {{ lev }} `

When a parameter in ‘**kwargs’ is an iterable, the ‘schedule’ function will recurse for every element in the iterable. For example, you can schedule multiple runs for a convergence test like this:

 ```py schedule(

run_dir=”Lev{{ lev }}”, # … lev=range(1, 3))

```

Parameters:

  • input_file_template – Path to an input file. It will be copied to the ‘run_dir’. It can be a Jinja template (see above).

  • scheduler – ‘None’ to run the executable directly, or a scheduler such as “sbatch” to submit the run to a queue.

  • no_schedule – Optional. If ‘True’, override the ‘scheduler’ to ‘None’. Useful to specify on the command line where the ‘scheduler’ defaults to “sbatch” on clusters.

  • executable – Path or name of the executable to run. If unspecified, use the ‘Executable’ set in the input file metadata.

  • run_dir – The directory to which input file, submit script, etc. are copied, and relative to which the executable will run. Can be a Jinja template (see above).

  • segments_dir – The directory in which a new segment is created as the ‘run_dir’. Mutually exclusive with ‘run_dir’. Can be a Jinja template (see above).

  • copy_executable –

    Copy the executable to the run or segments directory. By default (when set to ‘None’):

    • If ‘–run-dir’ / ‘-o’ is set, don’t copy.

    • If ‘–segments-dir’ / ‘-O’ is set, copy to segments directory to support resubmission.

    When set to ‘True’:

    • If ‘–run-dir’ / ‘-o’ is set, copy to the run directory.

    • If ‘–segments-dir’ / ‘-O’ is set, copy to segments directory to support resubmission. Still don’t copy to individual segments.

    When set to ‘False’: Never copy.

  • job_name – Optional. A string describing the job. Can be a Jinja template (see above). (Default: executable name)

  • submit_script_template – Optional. Path to a submit script. It will be copied to the ‘run_dir’ if a ‘scheduler’ is set. Can be a Jinja template (see above). (Default: value of ‘default_submit_script_template’)

  • from_checkpoint – Optional. Path to a checkpoint directory.

  • input_file_name – Optional. Filename of the input file in the ‘run_dir’. (Default: basename of the ‘input_file_template’)

  • submit_script_name – Optional. Filename of the submit script. (Default: “Submit.sh”)

  • out_file_name – Optional. Name of the log file. (Default: “spectre.out”)

  • context_file_name – Optional. Name of the file that stores the context for resubmissions in the run_dir. Used by spectre.support.resubmit. (Default: “SchedulerContext.yaml”)

  • submit – Optional. If ‘True’, automatically submit jobs using the ‘scheduler’. If ‘False’, skip the job submission. If ‘None’, prompt for confirmation before submitting.

  • clean_output – Optional. When ‘True’, use ‘spectre.tools.CleanOutput.clean_output’ to clean up existing output files in the ‘run_dir’ before scheduling the run. (Default: ‘False’)

  • force – Optional. When ‘True’, overwrite input file and submit script in the ‘run_dir’ instead of raising an error when they already exist.

  • extra_params – Optional. Dictionary of extra parameters passed to input file and submit script templates. Parameters can also be passed as keyword arguments to this function instead.

Returns: The ‘subprocess.CompletedProcess’ representing either the process

that scheduled the run, or the process that ran the executable if ‘scheduler’ is ‘None’. Returns ‘None’ if no or multiple runs were scheduled.

spectre.support.Schedule.scheduler_options(f)

CLI options for the ‘schedule’ function.

These options can be reused by other CLI commands that call the ‘schedule’ function.