UW-463 UPP driver

.github/pull_request_template.md

@@ -21,7 +21,7 @@ INSTRUCTIONS
 - [ ] Bug fix (corrects a known issue)
 - [ ] Code maintenance (refactoring, etc. without behavior change)
 - [ ] Documentation
-- [ ] Enhancement (adds a new functionality)
+- [ ] Enhancement (adds new functionality)
 - [ ] Tooling (CI, code-quality, packaging, revision-control, etc.)
 
 **Impact**

docs/index.rst

@@ -110,28 +110,28 @@ 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).
 
 esg_grid
-"""""""""""
+""""""""
 
 | **CLI**: ``uw esg_grid -h``
-| **API**: ``import uwtools.api.drivers.esg_grid``
+| **API**: ``import uwtools.api.esg_grid``
 
 global_equiv_resol
 """"""""""""""""""
 
 | **CLI**: ``uw global_equiv_resol -h``
-| **API**: ``import uwtools.api.drivers.global_equiv_resol``
+| **API**: ``import uwtools.api.global_equiv_resol``
 
 make_hgrid
 """"""""""
 
 | **CLI**: ``uw make_hgrid -h``
-| **API**: ``import uwtools.api.drivers.make_hgrid``
+| **API**: ``import uwtools.api.make_hgrid``
 
 sfc_climo_gen
 """""""""""""
 
 | **CLI**: ``uw sfc_climo_gen -h``
-| **API**: ``import uwtools.api.drivers.sfc_climo_gen``
+| **API**: ``import uwtools.api.sfc_climo_gen``
 
 shave
 """""
@@ -143,22 +143,28 @@ chgres_cube
 """""""""""
 
 | **CLI**: ``uw chgres_cube -h``
-| **API**: ``import uwtools.api.drivers.chgres_cube``
+| **API**: ``import uwtools.api.chgres_cube``
 
 FV3
 """
 
 | **CLI**: ``uw fv3 -h``
-| **API**: ``import uwtools.api.drivers.fv3``
+| **API**: ``import uwtools.api.fv3``
 
-JEDI
-""""
+UPP
+"""
 
-| **CLI**: ``uw jedi -h``
-| **API**: ``import uwtools.api.drivers.jedi``
+| **CLI**: ``uw upp -h``
+| **API**: ``import uwtools.api.upp``
 
+Driver for JEDI
+^^^^^^^^^^^^^^^
 
+JEDI
+""""
 
+| **CLI**: ``uw jedi -h``
+| **API**: ``import uwtools.api.jedi``
 
 Drivers for MPAS
 ^^^^^^^^^^^^^^^^
@@ -169,22 +175,19 @@ ungrib
 """"""
 
 | **CLI**: ``uw ungrib -h``
-| **API**: ``import uwtools.api.drivers.ungrib``
-
+| **API**: ``import uwtools.api.ungrib``
 
 mpas_init
 """""""""
 
 | **CLI**: ``uw mpas_init -h``
-| **API**: ``import uwtools.api.drivers.mpas_init``
+| **API**: ``import uwtools.api.mpas_init``
 
 mpas
 """"
 
 | **CLI**: ``uw mpas -h``
-| **API**: ``import uwtools.api.drivers.mpas``
-
-
+| **API**: ``import uwtools.api.mpas``
 
 ------------------
 

docs/sections/user_guide/api/chgres_cube.rst

@@ -1,5 +1,5 @@
 ``uwtools.api.chgres_cube``
-=============================
+===========================
 
 .. automodule:: uwtools.api.chgres_cube
     :members:

docs/sections/user_guide/api/esg_grid.rst

@@ -1,5 +1,5 @@
 ``uwtools.api.esg_grid``
-=============================
+========================
 
 .. automodule:: uwtools.api.esg_grid
     :members:

docs/sections/user_guide/api/fv3.rst

@@ -1,5 +1,5 @@
 ``uwtools.api.fv3``
-========================
+===================
 
 .. automodule:: uwtools.api.fv3
     :members:

docs/sections/user_guide/api/index.rst

@@ -18,3 +18,4 @@ API
    shave
    template
    ungrib
+   upp

docs/sections/user_guide/api/jedi.rst

@@ -1,5 +1,5 @@
 ``uwtools.api.jedi``
-==========================
+====================
 
 .. automodule:: uwtools.api.jedi
     :members:

docs/sections/user_guide/api/mpas.rst

@@ -1,5 +1,5 @@
 ``uwtools.api.mpas``
-=============================
+====================
 
 .. automodule:: uwtools.api.mpas
     :members:

docs/sections/user_guide/api/mpas_init.rst

@@ -1,5 +1,5 @@
 ``uwtools.api.mpas_init``
-=============================
+=========================
 
 .. automodule:: uwtools.api.mpas_init
     :members:

docs/sections/user_guide/api/shave.rst

@@ -1,5 +1,5 @@
 ``uwtools.api.shave``
-======================
+=====================
 
 .. automodule:: uwtools.api.shave
     :members:

docs/sections/user_guide/api/ungrib.rst

@@ -1,5 +1,5 @@
 ``uwtools.api.ungrib``
-=============================
+======================
 
 .. automodule:: uwtools.api.ungrib
-    :members:
+    :members:

docs/sections/user_guide/api/upp.rst

@@ -0,0 +1,5 @@
+``uwtools.api.upp``
+===================
+
+.. automodule:: uwtools.api.upp
+    :members:

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

@@ -34,22 +34,22 @@ All tasks take the same arguments. For example:
 .. code-block:: text
 
    $ uw chgres_cube run --help
