`mpas`

Note

The uwtools drivers are idempotent, meaning that actions they successfully complete during one invocation are not repeated in subsequent invocations. For example, an asset like a configuration file will not be recreated when the driver is run again, even if its UW YAML configuration changes. To force recreation, remove the asset(s) in question – up to and including the entire provisioned run directory – then re-run the driver, which will recreate any missing assets based on the current configuration.

The uw mode for configuring and running the MPAS forecast model. Each listed TASK may be called to generate the runtime asset(s) it is responsible for, and will call any task it depends on as needed. A provisioned_rundir comprises everything needed for a run, and a run runs the MPAS executable.

uw mpas --help

usage: uw mpas [-h] [--version] [--show-schema] TASK ...

Execute mpas tasks

Optional arguments:
  -h, --help
      Show help and exit
  --version
      Show version info and exit
  --show-schema
      Show driver schema and exit

Positional arguments:
  TASK
    boundary_files
      Boundary files
    files_copied
      Files copied for run
    files_hardlinked
      Files hardlinked for run
    files_linked
      Files linked for run
    namelist_file
      The namelist file
    provisioned_rundir
      Run directory provisioned with all required content
    run
      A run
    runscript
      The runscript
    show_output
      Show the output to be created by this component
    streams_file
      The streams file
    validate
      Validate the UW driver config

All tasks take the same arguments. For example:

uw mpas run --help

usage: uw mpas run --cycle CYCLE [-h] [--version] [--config-file PATH]
                   [--batch] [--dry-run] [--graph-file PATH]
                   [--key-path KEY[.KEY...]] [--schema-file PATH] [--quiet]
                   [--verbose]

A run

Required arguments:
  --cycle CYCLE
      The cycle in ISO8601 format (e.g. yyyy-mm-ddThh)

Optional arguments:
  -h, --help
      Show help and exit
  --version
      Show version info and exit
  --config-file PATH, -c PATH
      Path to UW YAML config file (default: read from stdin)
  --batch
      Submit job to batch scheduler
  --dry-run
      Only log info, making no changes
  --graph-file PATH
      Path to Graphviz DOT output [experimental]
  --key-path KEY[.KEY...]
      Dot-separated path of keys to driver config block
  --schema-file PATH
      Path to schema file to use for validation
  --quiet, -q
      Print no logging messages
  --verbose, -v
      Print all logging messages

Examples

The examples use a configuration file named config.yaml with contents similar to:

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

Its contents are described in depth in section mpas.

Run MPAS on an interactive node
```
$ uw mpas run --config-file config.yaml --cycle 2025-02-12T12
```
The driver creates a runscript.mpas file in the directory specified by rundir: in the config and runs it, executing atmosphere_model.
Run mpas via a batch job
```
$ uw mpas run --config-file config.yaml --cycle 2025-02-12T12 --batch
```
The driver creates a runscript.mpas file in the directory specified by rundir: in the config and submits it to the batch system. Running with --batch requires a correctly configured platform: block in config.yaml, as well as appropriate settings in the execution: block under mpas:.
Specifying the --dry-run flag results in the driver logging messages about actions it would have taken, without actually taking any.
```
$ uw mpas run --config-file config.yaml --cycle 2025-02-12T12 --batch --dry-run
```

The --key-path option can be used to navigate from the top of the config to the driver’s configuration block. For example, specifying --key-path foo.bar with config
```
foo:
  bar:
    driver:
      # driver config block
```
is equivalent to using config
```
driver:
  # driver config block
```
without specifying --key-path.

The run task depends on the other available tasks and executes them as prerequisites. It is possible to execute any task directly, which entails execution of any of its dependencies. For example, to create an mpas run directory provisioned with all the files, directories, symlinks, etc. required per the configuration file:
```
$ uw mpas provisioned_rundir --config-file config.yaml --cycle 2025-02-12T12 --batch
```

Specifying the --show-schema flag, with no other options, prints the driver’s schema:

uw mpas --show-schema >schema
head -n20 schema

{
  "properties": {
    "mpas": {
      "additionalProperties": false,
      "allOf": [
        {
          "if": {
            "properties": {
              "domain": {
                "const": "regional"
              }
            }
          },
          "then": {
            "required": [
              "lateral_boundary_conditions"
            ]
          }
        }
      ],

Use the --schema-file option to specify a custom JSON Schema file with which to validate the driver config. A custom schema could range in complexity from the simplest, most permissive schema, {}, to one based on the internal schema shown by --show-schema.

mpas

Examples

`mpas`