SOG Command Processor API

This section documents the SOG command processor Application Programming Interface (API). The API allows software that runs SOG (e.g. SoG-bloomcast) so that SOG commands can be used dirctly, rather than by way of a subprocess.

SOGcommand.api.batch(batchfile, dry_run=False, debug=False)

Run a collection of SOG jobs in batch mode.

Parameters:

• batchfile (str) – Path/filename of the batch job description file to use.
• dry_run (boolean) – Don’t do anything, just report what would be done. Defaults to False.
• debug (boolean) – Show extra information about the building of the job commands and their execution. Defaults to False.

Returns:

Return code from batch run; zero if all runs succeed, otherwise, maximum of return codes from failed jobs.

Return type:

int

SOGcommand.api.read_infile(yaml_infile, edit_files, key)

Return value for specified infile key.

Parameters:

• yaml_infile (str) – Path/name of a SOG YAML infile.
• edit_files (list) – Paths/names of YAML infile snippets to be merged into yaml_infile.
• key (str) – Infile key to return value for. Key must be “fully qualified”; i.e. a dotted name path through the nested YAML mappings, like initial_conditions.init_datetime.

Returns value:

Infile value associated with key

Return type:

str

SOGcommand.api.run(SOG_exec, infile, editfiles=[], outfile='', legacy_infile=False, dry_run=False, nice=19)

Launch SOG with the specified args, and return the run’s subprocess instance.

Parameters:

• SOG_exec (str) – Path/filename of the SOG executable.
• infile (str) – Path/filename of the infile to use.
• editfiles (list) – Path/filename of YAML infile(s) to apply to the infile as edits.
• outfile (str) – Path/filename of the file to receive stdout from the run. Defaults to the path/filename of the infile with .out appended.
• legacy_infile (boolean) – infile is a legacy, Fortran-style infile. Defaults to False.
• dry_run (boolean) – Don’t do anything. Defaults to False.
• nice (int) – Priority to use for the run. Defaults to 19.

Returns:

Process object for the launched SOG run.

Return type:

subprocess.Popen instance