UW-606: Add UFS_UTILS orog driver (#591)

Adds a driver for the UFS_UTILS orog pre-processing component.

docs/index.rst

@@ -162,6 +162,12 @@ make_solo_mosaic
 | **CLI**: ``uw make_solo_mosaic -h``
 | **API**: ``import uwtools.api.make_solo_mosaic``
 
+orog
+""""
+
+| **CLI**: ``uw orog -h``
+| **API**: ``import uwtools.api.orog``
+
 orog_gsl
 """"""""
 

docs/sections/user_guide/api/index.rst

@@ -19,6 +19,7 @@ API
    make_solo_mosaic
    mpas
    mpas_init
+   orog
    orog_gsl
    rocoto
    schism

docs/sections/user_guide/api/orog.rst

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

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

@@ -18,6 +18,7 @@ Drivers
    make_solo_mosaic
    mpas
    mpas_init
+   orog
    orog_gsl
    sfc_climo_gen
    shave

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

@@ -0,0 +1,62 @@
+``orog``
+========
+
+.. include:: /shared/idempotent.rst
+
+The ``uw`` mode for configuring and running the UFS Utils preprocessing component ``orog``.
+
+.. literalinclude:: orog/help.cmd
+   :language: text
+   :emphasize-lines: 1
+.. literalinclude:: orog/help.out
+   :language: text
+
+All tasks take the same arguments. For example:
+
+.. literalinclude:: orog/run-help.cmd
+   :language: text
+   :emphasize-lines: 1
+.. literalinclude:: orog/run-help.out
+   :language: text
+
+Examples
+^^^^^^^^
+
+The examples use a configuration file named ``config.yaml`` with contents similar to:
+
+.. highlight:: yaml
+.. literalinclude:: /shared/orog.yaml
+
+Its contents are described in section :ref:`orog_yaml`.
+
+* Run ``orog`` on an interactive node
+
+  .. code-block:: text
+
+     $ uw orog run --config-file config.yaml
+
+  The driver creates a ``runscript.orog`` file in the directory specified by ``rundir:`` in the config and runs it, executing ``orog``.
+
+* Run ``orog`` via a batch job
+
+  .. code-block:: text
+
+     $ uw orog run --config-file config.yaml --batch
+
+  The driver creates a ``runscript.orog`` file in the directory specified by ``rundir:`` in the config and submits it to the batch system. Running with ``--batch`` requires a correctly configured ``platform:`` block in ``config.yaml``, as well as appropriate settings in the ``execution:`` block under ``orog:``.
+
+* 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 orog run --config-file config.yaml --batch --dry-run
+
+.. include:: /shared/key_path.rst
+
+* Specifying the ``--show-schema`` flag, with no other options, prints the driver's schema:
+
+.. literalinclude:: orog/show-schema.cmd
+   :language: text
+   :emphasize-lines: 1
+.. literalinclude:: orog/show-schema.out
+   :language: text

docs/sections/user_guide/cli/drivers/orog/Makefile

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

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

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

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

@@ -0,0 +1,28 @@
+usage: uw orog [-h] [--version] [--show-schema] TASK ...
+
+Execute orog 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
+    files_linked
+      Files linked for run
+    grid_file
+      The input grid file
+    input_config_file
+      The input config file
+    provisioned_rundir
+      Run directory provisioned with all required content
+    run
+      A run
+    runscript
+      The runscript
+    validate
+      Validate the UW driver config

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

@@ -0,0 +1 @@
+uw orog run --help

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

@@ -0,0 +1,26 @@
+usage: uw orog run [-h] [--version] [--config-file PATH] [--batch] [--dry-run]
+                   [--graph-file PATH] [--key-path KEY[.KEY...]] [--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]
+  --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/orog/show-schema.cmd

@@ -0,0 +1,2 @@
+uw orog --show-schema >schema
+head schema && echo ... && tail schema

docs/sections/user_guide/cli/drivers/orog/show-schema.out

@@ -0,0 +1,21 @@
+{
+  "properties": {
+    "orog": {
+      "additionalProperties": false,
+      "properties": {
+        "execution": {
+          "additionalProperties": false,
+          "properties": {
+            "batchargs": {
+              "additionalProperties": true,
+...
+        "rundir"
+      ],
+      "type": "object"
+    }
+  },
+  "required": [
+    "orog"
+  ],
+  "type": "object"
+}

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

@@ -16,6 +16,7 @@ UW YAML for Components
    make_solo_mosaic
    mpas
    mpas_init
+   orog
    orog_gsl
    schism
    sfc_climo_gen

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

@@ -0,0 +1,57 @@
+.. _orog_yaml:
+
+orog
+====
+
+Structured YAML to run the component ``orog`` is validated by JSON Schema and requires the ``orog:`` block, described below. If ``orog`` is to be run via a batch system, the ``platform:`` block, described :ref:`here <platform_yaml>`, is also required.
+
+Documentation for the UFS Utils ``orog`` program is :ufs-utils:`here <orog>`.
+
+Here is a prototype UW YAML ``orog:`` block, explained in detail below:
+
+.. highlight:: yaml
+.. literalinclude:: /shared/orog.yaml
+
+UW YAML for the ``orog:`` Block
+-------------------------------
+
+old_line1_items
+^^^^^^^^^^^^^^^
+
+Configuration parameters for the ``orog`` component corresponding to the first line entries prior to hash 57bd832 from (July 9, 2024). If using this section, a value for ``orog_file`` should also be provided.
+
+
+execution:
+^^^^^^^^^^
+
+See :ref:`here <execution_yaml>` for details.
+
+files_to_copy:
+^^^^^^^^^^^^^^
+
+See :ref:`this page <files_yaml>` for details.
+
+files_to_link:
+^^^^^^^^^^^^^^
+
+Identical to ``files_to_copy:`` except that symbolic links will be created in the run directory instead of copies.
+
+mask:
+^^^^^
+
+Boolean indicating whether only the land mask will be generated. Defaults to ``false``.
+
+merge:
+^^^^^^
+
+Path to an ocean merge file.
+
+orog_file:
+^^^^^^^^^^
+
+Path to an output orography file if using a version of UFS_UTILS prior to hash 57bd832 from (July 9, 2024). If using this section, values for ``old_line1_items`` should also be provided.
+
+rundir:
+^^^^^^^
+
+The path to the run directory.

docs/shared/mpas.yaml

@@ -42,7 +42,7 @@ mpas:
       nhyd_model:
         config_dt: 60
     validate: true
-  rundir: /path/to/run/directory
+  rundir: /path/to/run/dir
   streams:
     input:
       filename_template: conus.init.nc

docs/shared/orog.yaml

@@ -0,0 +1,15 @@
+orog:
+  execution:
+    batchargs:
+      cores: 1
+      walltime: 00:05:00
+    executable: /path/to/orog
+    files_to_link:
+      fort.15: /path/to/fix/thirty.second.antarctic.new.bin
+      landcover30.fixed: /path/to/fix/landcover30.fixed
+      fort.235: /path/to/fix/gmted2010.30sec.int
+    grid_file: /path/to/netcdf/grid/file
+    rundir: /path/to/run/dir
+platform:
+  account: me
+  scheduler: slurm

docs/shared/schism.yaml

@@ -3,4 +3,4 @@ schism:
     template_file: /path/to/schism/param.nml.IN
     template_values:
       dt: 100
-  rundir: /path/to/run/directory
+  rundir: /path/to/run/dir

docs/shared/ww3.yaml

@@ -3,4 +3,4 @@ ww3:
     template_file: /path/to/ww3/ww3_shel.nml.IN
     template_values:
       input_forcing_winds: C
-  rundir: /path/to/run/directory
+  rundir: /path/to/run/dir

src/uwtools/api/orog.py

@@ -0,0 +1,28 @@
+"""
+API access to the ``uwtools`` ``orog`` driver.
+"""
+
+from uwtools.drivers.orog import Orog
+from uwtools.drivers.support import graph
+from uwtools.drivers.support import tasks as _tasks
+from uwtools.utils.api import make_execute as _make_execute
+
+_driver = Orog
+execute = _make_execute(_driver)
+
+
+def schema() -> dict:
+    """
+    Return the driver's schema.
+    """
+    return _driver.schema()
+
+
+def tasks() -> dict[str, str]:
+    """
+    Return a mapping from task names to their one-line descriptions.
+    """
+    return _tasks(_driver)
+
+
+__all__ = ["Orog", "execute", "graph", "schema", "tasks"]

src/uwtools/cli.py

@@ -81,6 +81,7 @@ def main() -> None:
                 STR.makesolomosaic,
                 STR.mpas,
                 STR.mpasinit,
+                STR.orog,
                 STR.oroggsl,
                 STR.sfcclimogen,
                 STR.shave,
@@ -1188,6 +1189,7 @@ def _parse_args(raw_args: list[str]) -> tuple[Args, Checks]:
             STR.globalequivresol,
             STR.makehgrid,
             STR.makesolomosaic,
+            STR.orog,
             STR.oroggsl,
             STR.sfcclimogen,
             STR.shave,