MIDOSS-MOHID Run Description File

Example Run Description YAML File

Example (from MIDOSS-MOHID-config/examples/mohid.yaml):

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


# The run id value appears in the list of jobs display by the squeue command
run_id: MarathassaConstTS
# Email address to send job notifications to
# If missing, email address is set to ${USER}@eoas.ubc.ca
email: you@example.com
# Account name to charge resources used by the job to
# If missing, account defaults to rrg-allen
account: def-allen
# Maximum run time requested/allowed for job
# Too low and your job will be terminated before it finishes
# Too high and you will have to wait longer on the queue for your job to start
# You have to experiment to find the "just right" value
walltime: 1:30:00

paths:
  # Absolute path to MIDOSS-MOHID-CODE repository clone.
  # You can use $SCRATCH, $PROJECT, $USER, ~, $HOME in the path, if you wish.
  mohid repo: $PROJECT/$USER/MIDOSS/MIDOSS-MOHID-CODE/
  # Directory in which to create temporary run directories
  # Typically NOT inside a version control repository
  runs directory: $SCRATCH/MIDOSS/runs/

forcing:
  # The keys below are the names of symlinks that will be created.
  # The associated values are the targets of those symlinks;
  # e.g. a symlink named winds.hdf5 will be created to
  # $PROJECT/MIDOSS/MIDOSS/forcing/HRDPS/atmosphere_20150408_20150414.hdf5
  #
  # The keys are file names that you use as "FILENAME" values in your
  # .dat files.
  #
  # You only need to include keys that are used in the .dat files for
  # your run.
  winds.hdf5: $PROJECT/MIDOSS/forcing/HRDPS/atmosphere_20150408_20150414.hdf5
  currents.hdf5: $PROJECT/MIDOSS/forcing/SalishSeaCast/hydrodynamics_20150408_20150414.hdf5
  water_levels.hdf5: $PROJECT/MIDOSS/forcing/SalishSeaCast/hydrodynamics_20150408_20150414.hdf5

# Path and file name of the bathymetry
# You can use $SCRATCH, $PROJECT, $USER, ~, $HOME in the path, if you wish.
bathymetry: $PROJECT/$USER/MIDOSS/MIDOSS-MOHID-config/SalishSeaCast/SalishSeaCast_bathymetry.dat

run data files:
  # Keywords and run data file paths to insert into the nomfich.dat file
  IN_MODEL: $PROJECT/$USER/MIDOSS/MIDOSS-MOHID-config/MarathassaConstTS/Model.dat
  PARTIC_DATA: $PROJECT/$USER/MIDOSS/MIDOSS-MOHID-config/MarathassaConstTS/Lagrangian.dat
  DOMAIN: $PROJECT/$USER/MIDOSS/MIDOSS-MOHID-config/SalishSeaCast/Geometry.dat
  SURF_DAT: $PROJECT/$USER/MIDOSS/MIDOSS-MOHID-config/SalishSeaCast/Atmosphere.dat
  DOMAIN: $PROJECT/$USER/MIDOSS/MIDOSS-MOHID-config/SalishSeaCast/Geometry.dat
  IN_DAD3D: $PROJECT/$USER/MIDOSS/MIDOSS-MOHID-config/SalishSeaCast/Hydrodynamic.dat
  BOT_DAT: $PROJECT/$USER/MIDOSS/MIDOSS-MOHID-config/SalishSeaCast/InterfaceSedimentWater.dat
  AIRW_DAT: $PROJECT/$USER/MIDOSS/MIDOSS-MOHID-config/SalishSeaCast/InterfaceWaterAir.dat
  IN_TIDES: $PROJECT/$USER/MIDOSS/MIDOSS-MOHID-config/SalishSeaCast/Tide.dat
  IN_TURB: $PROJECT/$USER/MIDOSS/MIDOSS-MOHID-config/SalishSeaCast/Turbulence.dat
  DISPQUAL: $PROJECT/$USER/MIDOSS/MIDOSS-MOHID-config/SalishSeaCast/WaterProperties.dat
  WAVES_DAT: $PROJECT/$USER/MIDOSS/MIDOSS-MOHID-config/SalishSeaCast/Waves.dat

vcs revisions:
  git:
    # Absolute paths to Git repos that you want revision records of
    # in your run results.
    # The MIDOSS-MOHID-CODE repo (from `paths: mohid repo:` above)
    # will be included automatically, so don't include it in this list.
    # You can use $SCRATCH, $PROJECT, $USER, ~, $HOME in the path, if you wish.
    - $PROJECT/$USER/MIDOSS/Make-MIDOSS-Forcing
    - $PROJECT/$USER/MIDOSS/MIDOSS-MOHID-config
    - $PROJECT/$USER/MIDOSS/MIDOSS-MOHID-grid
    - $PROJECT/$USER/MIDOSS/moad_tools
    - $PROJECT/$USER/MIDOSS/MOHID-Cmd
    - $PROJECT/$USER/MIDOSS/NEMO-Cmd

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. The email key is only required if the address is different than would be constructed by combining your user id on cedar with @eoas.ubc.ca.
account: The account name to include in the #SBATCH directives section of the MOHID.sh job script.
walltime: The wall-clock time requested for the run. It limits the time that the job will run for, and it also affects queue priority. It is important to allow some buffer time when calculating your walltime limits to allow for indeterminacy of the MOHID run and the file system operations. Too low a value and your job will be terminated before it finishes. Too high and you will have to wait longer on the queue for your job to start. You have to experiment to find the “just right” value.

