mpas_init

Structured YAML to run MPAS Init is validated by JSON Schema and requires the mpas_init: block, described below. If mpas_init 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_init: block, explained in detail below:

mpas_init:
  boundary_conditions:
    interval_hours: 6
    length: 6
    offset: 0
    path: /path/to/boundary/condition/files
  execution:
    batchargs:
      cores: 4
      walltime: "01:30:00"
    executable: init_atmosphere
    mpiargs:
      - "--ntasks=4"
    mpicmd: srun
  files_to_copy:
    conus.graph.info.part.4: /path/to/conus.graph.info.part.4
    conus.static.nc: /path/to/conus.static.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"
  namelist:
    base_file: "{{ user.mpas_app }}/MPAS-Model/namelist.init_atmosphere"
    update_values:
      data_sources:
        config_fg_interval: !int "{{ mpas_init.boundary_conditions['interval_hours'] * 3600 }}"
        config_met_prefix: FILE
      decomposition:
        config_block_decomp_file_prefix: conus.graph.info.part.
      nhyd_model:
        config_init_case: 9
      preproc_stages:
        config_native_gwd_static: false
        config_static_interp: false
      vertical_grid:
        config_blend_bdy_terrain: true
    validate: true
  rundir: /path/to/rundir
  streams:
    input:
      filename_template: conus.static.nc
      input_interval: initial_only
      mutable: false
      type: input
    output:
      filename_template: conus.init.nc
      mutable: false
      output_interval: initial_only
      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_init:` Block

boundary_conditions:

Describes the boundary condition files needed for the forecast. These will most likely be the output of the ungrib tool.

interval_hours:

Frequency interval of the given files, in integer hours.

length:

The length of the forecast 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 output of the ungrib tool that will be used to prepare MPAS-ready initial and lateral boundary conditions. The names of the files are specified in the streams.init_atmosphere XML file, and may be specified in the streams: values: block of the driver YAML.

execution:

See this page for details.

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_init:
  files_to_copy:
    conus.graph.info.part.4: /path/to/conus.graph.info.part.4

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

mpas_init:
  files_to_copy:
    conus.graph.info.part.{{mpas_init.execution["batchargs"]["cores"]}}: /path/to/conus.graph.info.part.{{mpas_init.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)