NEMO-3.6 Run Description File for AGRIF Runs

This section describes the additional sections that can be included in a NEMO-3.6 YAML run description file to enable NEMO-Cmd to handle runs that use AGRIF (Adaptive Grid Refinement in Fortran).

Example AGRIF Run Description YAML File

Example:

# nemo command processor run description example for NEMO-3.6

# Name of the NEMO-3.6 configuration to use for the run;
# i.e. your NEMO-3.6-code/NEMOGCM/CONFIG/ configuration directory
config name: mackenzie03

# How is the domain to be distributed over the processors in the
# i and j grid directions?
# These values are used to set the nammpp namelist jpni & jpnj values
# and to set the number of processors and nodes in the PBS script
MPI decomposition: 6x6

# For runs on systems that use qsub/PBS/TORQUE
#
# The run_id value appears in the list of jobs display by the showq command
run_id: example
# Maximum run time requested/allowed for job
# Too low and you 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: 10:00:00
# Email address to send job begin, end, and abort notifications to
email: you@example.com


# Only required if your run uses AGRIF
AGRIF:
  # Absolute path to AGRIF_FixedGrids.in file
  fixed grids: $HOME/CANYONS/mackenzie_canyon/real/AGRIF_FixedGrids.in


paths:
  # Absolute path to CONFIG/ directory in NEMO-3.6 code tree.
  # You can use ~ or $HOME or $USER if you wish.
  NEMO code config: $HOME/CANYONS/NEMO-3.6/CONFIG/
  # If relative, paths below are taken from current directory
  # You can use ~, $USER, $HOME if you wish.
  XIOS: $HOME/CANYONS/XIOS/
  # Directory in which to create temporary run directories
  # Typically NOT inside a version control repository
  runs directory: $HOME/CANYONS/runs/


grid:
  coordinates: $HOME/CANYONS/mackenzie_canyon/grid/coords_02.nc
  bathymetry: $HOME/CANYONS/mackenzie_canyon/grid/ideal_bathy_05.nc
  land processor elimination: False
  AGRIF_1:
    coordinates: $HOME/CANYONS/mackenzie_canyon/grid/coords_for_agrif.nc
    bathymetry: $HOME/CANYONS/mackenzie_canyon/grid/ideal_bathy_for_agrif.nc


forcing:
  # The keys below are the names of symlinks that will be created.
  # The targets of those symlinks will be the paths named by the associated
  # "link to:" keys;
  # e.g. a symlink named NEMO_files will be created to
  # $HOME/CANYONS/mackenzie_canyon/conditions/NEMO_files/
  #
  # The keys are directory names that you use as "cn_dir" values in your
  # namelists.
  #
  # You only need to include keys that are used in the namelist(s) for
  # your run.
  #
  # If relative, paths are taken from forcing path above
  NEMO_files:
      link to: $HOME/CANYONS/mackenzie_canyon/conditions/NEMO_files/


restart:
  # The keys below are the names of symlinks that will be created.
  # The targets of those symlinks will be the paths/filenames associated
  # with the keys;
  # e.g. a symlink named restart.nc will be created to
  # $HOME/CANYONS/results_mackenzie/idealized/sbcana_forcings/forcing01/GYRE_00000030_restart.nc
  #
  # You only need to include keys for the types of restart files
  # that are used in your run.
  #
  # If relative, paths are taken from current directory
  restart.nc: $HOME/CANYONS/results_mackenzie/idealized/sbcana_forcings/forcing01/GYRE_00000030_restart.nc


namelists:
  # The namelist section files in the lists below will be concatenated
  # to create a namelist file whose name is the key under which the files
  # are listed. The keys are the names of the namelist files that NEMO-3.6
  # expects.
  #
  # The only required key is namelist_cfg.
  #
  # If relative, paths are taken from current directory
  namelist_cfg:
    - namelist.time
    - namelist_cfg

  # Sub-grid domain namelists
  AGRIF_1:
    namelist_cfg:
      - namelist.time.agrif
      - namelist_cfg.agrif


output:
  separate XIOS server: True
  XIOS servers: 1
  # If relative, paths are taken from current directory
  iodefs: iodef.xml
  filedefs: file_def.xml
  domaindefs: ../domain_def.xml
  fielddefs: $HOME/CANYONS/mackenzie_canyon/output/field_def.xml
  AGRIF_1:
    filedefs: agrif_file_def.xml
    domaindefs: agrif_domain_def.xml


vcs revisions:
  git:
    # Absolute paths to Mercurial repos that you want revision records of
    # in your run results
    # You can use ~ or $HOME or $USER if you wish.
    - $HOME/CANYONS/NEMO-3.6-code/
    - $HOME/CANYONS/XIOS/
    - $HOME/CANYONS/XIOS-ARCH/
    - $HOME/CANYONS/mackenzie_canyon/
    - $HOME/CANYONS/NEMO-Cmd/

Basic Run Configuration

There are no changes to the basic run configuration key-value pairs for AGRIF runs. Please see Basic Run Configuration.

`AGRIF` Section

The existence of an AGRIF section in the run description YAML file signals to nemo run and nemo prepare that the YAML file includes AGRIF sub-grid sections. It also contains the path to the AGRIF_FixedGrids.in file that NEMO-3.6 uses to configure itself for an AGRIF run.

An example AGRIF section:

AGRIF:
  fixed grids: $HOME/CANYONS/NEMO-forcing-BS1/AGRIF_FixedGrids.in

