Adding CDEPS support

docs/conf.py

@@ -31,6 +31,7 @@
     "anaconda": ("https://www.anaconda.com/%s", "%s"),
     "anaconda-condev": ("https://anaconda.org/maddenp/condev/%s", "%s"),
     "black": ("https://black.readthedocs.io/en/stable/%s", "%s"),
+    "cdeps": ("https://escomp.github.io/CDEPS/versions/master/html/%s", "%s"),
     "cmeps": ("https://escomp.github.io/CMEPS/versions/master/html/esmflds.html#%s", "%s"),
     "conda": ("https://docs.conda.io/en/latest/%s", "%s"),
     "conda-forge": ("https://conda-forge.org/%s", "%s"),

docs/index.rst

@@ -125,6 +125,12 @@ Drivers for UFS
 
 To prepare a complete forecast, drivers would typically be run in the order shown here (along with additional drivers still in development).
 
+cdeps
+"""""
+
+| **CLI**: ``uw cdeps -h``
+| **API**: ``import uwtools.api.cdeps``
+
 esg_grid
 """"""""
 

docs/sections/user_guide/api/cdeps.rst

@@ -0,0 +1,6 @@
+``uwtools.api.cdeps``
+=====================
+
+.. automodule:: uwtools.api.cdeps
+   :inherited-members:
+   :members:

docs/sections/user_guide/api/index.rst

@@ -2,6 +2,7 @@ API
 ===
 
 .. toctree::
+   cdeps
    chgres_cube
    config
    esg_grid

docs/sections/user_guide/cli/drivers/cdeps.rst

@@ -0,0 +1,45 @@
+``cdeps``
+=========
+
+The ``uw`` mode for configuring and running the :CDEPS:`cdeps<>` component.
+
+.. literalinclude:: cdeps/help.cmd
+   :language: text
+   :emphasize-lines: 1
+.. literalinclude:: cdeps/help.out
+   :language: text
+
+All tasks take the same arguments. For example:
+
+.. literalinclude:: cdeps/run-help.cmd
+   :language: text
+   :emphasize-lines: 1
+.. literalinclude:: cdeps/run-help.out
+   :language: text
+
+Examples
+^^^^^^^^
+
+The examples use a configuration file named ``config.yaml`` with content similar to:
+
+.. highlight:: yaml
+.. literalinclude:: /shared/cdeps.yaml
+
+Its contents are described in depth in section :ref:`cdeps_yaml`. 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:
+
+  .. code-block:: text
+
+     $ 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.
+
+  .. code-block:: text
+
+     $ uw cdeps run --config-file config.yaml --cycle 2023-12-15T18 --batch --dry-run
+
+.. include:: /shared/key_path.rst

docs/sections/user_guide/cli/drivers/cdeps/Makefile

@@ -0,0 +1 @@
+../../Makefile.outputs

docs/sections/user_guide/cli/drivers/cdeps/help.cmd

@@ -0,0 +1 @@
+uw cdeps --help

docs/sections/user_guide/cli/drivers/cdeps/help.out

@@ -0,0 +1,28 @@
+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)
+    provisioned_rundir
+      Run directory provisioned with all required content
+    validate
+      Validate the UW driver config

docs/sections/user_guide/cli/drivers/cdeps/run-help.cmd

@@ -0,0 +1 @@
+uw cdeps atm --help

docs/sections/user_guide/cli/drivers/cdeps/run-help.out

@@ -0,0 +1,28 @@
+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

docs/sections/user_guide/cli/drivers/index.rst

@@ -4,6 +4,7 @@ Drivers
 .. toctree::
    :maxdepth: 1
 
+   cdeps
    chgres_cube
    esg_grid
    filter_topo

docs/sections/user_guide/yaml/components/cdeps.rst

@@ -0,0 +1,53 @@
+.. _cdeps_yaml:
+
+cdeps
+=====
+
+Structured YAML to run :cdeps:`CDEPS<index.html>` is validated by JSON Schema and requires the ``cdeps:`` block, described below.
+
+.. include:: /shared/injected_cycle.rst
+
+Here is a prototype UW YAML ``cdeps:`` block, explained in detail below:
+
+.. highlight:: yaml
+.. literalinclude:: /shared/cdeps.yaml
+
+UW YAML for the ``cdeps:`` Block
+--------------------------------
+
+atm_in
+^^^^^^
+
+Configures the atm namelist file. Supports ``base_file:`` and ``update_values:`` blocks (see :ref:`updating_values` for details). Namelist options are described :cdeps:`here<streams.html>`.
+
+.. include:: /shared/validate_namelist.rst
+
+atm_streams
+^^^^^^^^^^^
+
+Configures the atm streams.
+
+  **streams:**
+
+  The ``streams:`` block may contain sub-blocks ``stream01`` through ``stream09``. Each such sub-block specifies a stream configuration to be used to render the Jinja2 template file named by ``template_file:`` (see below). Supported keys and avlues are described :cdeps:`here<streams.html>`.
+
+  **template_file:**
+
+  The path to a Jinja2 template file to be rendered, using the values from the ``streams:`` block (see above), to a streams file.
+
+ocn_in
+^^^^^^
+
+Configures the ocn namelist file. Supports ``base_file:`` and ``update_values:`` blocks (see :ref:`updating_values` for details). Namelist options are described :cdeps:`here<streams.html>`.
+
+.. include:: /shared/validate_namelist.rst
+
+ocn_streams
+^^^^^^^^^^^
+
+Configures the ocn streams. See the ``atm_streams:`` block, above, which is configured identically.
+
+rundir
+^^^^^^
+
+The path to the run directory.

docs/sections/user_guide/yaml/components/index.rst

@@ -4,6 +4,7 @@ UW YAML for Components
 .. toctree::
    :maxdepth: 1
 
+   cdeps
    chgres_cube
    esg_grid
    filter_topo

docs/shared/cdeps.yaml

@@ -0,0 +1,78 @@
+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:
+          - var1
+        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:
+          - var2
+          - var3
+        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
+platform:
+  account: me
+  scheduler: slurm

src/uwtools/api/cdeps.py

@@ -0,0 +1,14 @@
+"""
+API access to the ``uwtools`` ``cdeps`` driver.
+"""
+
+from functools import partial
+
+from uwtools.drivers.cdeps import CDEPS
+from uwtools.drivers.support import graph, tasks
+from uwtools.utils.api import make_execute as _make_execute
+
+_driver = CDEPS
+execute = _make_execute(_driver, with_cycle=True)
+tasks = partial(tasks, _driver)
+__all__ = [_driver.__name__, "execute", "graph", "tasks"]