`paths` Section

The paths section of the run description file is a collection of directory paths that mohid uses to find files in other repos that it needs.

mohid repo

The path to the MIDOSS-MOHID-CODE repository clone where the MohidWater.exe executable for the run is to be found.

This path may be either absolute or relative. 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

Absolute paths with environment variables are strongly recommended for portability and re-usability.

runs directory

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

This 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

Absolute paths with environment variables are strongly recommended for portability and re-usability.

`forcing` Section

The forcing section of the run description file contains key-value pairs that provide the names of files that are to be symlinked in the temporary run directory for MOHID to read forcing data from.

An example forcing section:

forcing:
  winds.hdf5: $PROJECT/MIDOSS/forcing/HRDPS/atmosphere_20150408_20150414.hdf5
  currents.hdf5: $PROJECT/MIDOSS/forcing/SalishSeaCast/hydrodynamics_20150408_20150414.hdf5
  water_levels.hdf5: $PROJECT/MIDOSS/forcing/SalishSeaCast/hydrodynamics_20150408_20150414.hdf5

The keys (winds.hdf5, currents.hdf5, and water_levels.hdf5 above) are the names of the symlinks that will be created in the temporary run directory. Those names are expected to appear in the appropriate places in the .dat files. The values associated with the keys are the targets of the symlinks that will be created in the temporary run directory.

The paths may be relative or absolute. 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

Absolute paths with environment variables are strongly recommended for portability and re-usability.

`bathymetry` Path

The path and file name of the bathymetry file to use for the run is given by the value associated with the bathymetry key. The bathymetry path is inserted into the nomfich.dat file that is created in the temporary run directory as the value associated with the IN_BATIM key.

An example bathymetry line:

bathymetry: $PROJECT/$USER/MIDOSS/MIDOSS-MOHID-config/SalishSeaCast/SalishSeaCast_bathymetry.dat

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 absolute path with environment variables is strongly recommended for portability and re-usability.

`run data files` Section

The run data files section of the run description file contains key-value pairs that provide the keywords and paths to run data files that will be used to build the nomfich.dat file that MOHID requires.

An example run data files section:

run data files:
  IN_MODEL: $PROJECT/$USER/MIDOSS/MIDOSS-MOHID-config/MarathassaConstTS/Model.dat
  PARTIC_DATA: $PROJECT/$USER/MIDOSS/MIDOSS-MOHID-config/MarathassaConstTS/Lagrangian.dat
  DOMAIN: $PROJECT/$USER/MIDOSS/MIDOSS-MOHID-config/SalishSeaCast/Geometry.dat
  SURF_DAT: $PROJECT/$USER/MIDOSS/MIDOSS-MOHID-config/SalishSeaCast/Atmosphere.dat
  DOMAIN: $PROJECT/$USER/MIDOSS/MIDOSS-MOHID-config/SalishSeaCast/Geometry.dat
  IN_DAD3D: $PROJECT/$USER/MIDOSS/MIDOSS-MOHID-config/SalishSeaCast/Hydrodynamic.dat
  BOT_DAT: $PROJECT/$USER/MIDOSS/MIDOSS-MOHID-config/SalishSeaCast/InterfaceSedimentWater.dat
  AIRW_DAT: $PROJECT/$USER/MIDOSS/MIDOSS-MOHID-config/SalishSeaCast/InterfaceWaterAir.dat
  IN_TIDES: $PROJECT/$USER/MIDOSS/MIDOSS-MOHID-config/SalishSeaCast/Tide.dat
  IN_TURB: $PROJECT/$USER/MIDOSS/MIDOSS-MOHID-config/SalishSeaCast/Turbulence.dat
  DISPQUAL: $PROJECT/$USER/MIDOSS/MIDOSS-MOHID-config/SalishSeaCast/WaterProperties.dat
  WAVES_DAT: $PROJECT/$USER/MIDOSS/MIDOSS-MOHID-config/SalishSeaCast/Waves.dat

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 absolute path with environment variables is strongly recommended for portability and re-usability.

Necessary HDF5 results file keywords and paths are automatically added to nomfich.dat. The HDF5 results files are stored in the res/ sub-directory of the temporary run directory (the path that MOHID requires). Their file names are the .dat file stem with the run_id appended, and the extension .hdf. For example, if the value associated with the run_id key in the run description YAML file is MarathassaConstTS, the