The value associated with the fixed grids key must be an absolute path. The path may contain ~ or $HOME as alternative spellings of the user’s home directory, and $USER as an alternative spelling of the user’s userid.

`paths` Section

There are no changes to the paths section for AGRIF runs. Please see paths Section.

`grid` Section

The grid section must contain coordinates and bathymetry items for the main grid as described in grid Section.

Note

Land processor elimination is not supported for AGRIF runs.

An example grid section:

grid:
  coordinates: coordinates_seagrid_SalishSea201702.nc
  bathymetry: bathymetry_201702.nc
  land processor elimination: False
  AGRIF_1:
    coordinates: $HOME/MEOPAR/NEMO-forcing-BS1/1_coordinates_seagrid_SalishSea201702.nc
    bathymetry: $HOME/MEOPAR/NEMO-forcing-BS1/1_bathymetry_201702.nc

The AGRIF_1 key identifies a grid sub-section for the first AGRIF sub-grid. It must contain coordinates and bathymetry items for the sub-grid. Those items must follow the same rules as described in grid Section for the main grid coordinates and bathymetry. The AGRIF_1 coordinates file will be symlinked in the run directory as 1_coordinates.nc (the file name required by NEMO). Likewise, the AGRIF_1 bathymetry file will be symlinked as 1_bathy_meter.nc.

Additional AGRIF sub-grid sections are defined by adding additional AGRIF_n sub-sections. The n value from each AGRIF_n sub-section will be used as the prefix for the coordinates and bathymetry links for that sub-grid.

`forcing` Section

There are no changes to the forcing section for AGRIF runs. Please see forcing Section.

`restart` Section

The optional restart section of the run description file contains key-value pairs that provide paths and file names of restart files to be used to initialize the run.

Here is an example restart section:

restart:
  restart.nc: $HOME/CANYONS/results_mackenzie/idealized/sbcana_forcings/forcing01/GYRE_00000030_restart.nc
  AGRIF_1:
    restart.nc: $HOME/CANYONS/results_mackenzie/idealized/sbcana_forcings/forcing01/1_GYRE_00000030_restart.nc

The AGRIF_1 key identifies a restart sub-section for the first AGRIF sub-grid. It contains key-value pairs that provide paths and file names of restart files to be used to initialize sub-grid for the run. Those items must follow the same rules as described in grid Section for the main grid restart files. The AGRIF_1 restart file will be symlinked in the run directory as 1_restart.nc

NEMO requires that the name of the model restart file be restart.nc, so that is the key that you must use. For an (optional) tracers restart file the required file name (key) is restart_trc.nc.

Additional AGRIF sub-grid sections are defined by adding additional AGRIF_n sub-sections. The n value from each AGRIF_n sub-section will be used as the prefix for the restart file links for that sub-grid.

`namelists` Section

The namelists section of the run description file contains a dict of lists of NEMO namelist section files that will be concatenated to construct namelist*_cfg files (the file names required by NEMO) file for the run.

Here is an example namelist section:

namelists:
  namelist_cfg:
    - namelist.time
    - namelist_cfg

  # Sub-grid domain namelists
  AGRIF_1:
    namelist_cfg:
    - 1_namelist.time
    - 1_namelist_cfg

The AGRIF_1 key identifies a namelist sub-section for the first AGRIF sub-grid. Those items must follow the same rules as described in namelists Section for the main grid namelist files. The namelist section files associated with the namelist_cfg key in the AGRIF_1 sub-section will be concatenated to create the 1_namelist_cfg file in the run directory (the file name required by NEMO). Other namelists will be similarly prefixed.

Additional AGRIF sub-grid sections are defined by adding additional AGRIF_n sub-sections. The n value from each AGRIF_n sub-section will be used as the prefix for the namelist files for that sub-grid.

`output` Section

The output section of the run description file contains key-value pairs that provide the names of the files that define the output files, domains, and fields to be used by the XIOS server for the run.

Note

It is assumed here that AGRIF runs use XIOS-2.

Here is an example output section:

output:
  separate XIOS server: True
  XIOS servers: 1
  iodefs: iodef.xml
  domaindefs: ../domain_def.xml
  fielddefs: $HOME/CANYONS/mackenzie_canyon/output/field_def.xml
  filedefs: ../file_def.xml
  AGRIF_1:
    domaindefs: ../1_domain_def.xml
    filedefs: ../1_file_def.xml

The AGRIF_1 key identifies an output sub-section for the first AGRIF sub-grid. It must contain domaindefs and filedefs items for the sub-grid. Those items must follow the same rules as described in output Section for the main grid domain and files definitions. The AGRIF_1 domain definition file will be copied into the run directory as 1_domain_def.xml (the file name required by NEMO). Likewise, the AGRIF_1 files definition file will be copied as 1_file_def.xml.

Additional AGRIF sub-grid sections are defined by adding additional AGRIF_n sub-sections. The n value from each AGRIF_n sub-section will be used as the prefix for the domain and files definition files for that sub-grid.

`vcs revisions` Section

There are no changes to the vcs revisions section for AGRIF runs. Please see vcs revisions Section.

`PBS resources` Section

There are no changes to the PBS resources section for AGRIF runs. Please see PBS resources Section.

`modules to load` Section

There are no changes to the modules to load section for AGRIF runs. Please see modules to load Section.

NEMO-3.6 Run Description File for AGRIF Runs

Example AGRIF Run Description YAML File

Basic Run Configuration

AGRIF Section

paths Section

grid Section

forcing Section

restart Section

namelists Section

output Section

vcs revisions Section

PBS resources Section

modules to load Section