UW-632 Schema Injection

[maddenp-noaa]

Synopsis

Provide a mechanism to support existing drivers requiring rundir: (Assets and all its subclasses) and execution: (Driver and all its subclasses) blocks in their UW YAML configs to inherit those from a block belonging to a coupled executable, by instantiating such constituent drivers with a new coupler= argument specifying the name of the coupled-executable block. See below for an example.

Note that the diffs in most of the changed files fall into two trivial categories:

1. Replacement of magic strings related to drivers with references to the STR dataclass.
2. Addition of calls to a new function to add constructor arguments to the docstrings for component drivers.

Type

• Code maintenance (refactoring, etc. without behavior change)
• Documentation
• Enhancement (adds new functionality)

Impact

• This is a non-breaking change (existing functionality continues to work as expected)

Checklist

• I have added myself and any co-authors to the PR's Assignees list.
• I have reviewed the documentation and have made any updates necessitated by this change.

Consider this UW YAML config, coastal.yaml, for a hypothetical coupled driver:

coastal:
  execution:
    executable: /path/to/coastal.exe
  rundir: /path/to/run/dir
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
schism:
  namelist:
    template_file: /path/to/schism/param.nml.IN
    template_values:
      dt: 100
ww3:
  namelist:
    template_file: /path/to/ww3/ww3_shel.nml.IN
    template_values:
      input_forcing_winds: C

Ultimately, coastal.exe will be executed, but it will be linked to CDEPS, SCHISM, and WaveWatchIII code, so its driver will need to call on those constituent components' drivers to provision assets (namelist files, stream files) to the run directory. The schism: block does not contain the required rundir: entry, though, so will not pass validation when a hypothetical Coastal driver tries to instantiate a SCHISM driver object:

>>> schism_driver = SCHISM(cycle=dt.datetime(2024, 7, 31, 12), config="coastal.yaml")
1 UW schema-validation error found
Error at schism:
  'rundir' is a required property
...
uwtools.exceptions.UWConfigError: YAML validation errors

Since the coastal: block defines rundir:, the new coupler= argument can be provided to specify that run-time facts required by the SCHISM driver be obtained from that block:

>>> schism_driver = SCHISM(cycle=dt.datetime(2024, 7, 31, 12), config="coastal.yaml", coupler="coastal")
>>> schism_driver._rundir
PosixPath('/path/to/run/dir')

With an instantiated SCHISM driver in hand, the Coastal driver could call e.g. schism_driver.namelist_file() to execute the task to provision the SCHISM namelist file.

Better changes were proposed

[christinaholtNOAA]

LGTM! Thanks for the changes.

[WeirAE]

Honestly, everything was so solid that naming was all I had for feedback! LGTM

[NaureenBharwaniNOAA]

This looks great to me! I see the link that was broken and caused the tests to fail works now. I assume this had to do with the discussion yesterday when the epic link was broken.