`cdeps`

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 cdeps component.

uw cdeps --help

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

Execute cdeps 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
    atm
      The data atmosphere configuration with all required content
    atm_nml
      The data atmosphere Fortran namelist file (datm_in)
    atm_stream
      The data atmosphere stream config file (datm.streams)
    ocn
      The data ocean configuration with all required content
    ocn_nml
      The data ocean Fortran namelist file (docn_in)
    ocn_stream
      The data ocean stream config file (docn.streams)
    validate
      Validate the UW driver config

All tasks take the same arguments. For example:

uw cdeps atm --help

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

The data atmosphere configuration with all required content

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)
  --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 content similar to:

cdeps:
  atm_in:
    update_values:
      datm_nml:
        datamode: GFS
        export_all: true
        factorfn_data: 'null'
        factorfn_mesh: 'null'
        flds_co2: false
        flds_presaero: false
        flds_wiso: false
        iradsw: 1
        model_maskfile: /path/to/mesh1.nc
        model_meshfile: /path/to/mesh1.nc
        nx_global: 100
        ny_global: 100
        restfilm: 'null'
  atm_streams:
    streams:
      stream01:
        dtlimit: 1.5
        mapalgo: redist
        readmode: single
        stream_data_files:
          - /path/to/data_file1.nc
        stream_data_variables:
          - temperature Sa_tbot
        stream_lev_dimname: 'null'
        stream_mesh_file: /path/to/mesh1.nc
        stream_offset: 0
        stream_vectors:
          - u
          - v
        taxmode: limit
        tinterpalgo: linear
        yearAlign: 2008
        yearFirst: 2008
        yearLast: 2008
    template_file: stream.jinja2
  ocn_in:
    update_values:
      docn_nml:
        datamode: some_supported_mode2
        import_data_fields: none
        model_maskfile: /path/to/mesh2.nc
        model_meshfile: /path/to/mesh2.nc
        nx_global: 150
        ny_global: 150
        restfilm: 'null'
        skip_restart_read: true
        sst_constant_value: -1
  ocn_streams:
    streams:
      stream01:
        dtlimit: 1.5
        mapalgo: redist
        readmode: single
        stream_data_files:
          - /path/to/data_file2.nc
          - /path/to/data_file3.nc
        stream_data_variables:
          - sst So_t
          - mask So_omask
        stream_lev_dimname: 'null'
        stream_mesh_file: /path/to/mesh2.nc
        stream_offset: 0
        stream_vectors:
          - 'null'
        taxmode: limit
        tinterpalgo: linear
        yearAlign: 2008
        yearFirst: 2008
        yearLast: 2008
    template_file: stream.jinja2
  rundir: /path/to/dir

Its contents are described in depth in section cdeps. Each of the values in the cdeps YAML may contain Jinja2 variables/expressions using a cycle variable, which is a Python datetime object corresponding to the FV3 cycle being run.

Create CDEPS atm configuration:
```
$ uw cdeps atm --config-file config.yaml --cycle 2023-12-15T18
```
The driver creates a datm_in Fortran namelist file and a datm.streams stream-configuration file in the directory specified by rundir: in the config.
Specifying the --dry-run flag results in the driver logging messages about actions it would have taken, without actually taking any.
```
$ uw cdeps run --config-file config.yaml --cycle 2023-12-15T18 --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.

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

uw cdeps --show-schema >schema
head -n20 schema

{
  "$defs": {
    "streams": {
      "additionalProperties": false,
      "minProperties": 1,
      "patternProperties": {
        "^stream0[1-9]$": {
          "additionalProperties": false,
          "properties": {
            "dtlimit": {
              "type": "number"
            },
            "mapalgo": {
              "type": "string"
            },
            "readmode": {
              "enum": [
                "single"
              ]
            },

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.

cdeps

Examples

`cdeps`