SalishSeaCmd API

This section documents the SalishSeaCast NEMO command processor Application Programming Interface (API). The API provides Python function interfaces to command processor sub-commands for use in other sub-command processor modules, and by other software.

salishsea_cmd.api.combine(run_desc_file)[source]

Run the NEMO rebuild_nemo tool for each set of per-processor results files.

The output of rebuild_nemo for each file set is logged at the INFO level.

Parameters:

run_desc_file (pathlib.Path) – File path/name of the run description YAML file.

salishsea_cmd.api.deflate(filepaths, max_concurrent_jobs)[source]

Deflate variables in each of the netCDF files in filepaths using Lempel-Ziv compression.

Converts files to netCDF-4 format. The deflated file replaces the original file.

Parameters:
  • filepaths (sequence) – Paths/names of files to be deflated.

  • max_concurrent_jobs (int) – Maximum number of concurrent deflation processes allowed.

salishsea_cmd.api.gather(results_dir)[source]

Move all of the files and directories from the present working directory into results_dir.

If results_dir doesn’t exist, create it.

Delete any symbolic links so that the present working directory is empty.

Parameters:

results_dir (pathlib.Path) – Path of the directory into which to store the run results.

salishsea_cmd.api.prepare(run_desc_file, nocheck_init=False)[source]

Prepare a SalishSeaCast NEMO run.

A UUID named temporary run directory is created and symbolic links are created in the directory to the files and directories specifed to run NEMO. The output of hg parents is recorded in the directory for the NEMO-code and NEMO-forcing repos that the symlinks point to. The path to the run directory is returned.

Parameters:
  • run_desc_file (pathlib.Path) – File path/name of the YAML run description file.

  • nocheck_init (boolean) – Suppress initial condition link check the default is to check

Returns:

Path of the temporary run directory

Return type:

pathlib.Path

salishsea_cmd.api.run_description(config_name='SalishSea', run_id=None, walltime=None, mpi_decomposition='8x18', NEMO_code_config=None, XIOS_code=None, forcing_path=None, runs_dir=None, forcing=None, init_conditions=None, namelists=None)[source]

Return a SalishSeaCast NEMO run description dict template.

Value may be passed for the keyword arguments to set the value of the corresponding items. Otherwise, the returned run description dict that must be updated by assignment statements to provide those values.

Note

The value of the ['forcing']['atmospheric'] item is set to /results/forcing/atmospheric/GEM2.5/operational/ which is appropriate for runs on salish, but needs to be changed for runs on WestGrid.

Parameters:
  • config_name (str) – NEMO configuration name to use for the run.

  • run_id (str) – Job identifier that appears in the qstat listing.

  • walltime (str) – Wall-clock time requested for the run.

  • mpi_decomposition (str) – MPI decomposition to use for the run.

  • NEMO_code_config (str) – Absolute path to the CONFIG/ directory where the NEMO configurations are to be found.

  • XIOS_code (str) – Path to the XIOS/ directory where the XIOS executable for the run are to be found. If a relative path is used it will start from the current directory.

  • forcing_path (str) – Path to the NEMO-forcing/ directory where the netCDF files for the grid coordinates, bathymetry, initial conditions, open boundary conditions, etc. are found. If a relative path is used it will start from the current directory.

  • runs_dir (str) – Path to the directory where run directories will be created. If a relative path is used it will start from the current directory.

  • forcing (dict) – Forcing link data structure. The default of None produces “sensible defaults” for NEMO-3.4, but None for NEMO-3.6. See the Run Description File Structure docs for the version of NEMO that you are using for details of the data structure.

  • init_conditions (str) – Name of sub-directory in NEMO-forcing/ where initial conditions files are to be found, or the path to and name of a restart file. If a relative path is used for a restart file it will start from the current directory.

  • namelists (dict) – Namelists data structure. The default of None produces “sensible defaults” for a physics-only run for both NEMO-3.4, annd NEMO-3.6. See the Run Description File Structure docs for the version of NEMO that you are using for details of the data structure.

salishsea_cmd.api.run_in_subprocess(run_id, run_desc, results_dir)[source]

Execute salishsea run in a subprocess.

Parameters:
  • run_id (str) – Job identifier that appears in the qstat listing. A temporary run description YAML file is created with the name run_id_subprocess_run.yaml.

  • run_desc (dict) – Run description data structure that will be written to the temporary YAML file.

  • results_dir (str) – Directory to store results into.