mpas

Structured YAML to run MPAS is validated by JSON Schema and requires the mpas: block, described below. If mpas is to be run via a batch system, the platform: block, described here, is also required.

This driver receives a cycle argument, which it makes available as a Python datetime object to Jinja2 when realizing its input config. This supports specification of cycle-specific values. For example, the key-value pair
```
gfs.t{{ cycle.strftime('%H') }}z.atmanl.nc: /some/path/{{ cycle.strftime('%Y%m%d%H') }}/gfs.t{{ cycle.strftime('%H') }}z.atmanl.nc
```
would be rendered as
```
gfs.t18z.atmanl.nc: /some/path/2024021218/gfs.t18z.atmanl.nc
```
for cycle 2024-02-12T18.

Here is a prototype UW YAML mpas: block, explained in detail below:

mpas:
  domain: regional
  execution:
    batchargs:
      cores: 32
      walltime: "01:30:00"
    executable: atmosphere_model
    mpiargs:
      - "--ntasks={{ mpas['execution']['batchargs']['cores'] }}"
    mpicmd: srun
  files_to_copy:
    conus.graph.info.part.32: /path/to/conus.graph.info.part.32
    conus.init.nc: /path/to/conus.init.nc
    stream_list.atmosphere.diagnostics: "{{ user.mpas_app }}/MPAS-Model/stream_list.atmosphere.diagnostics"
    stream_list.atmosphere.output: "{{ user.mpas_app }}/MPAS-Model/stream_list.atmosphere.output"
    stream_list.atmosphere.surface: "{{ user.mpas_app }}/MPAS-Model/stream_list.atmosphere.surface"
  files_to_link:
    CAM_ABS_DATA.DBL: "{{ user.mpas_app }}/MPAS-Model/CAM_ABS_DATA.DBL"
    CAM_AEROPT_DATA.DBL: "{{ user.mpas_app }}/MPAS-Model/CAM_AEROPT_DATA.DBL"
    GENPARM.TBL: "{{ user.mpas_app }}/MPAS-Model/GENPARM.TBL"
    LANDUSE.TBL: "{{ user.mpas_app }}/MPAS-Model/LANDUSE.TBL"
    OZONE_DAT.TBL: "{{ user.mpas_app }}/MPAS-Model/OZONE_DAT.TBL"
    OZONE_LAT.TBL: "{{ user.mpas_app }}/MPAS-Model/OZONE_LAT.TBL"
    OZONE_PLEV.TBL: "{{ user.mpas_app }}/MPAS-Model/OZONE_PLEV.TBL"
    RRTMG_LW_DATA: "{{ user.mpas_app }}/MPAS-Model/RRTMG_LW_DATA"
    RRTMG_LW_DATA.DBL: "{{ user.mpas_app }}/MPAS-Model/RRTMG_LW_DATA.DBL"
    RRTMG_SW_DATA: "{{ user.mpas_app }}/MPAS-Model/RRTMG_SW_DATA"
    RRTMG_SW_DATA.DBL: "{{ user.mpas_app }}/MPAS-Model/RRTMG_SW_DATA.DBL"
    SOILPARM.TBL: "{{ user.mpas_app }}/MPAS-Model/SOILPARM.TBL"
    VEGPARM.TBL: "{{ user.mpas_app }}/MPAS-Model/VEGPARM.TBL"
  lateral_boundary_conditions:
    interval_hours: 6
    offset: 0
    path: /path/to/boundary/conditions/directory
  length: 6
  namelist:
    base_file: "{{ user.mpas_app }}/MPAS-Model/namelist.atmosphere"
    update_values:
      decomposition:
        config_block_decomp_file_prefix: conus.graph.info.part.
      limited_area:
        config_apply_lbcs: true
      nhyd_model:
        config_dt: 60
    validate: true
  rundir: /path/to/run/dir
  streams:
    input:
      filename_template: conus.init.nc
      input_interval: initial_only
      mutable: false
      type: input
    output:
      clobber_mode: overwrite
      filename_template: history.$Y-$M-$D_$h.$m.$s.nc
      files:
        - stream_list.atmosphere.output
      io_type: pnetcdf
      mutable: true
      output_interval: "6:00:00"
      precision: single
      reference_time: "2024-06-06 00:00:00"
      type: output
