WaveWatch III® Run Description File

Example Run Description YAML File

# wwatch3 command processor run description file example
#
# Please see
#   http://wwatch3-cmd.readthedocs.org/en/latest/run_description_file/yaml_file.html
# for detailed documentation.


# The run id value appears in the list of jobs displayed by the squeue command
run_id: SoGwaves
# Email address to send job begin, end, and abort notifications to
email: you@example.com
# Account name to charge resources used by the job to
account: def-allen



paths:
  # Directory in which to create temporary run directories
  # Typically NOT inside a version control repository
  runs directory: $SCRATCH/MIDOSS/wwatch3-runs/


grid:
  # Path of the mod_def.ww3 file generated by ww3_grid during the wwatch3
  # installation process
  mod_def.ww3 file: $PROJECT/$USER/MIDOSS/wwatch3-runs/mod_def.ww3


forcing:
  # Directories containing the daily current and wind forcing files
  # generated by the SalishSeaNowcast make_ww3_current_file and
  # make_ww3_wind_file workers.
  #
  # /scratch/dlatorne/MIDOSS/forcing/wwatch3/ is the shared forcing files
  # storage tree for the MIDOSS project on cedar and graham
  current: /scratch/dlatorne/MIDOSS/forcing/wwatch3/current/
  wind: /scratch/dlatorne/MIDOSS/forcing/wwatch3/wind/


# **OPTIONAL**
restart:
  # Path of the restart file to be used to initialize the wave fields for the run
  restart.ww3: /scratch/dlatorne/MIDOSS/forcing/wwatch3/01jan15/restart001.ww3

Basic Run Configuration

The following key-value pairs provide the basic configuration for the run:

run_id

The job identifier that appears in the temporary run directory name and the squeue command output.

email

The email address at which you want to receive notification of the beginning and end of execution of the run, as well as notification of abnormal abort messages. You can include multiple email addresses by separating them with commas.

account

The account name to include in the #SBATCH directives section of the SoGWW3.sh job script. This key-value pair is required on systems like cedar.computecanada.ca and graham.computecanada.ca that use the Slurm Workload Manager and that you submit runs to with the sbatch command.

Here is an example of the basic run configuration keys and values:

run_id: SoGwaves
email: you@example.com
account: def-allen

paths Section

The paths section of the run description file is a collection of directory paths that wwatch3 uses to find directory paths that it needs.

Here is an example paths section:

paths:
  runs directory: $SCRATCH/MIDOSS/wwatch3-runs/
runs directory

The path to the directory where temporary run directories will be created by the wwatch3 run (or wwatch3 prepare) sub-command.

This path may be relative or absolute, but an absolute path is strongly recommended. It may contain:

  • $SCRATCH as an alternative spelling of the user’s scratch directory on cedar

  • $PROJECT as an alternative spelling of the group’s project directory on cedar

  • $USER as an alternative spelling of the user’s userid

  • ~ or $HOME as alternative spellings of the user’s home directory

An error will be raised if runs directory key is missing, or if the path given does not exist.

grid Section

The grid section of the run description file provides the path of the mod_def.ww3 file generated by ww3_grid during the WaveWatch III® installation process:

Here is an example grid section:

grid:
  mod_def.ww3 file: $PROJECT/$USER/MIDOSS/wwatch3-runs/mod_def.ww3

The path may be relative or absolute. It may contain:

  • $SCRATCH as an alternative spelling of the user’s scratch directory on cedar

  • $PROJECT as an alternative spelling of the group’s project directory on cedar

  • $USER as an alternative spelling of the user’s userid

  • ~ or $HOME as alternative spellings of the user’s home directory

An error will be raised if the mod_def.ww3 key is missing, or if the file does not exist at the location given.

forcing Section

The forcing section of the run description file is a collection of directory paths that wwatch3 uses to find directory paths that it needs.

Here is an example forcing section:

forcing:
  current: /scratch/dlatorne/MIDOSS/forcing/wwatch3/current/
  wind: /scratch/dlatorne/MIDOSS/forcing/wwatch3/wind/
current

The path to the directory where surface current forcing files generated by the make_ww3_current_file are stored.

wind

The path to the directory where wind forcing files generated by the make_ww3_wind_file are stored.

The paths may be relative or absolute, byt absolute paths are strongly recommended. They may contain:

  • $SCRATCH as an alternative spelling of the user’s scratch directory on cedar

  • $PROJECT as an alternative spelling of the group’s project directory on cedar

  • $USER as an alternative spelling of the user’s userid

  • ~ or $HOME as alternative spellings of the user’s home directory

If relative paths are given, they are appended to the directory containing the run description file.

Errors will be raised if either the current or wind keys are missing, or if the paths given do not exist.

restart Section

The optional restart section of the run description file contain a key-value pair that the provide path and file name of the restart file to be used to initialize the run.

Here is an example restart section:

restart:
  restart.ww3: /scratch/dlatorne/MIDOSS/forcing/wwatch3/01jan15/restart001.ww3

The path may be relative or absolute, but an absolute path is strongly recommended. It may contain:

  • $SCRATCH as an alternative spelling of the user’s scratch directory on cedar

  • $PROJECT as an alternative spelling of the group’s project directory on cedar

  • $USER as an alternative spelling of the user’s userid

  • ~ or $HOME as alternative spellings of the user’s home directory

If a relative path is given, it is appended to the directory containing the run description file.

The restart.ww3 key is the name that is used for the symbolic link that is created to the restart file path/name. It is

WaveWatch III or requires that the name of the model restart file be restart.ww3, so that is the key that you must use. A symbolic link called restart.ww3 is created to the value in the temporary run directory.

The restart section is optional. If no restart file is provided WaveWatch III® initializes itself with a quiescent wave field.