PARTIC_DATA: $PROJECT/$USER/MIDOSS/MIDOSS-MOHID-config/MarathassaConstTS/Lagrangian.dat

line in the run data files section causes the following 2 lines to be added to the nomfich.dat file:

PARTIC_DATA : /project/def-allen/dlatorne//MIDOSS/MIDOSS-MOHID-config/MarathassaConstTS/Lagrangian.dat
PARTIC_HDF  : /project/def-allen/dlatorne//MIDOSS/MIDOSS-MOHID-config/MarathassaConstTS/Lagrangian_MarathassaConstTS.hdf

`vcs revisions` Section

The optional vcs revisions section of the run description YAML file contains lists of version control system repositories for which the revision and status will be recorded in the temporary run directory and run results directory.

Note

Revision and status record files for the MIDOSS-MOHID-CODE code repository listed in the paths Section is always generated, so that repository path should not be included in the vcs revisions section.

An example vcs revisions section:

vcs revisions:
  git:
    - $PROJECT/$USER/MIDOSS/Make-MIDOSS-Forcing
    - $PROJECT/$USER/MIDOSS/MIDOSS-MOHID-config
    - $PROJECT/$USER/MIDOSS/MIDOSS-MOHID-grid
    - $PROJECT/$USER/MIDOSS/moad_tools
    - $PROJECT/$USER/MIDOSS/MOHID-Cmd
    - $PROJECT/$USER/MIDOSS/NEMO-Cmd

The sub-section keys (git, and hg above) are the names of the version control tools to use for the repositories listed below them. At present only Git (git) and Mercurial (hg) are supported.

The paths listed under the version control tool key are the repositories for which the revision and status will be recorded.

The repository paths may be relative or absolute. 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

Absolute paths with environment variables are strongly recommended for portability and re-usability.

For each repository, a file will be created in the temporary run directory. The file names are the repository directory names with _rev.txt appended. So, from the example above, the files created will be:

Make-MIDOSS-Forcing_rev.txt
MIDOSS-MOHID-CODE_rev.txt
MIDOSS-MOHID-config_rev.txt
MIDOSS-MOHID-grid_rev.txt
MOHID-Cmd_rev.txt
moad_tools_rev.txt
NEMO-Cmd_rev.txt

For Git repositories, each _rev.txt file will contain the output of the commands:

git branch --show-current
git log -1
git show --pretty="" --name-only

for the repository. That is a record of the last committed revision of the repository that will be in effect for the run. For example, MIDOSS-MOHID-config_rev.txt might contain:

branch: main
commit: 35fc362f3d77866df8c0a8b743aca81359295d59
author: Rachael D. Mueller <rmueller@eoas.ubc.ca>
date:   Fri Nov 01 21:26:36 2019 -04:00
files:  MediumFloater/submit_run_AKNScrude.yaml settings/Model.dat
message:
SOG AKNS 01jun2017 - 08jun2017 with BEACHING_LIMIT: 250

If any of the listed repositories contain uncommitted changes, the nemo prepare command that mohid run uses will generate a warning message like:

nemo_cmd.prepare WARNING: There are uncommitted changes in $PROJECT/$USER/MIDOSS/MIDOSS-MOHID-config/

and the list of uncommitted changes and their status codes, the output of the git diff --name-status command, will be appended to the _rev.txt file, for example:

uncommitted changes:
M MediumFloater/submit_run_AKNScrude.yaml
M settings/Model.dat
M settings/Waves.dat

For Mercurial repositories, each _rev.txt file will contain the output of the hg parents -v command for the repository. That is a record of the last committed revision of the repository that will be in effect for the run. For example, if MOHID-Cmd were is Git repository, MOHID-Cmd_rev.txt might contain:

changset:   17:190158c9704e17d0a8da8f1c0c59576c880a4559
tag:        tip
user:       Doug Latornell <dlatornell@eoas.ubc.ca>
date:       Tue Jan 01 15:56:34 2019 -08:00
files:      mohid_cmd/prepare.py tests/test_prepare.py
description:
Create results directory in tmp run dir.

If any of the listed repositories contain uncommitted changes, the nemo prepare command will generate a warning message like:

nemo_cmd.prepare WARNING: There are uncommitted changes in $PROJECT/$USER/MIDOSS/MOHID-Cmd/

and the list of uncommitted changes and their status codes, the output of the hg status -mardC command, will be appended to the _rev.txt file, for example:

uncommitted changes:
M mohid_cmd/prepare.py

MIDOSS-MOHID Run Description File

Example Run Description YAML File

Basic Run Configuration

paths Section

forcing Section

bathymetry Path

run data files Section

vcs revisions Section

`paths` Section

`forcing` Section

`bathymetry` Path

`run data files` Section

`vcs revisions` Section