platform:
  account: me
  scheduler: slurm
user:
  mpas_app: /path/to/mpas/installation

An MPAS build provides prototype versions of certain required runtime files. Here, an arbitrarily named user: block defines an mpas_app variable, pointing to the directory where MPAS was installed, to reduce duplication in references to those files.

UW YAML for the `mpas:` Block

domain:

Accepted values are global and regional.

execution:

See this page for details.

lateral_boundary_conditions:

Describes the boundary condition files needed for a regional forecast. This section is not used when domain is set to global. These will be the output from the init_atmosphere executable, which may be run using the mpas_init UW driver. Please see its documentation here.

interval_hours:

Frequency interval of the given files, in integer hours.

offset:

How many hours earlier the external model used for boundary conditions started compared to the desired forecast cycle, in integer hours.

path:

An absolute path to the MPAS-ready files to be used for initial and lateral boundary conditions input. The names of the files are specified in the MPAS streams.atmosphere XML file, and may be specified in the streams: values: block of the driver YAML.

length:

The length of the forecast in integer hours.

files_to_copy:

See this page for details.

To reduce duplication of information in this section, it may be helpful to template the file that depends on the number of cores being used to run the executable. For example, instead of:

mpas:
  files_to_copy:
    conus.graph.info.part.32: /path/to/conus.graph.info.part.32

Jinja2 expressions can be used to reference the number of cores used in execution:

mpas:
  files_to_copy:
    conus.graph.info.part.{{mpas.execution["batchargs"]["cores"]}}: /path/to/conus.graph.info.part.{{mpas.execution["batchargs"]["cores"]}}

files_to_link:

Identical to files_to_copy: except that symbolic links will be created in the run directory instead of copies.

namelist:

Supports base_file: and update_values: blocks (see Updating Values for details).

Before the namelist file is written, its proposed content will be validated against the appropriate schema. This can be suppressed by setting validate: false in the UW YAML configuration block for the namelist.

rundir:

The path to the run directory.

streams:

The streams: block comprises a mapping from stream names to sub-mappings providing configuration values for the named stream. See the “Configuring Model Input and Output” chapter in the MPAS-Atmosphere Model User’s Guide, available from the MPAS releases page, for additional information, including the specifics of supported values, on these attributes.

Required attributes:

filename_template:

The template for files that exist or will be created by the stream. (type: string)

mutable:

Whether the set of fields that belong to the stream may be modified at model run-time. (type: boolean)

type:

One of input, output, input;output, or none. (type: string)

Optional attributes:

clobber_mode:

One of append, never_modify, overwrite, replace_files, or truncate. (type: string)

filename_interval:

The interval at which the stream will be read. (type: string)

files:

Names of files, each of which lists variables, one per line, to associate with the stream. Each filename becomes a <file> child element of the current stream. (type: sequence of strings)

input_interval:

The interval at which the stream will be read. Required if type: includes input. (type: string)

io_type:

One of netcdf, netcdf4, pnetcdf, or pnetcdf,cdf5. (type: string)

output_interval:

The interval at which the stream will be written. Required if type: includes output. (type: string)

packages:

Packages attached to the stream. (type: semicolon-separated list of strings)

precision:

One of double, native, or single. (type: string)

reference_time:

A time that is an integral number of filename intervals from the timestamp of any file associated with the stream. (type: string)

streams:

Names of streams whose explicitly associated fields to associate with the current stream. Each named stream becomes a <stream> child element of the current stream. (type: sequence of strings)

var_arrays:

Names of MPAS-defined var_array items whose constituent variables to associate with the current stream. Each named var_array becomes a <var_array> child element of the current stream. (type: sequence of strings)

var_structs:

Names of MPAS-defined var_struct items whose variables to associate with the current stream. Each named var_struct becomes a <var_struct> child element of the current stream. (type: sequence of strings)

vars:

Names of variables to associate with the current stream. Each named variable becomes a <var> child element of the current stream. (type: sequence of strings)