Ungrib update (#779)

Author: maddenp-cu

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

@@ -1,4 +1,13 @@
 {
+  "$defs": {
+    "iso8601": {
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}[T ][0-9]{2}:[0-9]{2}:[0-9]{2}$",
+      "type": [
+        "datetime",
+        "string"
+      ]
+    }
+  },
   "properties": {
     "ungrib": {
       "additionalProperties": false,
@@ -9,12 +18,3 @@
             "batchargs": {
               "additionalProperties": true,
               "properties": {
-                "cores": {
-                  "type": "integer"
-                },
-                "debug": {
-                  "type": "boolean"
-                },
-                "exclusive": {
-                  "type": "boolean"
-                },

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

@@ -23,28 +23,27 @@ See :ref:`this page <execution_yaml>` for details.
 gribfiles:
 ^^^^^^^^^^
 
-Describes the GRIB-formatted files to be processed by ``ungrib``.
+A list of paths to the GRIB-formatted files to be processed by ``ungrib``. 
 
-  **interval_hours:**
-
-  Frequency interval of the given files, in integer hours.
-
-  **max_leadtime:**
+rundir:
+^^^^^^^
 
-  The maximum forecast leadtime to process. This may be the same as the forecast length, or a lower leadtime.
+The path to the run directory.
 
-  **offset:**
+start:
+^^^^^^
 
-  How many hours earlier the external model used for boundary conditions started compared to the desired forecast cycle, in integer hours.
+The validtime of the initial element of ``gribfiles`` as an ISO8601 timestamp.
 
-  **path:**
+step:
+^^^^^
 
-  An absolute-path template to the GRIB-formatted files to be processed by ``ungrib``. The Python ``int`` variables ``cycle_hour`` and ``forecast_hour`` will be interpolated into, e.g., ``/path/to/gfs.t{cycle_hour:02d}z.pgrb2.0p25.f{forecast_hour:03d}``. Note that this is a Python string template rather than a Jinja2 template.
+The interval between successive elements of ``gribfiles`` as integer hours or as a string of the form ``hours[:minutes[:seconds]]``, where the ``hours``, ``minutes``, and ``seconds`` components are (possibly zero-padded) integers.
 
-rundir:
-^^^^^^^
+stop:
+^^^^^
 
-The path to the run directory.
+The validtime of the final element of ``gribfiles`` as an ISO8601 timestamp.
 
 vtable:
 ^^^^^^^

docs/sections/user_guide/yaml/tags.rst

@@ -38,12 +38,11 @@ Converts the tagged node to a Python ``bool`` object. For example, given ``input
 
 .. code-block:: text
 
-   $ uw config realize -i ../input.yaml --output-format yaml
+   $ uw config realize -i input.yaml --output-format yaml
    flag1: True
    flag2: True
    flag3: False
 
-
 ``!datetime``
 ^^^^^^^^^^^^^
 
@@ -56,9 +55,9 @@ Converts the tagged node to a Python ``datetime`` object. For example, given ``i
 
 .. code-block:: text
 
-   $ uw config realize -i ../input.yaml --output-format yaml
+   $ uw config realize -i input.yaml --output-format yaml
    date1: 2024-09-01
-   date2: 2024-09-01 00:00:00
+   date2: 2024-09-01T00:00:00
 
 The value provided to the tag must be in :python:`ISO 8601 format<datetime.html#datetime.datetime.fromisoformat>` to be interpreted correctly by the ``!datetime`` tag.
 
@@ -76,7 +75,7 @@ Converts the tagged node to a Python ``dict`` value. For example, given ``input.
 
 .. code-block:: text
 
-   $ uw config realize --input-file input.yaml --output-format yaml
+   $ uw config realize -i input.yaml --output-format yaml
    d1: {'k0': 0, 'k1': 1, 'k2': 2}
    d2: {'k0': 0, 'k1': 1, 'k2': 2}
    d3: {'k0': 0, 'k1': 1, 'k2': 2}
@@ -93,7 +92,7 @@ Converts the tagged node to a Python ``float`` value. For example, given ``input
 
 .. code-block:: text
 
-   $ uw config realize --input-file input.yaml --output-format yaml
+   $ uw config realize -i input.yaml --output-format yaml
    f2: 5.859
 
 ``!glob``
@@ -119,7 +118,7 @@ and ``constants.yaml``:
 
 .. code-block:: text
 
-   $ uw config realize --input-file numbers.yaml --output-format yaml
+   $ uw config realize -i numbers.yaml --output-format yaml
    values:
      e: 2.718
      pi: 3.141
@@ -146,7 +145,7 @@ and ``pi.yaml``:
 
 .. code-block:: text
 
-   $ uw config realize --input-file numbers.yaml --output-format yaml
+   $ uw config realize -i numbers.yaml --output-format yaml
    values:
      constants:
        pi: 3.141
@@ -164,7 +163,7 @@ Converts the tagged node to a Python ``int`` value. For example, given ``input.y
 
 .. code-block:: text
 
-   $ uw config realize --input-file input.yaml --output-format yaml
+   $ uw config realize -i input.yaml --output-format yaml
    f1: 3
    f2: 11
    f2: 140
@@ -182,7 +181,7 @@ Converts the tagged node to a Python ``list`` value. For example, given ``input.
 
 .. code-block:: text
 
-   $ uw config realize --input-file input.yaml --output-format yaml
+   $ uw config realize -i input.yaml --output-format yaml
    l1: [1, 2, 3]
    l2: ['a0', 'a1', 'a2']
    l3: ['a0', 'a1', 'a2']
@@ -205,5 +204,26 @@ and ``update.yaml``:
 
 .. code-block:: text
 
-   $ uw config realize --input-file input.yaml --update-file update.yaml --output-format yaml
+   $ uw config realize -i input.yaml --update-file update.yaml --output-format yaml
    pi: 3.141
+
+``!timedelta``
+^^^^^^^^^^^^^^
+
+Converts the tagged node to a Python ``timedelta`` object. For example:
+
+
+.. code-block:: yaml
+
+   base: !datetime 2025-07-31T12:00:00
+   offset: !timedelta 6
+   cycle: !datetime "{{ base + offset }}"
+
+.. code-block:: text
+
+   $ uw config realize -i input.yaml --output-format yaml
+   base: 2025-07-31T12:00:00
+   offset: !timedelta '6:00:00'
+   cycle: 2025-07-31T18:00:00
+
+The value provided to the tag may be an integer number of hours, or a string of the form ``hours[:minutes[:seconds]]``, where the ``hours``, ``minutes``, and ``seconds`` components are (possibly zero-padded) integers.

docs/shared/ungrib.yaml

@@ -5,11 +5,13 @@ ungrib:
       walltime: "00:01:00"
     executable: /path/to/ungrib.exe
   gribfiles:
-    interval_hours: 6
-    max_leadtime: 24
-    offset: 0
-    path: /path/to/dir/gfs.t{cycle_hour:02d}z.pgrb2.0p25.f{forecast_hour:03d}
+    - /path/to/dir/rap.t00z.wrfnatf00.grib2
+    - /path/to/dir/rap.t00z.wrfnatf06.grib2
+    - /path/to/dir/rap.t00z.wrfnatf12.grib2
   rundir: /path/to/run/dir
+  start: 2025-07-31T00:00:00
+  step: 6
+  stop: 2025-07-31T12:00:00
   vtable: /path/to/Vtable.GFS
 platform:
   account: me

src/uwtools/config/formats/yaml.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from collections import OrderedDict
+from datetime import datetime, timedelta
 from types import SimpleNamespace as ns
 from typing import TYPE_CHECKING
 
@@ -21,6 +22,7 @@
 from uwtools.exceptions import UWConfigError
 from uwtools.strings import FORMAT
 from uwtools.utils.file import readable, writable
+from uwtools.utils.time import to_iso8601
 
 if TYPE_CHECKING:
     from pathlib import Path
@@ -66,6 +68,16 @@ def _add_yaml_representers(cls) -> None:
         """
         yaml.add_representer(Namelist, cls._represent_namelist)
         yaml.add_representer(OrderedDict, cls._represent_ordereddict)
+        yaml.add_representer(
+            datetime,
+            lambda dumper, data: dumper.represent_scalar(
+                "tag:yaml.org,2002:timestamp", to_iso8601(data)
+            ),
+        )
+        yaml.add_representer(
+            timedelta,
+            lambda dumper, data: dumper.represent_scalar("!timedelta", str(data)),
+        )
         for tag_class in [UWYAMLConvert, UWYAMLGlob, UWYAMLRemove]:
             yaml.add_representer(tag_class, tag_class.represent)
 

src/uwtools/config/jinja2.py

@@ -5,7 +5,7 @@
 from __future__ import annotations
 
 import os
-from datetime import datetime
+from datetime import datetime, timedelta
 from functools import cached_property
 from pathlib import Path
 from typing import Union
@@ -25,7 +25,7 @@
 from uwtools.utils.file import get_file_format, readable, writable
 
 _ConfigVal = Union[
-    bool, datetime, dict, float, int, list, str, UWYAMLConvert, UWYAMLGlob, UWYAMLRemove
+    bool, datetime, dict, float, int, list, str, timedelta, UWYAMLConvert, UWYAMLGlob, UWYAMLRemove
 ]
 
 

src/uwtools/config/support.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import math
-from datetime import datetime
+from datetime import datetime, timedelta
 from functools import partial
 from importlib import import_module
 from typing import TYPE_CHECKING, Callable, Union
@@ -11,6 +11,7 @@
 from uwtools.exceptions import UWConfigError
 from uwtools.logging import log
 from uwtools.strings import FORMAT
+from uwtools.utils.time import to_datetime, to_timedelta
 
 if TYPE_CHECKING:
     from collections import OrderedDict
@@ -114,10 +115,7 @@ def __repr__(self) -> str:
         return ("%s %s" % (self.tag, self.value)).strip()
 
     @staticmethod
-    def represent(
-        _dumper: yaml.Dumper,
-        data: UWYAMLTag,
-    ) -> yaml.nodes.Node:
+    def represent(_dumper: yaml.Dumper, data: UWYAMLTag) -> yaml.nodes.Node:
         """
         Serialize a scalar value as "!type value".
 
@@ -153,8 +151,8 @@ class UWYAMLConvert(UWYAMLTaggedStr):
     Support for YAML tags that specify type conversions.
     """
 
-    TAGS = ("!bool", "!datetime", "!dict", "!float", "!int", "!list")
-    TaggedValT = Union[bool, datetime, dict, float, int, list]
+    TAGS = ("!bool", "!datetime", "!dict", "!float", "!int", "!list", "!timedelta")
+    TaggedValT = Union[bool, datetime, dict, float, int, list, timedelta]
 
     def __repr__(self) -> str:
         return "%s %s" % (self.tag, self.converted)
@@ -171,12 +169,13 @@ def converted(self) -> UWYAMLConvert.TaggedValT:
         """
         load_as = lambda t, v: t(yaml.safe_load(v))
         converters: list[Callable[..., UWYAMLConvert.TaggedValT]] = [
-            partial(load_as, bool),
-            datetime.fromisoformat,
-            partial(load_as, dict),
-            float,
-            int,
-            partial(load_as, list),
+            partial(load_as, bool),  # !bool
+            to_datetime,  # !datetime
+            partial(load_as, dict),  # !dict
+            float,  # !float
+            int,  # !int
+            partial(load_as, list),  # !list
+            to_timedelta,  # !timedelta
         ]
         return dict(zip(UWYAMLConvert.TAGS, converters))[self.tag](self.value)
 

src/uwtools/config/validator.py

@@ -5,7 +5,7 @@
 from __future__ import annotations
 
 import json
-from datetime import datetime
+from datetime import datetime, timedelta
 from functools import cache
 from pathlib import Path
 from typing import TYPE_CHECKING, Union
@@ -196,9 +196,13 @@ def _validation_errors(config: JSONValueT, schema: dict) -> list[ValidationError
     :return: Any validation errors.
     """
     base = Draft202012Validator
-    type_checker = base.TYPE_CHECKER.redefine(
-        "fs_src", lambda _, x: any(isinstance(x, t) for t in [str, UWYAMLGlob])
-    ).redefine("datetime", lambda _, x: isinstance(x, datetime))
+    type_checker = (
+        base.TYPE_CHECKER.redefine(
+            "fs_src", lambda _, x: any(isinstance(x, t) for t in [str, UWYAMLGlob])
+        )
+        .redefine("datetime", lambda _, x: isinstance(x, datetime))
+        .redefine("timedelta", lambda _, x: isinstance(x, timedelta))
+    )
     uwvalidator = validators.extend(base, type_checker=type_checker)
     validator = uwvalidator(schema, registry=_registry())
     return list(validator.iter_errors(config))