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] TASK ...

Execute cdeps tasks

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

Positional arguments:
  TASK
    atm
      Create data atmosphere configuration with all required content
    atm_nml
      Create data atmosphere Fortran namelist file (datm_in)
    atm_stream
      Create data atmosphere stream config file (datm.streams)
    ocn
      Create data ocean configuration with all required content
    ocn_nml
      Create data ocean Fortran namelist file (docn_in)
    ocn_stream
      Create 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...]]
                    [--quiet] [--verbose]

Create data atmosphere configuration with all required content

Required arguments:
  --cycle CYCLE
      The cycle in ISO8601 format (e.g. 2024-07-17T00)

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 leading through the config to the driver's
      configuration block
  --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.