-   usage: uw chgres_cube run --config-file PATH --cycle CYCLE [-h] [--version] [--batch] [--dry-run]
-                             [--graph-file PATH] [--quiet] [--verbose]
+   usage: uw chgres_cube run --cycle CYCLE [-h] [--version] [--config-file PATH] [--batch]
+                             [--dry-run] [--graph-file PATH] [--quiet] [--verbose]
 
    A run
 
    Required arguments:
-     --config-file PATH, -c PATH
-         Path to UW YAML config file
      --cycle CYCLE
-         The cycle in ISO8601 format
+         The cycle in ISO8601 format (e.g. 2024-05-08T18)
 
    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 run to batch scheduler
      --dry-run
@@ -69,10 +69,8 @@ The examples use a configuration file named ``config.yaml`` with content similar
 .. highlight:: yaml
 .. literalinclude:: ../../../../shared/chgres_cube.yaml
 
-
 Its contents are described in depth in section :ref:`chgres_cube_yaml`. Each of the values in the ``chgres_cube`` YAML may contain Jinja2 variables/expressions using a ``cycle`` variable, which is a Python ``datetime`` object corresponding to the FV3 cycle being run.
 
-
 * Run ``chgres_cube`` on an interactive node
 
   .. code-block:: text

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

@@ -6,57 +6,56 @@ The ``uw`` mode for configuring and running the :ufs-utils:`regional_esg_grid<re
 .. code-block:: text
 
    $ uw esg_grid --help
-    usage: uw esg_grid [-h] [--version] TASK ...
-
-    Execute esg_grid tasks
-
-    Optional arguments:
-      -h, --help
-          Show help and exit
-      --version
-          Show version info and exit
-
-    Positional arguments:
-      TASK
-        namelist_file
-          The namelist file
-        provisioned_run_directory
-          Run directory provisioned with all required content
-        run
-          A run
-        runscript
-          The runscript
-        validate
-          Validate the UW driver config
+   usage: uw esg_grid [-h] [--version] TASK ...
+
+   Execute esg_grid tasks
+
+   Optional arguments:
+     -h, --help
+         Show help and exit
+     --version
+         Show version info and exit
+
+   Positional arguments:
+     TASK
+       namelist_file
+         The namelist file
+       provisioned_run_directory
+         Run directory provisioned with all required content
+       run
+         A run
+       runscript
+         The runscript
+       validate
+         Validate the UW driver config
 
 All tasks take the same arguments. For example:
 
 .. code-block:: text
 
-    $ uw esg_grid run --help
-    usage: uw esg_grid run --config-file PATH [-h] [--version] [--batch] [--dry-run] [--graph-file PATH] [--quiet] [--verbose]
-
-    A run
-
-    Required arguments:
-      --config-file PATH, -c PATH
-          Path to UW YAML config file
-
-    Optional arguments:
-      -h, --help
-          Show help and exit
-      --version
-          Show version info and exit
-      --batch
-          Submit run to batch scheduler
-      --dry-run
-          Only log info, making no changes
-      --graph-file PATH
-          Path to Graphviz DOT output [experimental]
-      --quiet, -q
-          Print no logging messages
-      --verbose, -v
-          Print all logging messages
+   $ uw esg_grid run --help
+   usage: uw esg_grid run [-h] [--version] [--config-file PATH] [--batch] [--dry-run]
+                          [--graph-file PATH] [--quiet] [--verbose]
+
+   A run
+
+   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 run to batch scheduler
+     --dry-run
+         Only log info, making no changes
+     --graph-file PATH
+         Path to Graphviz DOT output [experimental]
+     --quiet, -q
+         Print no logging messages
+     --verbose, -v
+         Print all logging messages
 
 Examples
 ^^^^^^^^

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

@@ -8,7 +8,7 @@ The ``uw`` mode for configuring and running FV3.
    $ uw fv3 --help
    usage: uw fv3 [-h] [--version] TASK ...
 
-   Execute FV3 tasks
+   Execute fv3 tasks
 
    Optional arguments:
      -h, --help
@@ -57,7 +57,7 @@ All tasks take the same arguments. For example:
      --config-file PATH, -c PATH
          Path to UW YAML config file
      --cycle CYCLE
-         The cycle in ISO8601 format
+         The cycle in ISO8601 format (e.g. 2024-05-08T18)
 
    Optional arguments:
      -h, --help

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

@@ -5,7 +5,7 @@ The ``uw`` mode for configuring and running the UFS Utils preprocessing componen
 
 .. code-block:: text
 
-   $ uw global_equiv_resol -h
+   $ uw global_equiv_resol --help
    usage: uw global_equiv_resol [-h] [--version] TASK ...
 
    Execute global_equiv_resol tasks
@@ -33,21 +33,19 @@ All tasks take the same arguments. For example:
 
 .. code-block:: text
 
-   $ uw global_equiv_resol run -h
-   usage: uw global_equiv_resol run --config-file PATH [-h] [--version] [--batch] [--dry-run]
+   $ uw global_equiv_resol run --help
+   usage: uw global_equiv_resol run [-h] [--version] [--config-file PATH] [--batch] [--dry-run]
                                     [--graph-file PATH] [--quiet] [--verbose]
 
    A run
 
-   Required arguments:
-     --config-file PATH, -c PATH
-         Path to config file
-
    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 run to batch scheduler
      --dry-run
@@ -67,7 +65,6 @@ The examples use a configuration file named ``config.yaml`` with content similar
 .. highlight:: yaml
 .. literalinclude:: ../../../../shared/global_equiv_resol.yaml
 
-
 Its contents are described in section :ref:`global_equiv_resol_yaml`.
 
 * Run ``global_equiv_resol`` on an interactive node

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

@@ -15,3 +15,4 @@ Drivers
    sfc_climo_gen
    shave
    ungrib
+   upp