Merge branch 'main' into logging-update

merge main
ufs-community · Nov 26, 2024 · eaf0725 · eaf0725
2 parents c6a6d56 + b9f70c1
commit eaf0725
Show file tree

Hide file tree

Showing 75 changed files with 6,474 additions and 65 deletions.
diff --git a/.github/scripts/test.sh b/.github/scripts/test.sh
@@ -8,11 +8,12 @@ run_tests() {
   devpkgs=$(jq .packages.dev[] recipe/meta.json | tr -d ' "')
   conda create --yes --name $env --quiet python=$PYTHON_VERSION $devpkgs
   conda activate $env
+  . notebooks/install-deps
   set -x
   python --version
   git clean -dfx
   pip install --editable src # sets new Python version in entry-point scripts
-  make test
+  make test && make test-nb
   status=$?
   set +x
   conda deactivate

diff --git a/Makefile b/Makefile
@@ -1,7 +1,7 @@
 CHANNELS  = $(addprefix -c ,$(shell tr '\n' ' ' <$(RECIPE_DIR)/channels)) -c local
 METADEPS  = $(addprefix $(RECIPE_DIR)/,meta.yaml) src/uwtools/resources/info.json
 METAJSON  = $(RECIPE_DIR)/meta.json
-TARGETS   = clean-devenv devshell docs env format lint meta package test typecheck unittest
+TARGETS   = clean-devenv devshell docs env format lint meta package test test-nb typecheck unittest
 
 export RECIPE_DIR := $(shell cd ./recipe && pwd)
 
@@ -41,6 +41,9 @@ package: meta
 test:
 	recipe/run_test.sh
 
+test-nb:
+	$(MAKE) -C notebooks test-nb
+
 typecheck:
 	recipe/run_test.sh typecheck
 

diff --git a/binder/environment.yml b/binder/environment.yml
@@ -0,0 +1,6 @@
+name: default
+channels:
+  - conda-forge
+  - ufs-community
+dependencies:
+  - uwtools
diff --git a/docs/sections/user_guide/api/config.rst b/docs/sections/user_guide/api/config.rst
@@ -1,6 +1,9 @@
 ``uwtools.api.config``
 ======================
 
+.. image:: https://mybinder.org/badge_logo.svg
+   :target: https://mybinder.org/v2/gh/ufs-community/uwtools/main?labpath=notebooks%2Fconfig.ipynb
+
 .. automodule:: uwtools.api.config
    :inherited-members: UserDict
    :members:
diff --git a/docs/sections/user_guide/api/fs.rst b/docs/sections/user_guide/api/fs.rst
@@ -1,5 +1,8 @@
 ``uwtools.api.fs``
 ==================
 
+.. image:: https://mybinder.org/badge_logo.svg
+   :target: https://mybinder.org/v2/gh/ufs-community/uwtools/main?labpath=notebooks%2Ffs.ipynb
+
 .. automodule:: uwtools.api.fs
    :members:
diff --git a/docs/sections/user_guide/api/rocoto.rst b/docs/sections/user_guide/api/rocoto.rst
@@ -1,5 +1,8 @@
 ``uwtools.api.rocoto``
 ======================
 
+.. image:: https://mybinder.org/badge_logo.svg
+   :target: https://mybinder.org/v2/gh/ufs-community/uwtools/main?labpath=notebooks%2Frocoto.ipynb
+
 .. automodule:: uwtools.api.rocoto
    :members:
diff --git a/docs/sections/user_guide/api/template.rst b/docs/sections/user_guide/api/template.rst
@@ -1,5 +1,8 @@
 ``uwtools.api.template``
 ========================
 
+.. image:: https://mybinder.org/badge_logo.svg
+   :target: https://mybinder.org/v2/gh/ufs-community/uwtools/main?labpath=notebooks%2Ftemplate.ipynb
+
 .. automodule:: uwtools.api.template
    :members:
diff --git a/docs/sections/user_guide/cli/drivers/mpas/show-schema.out b/docs/sections/user_guide/cli/drivers/mpas/show-schema.out
@@ -2,19 +2,19 @@
   "properties": {
     "mpas": {
       "additionalProperties": false,
-      "properties": {
-        "execution": {
-          "additionalProperties": false,
-          "properties": {
-            "batchargs": {
-              "additionalProperties": true,
-              "properties": {
-                "cores": {
-                  "type": "integer"
-                },
-                "debug": {
-                  "type": "boolean"
-                },
-                "exclusive": {
-                  "type": "boolean"
-                },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "domain": {
+                "const": "regional"
+              }
+            }
+          },
+          "then": {
+            "required": [
+              "lateral_boundary_conditions"
+            ]
+          }
+        }
+      ],
diff --git a/docs/sections/user_guide/index.rst b/docs/sections/user_guide/index.rst
@@ -8,3 +8,5 @@ User Guide
    cli/index
    api/index
    yaml/index
+
+.. include:: /shared/binder_links.rst
diff --git a/docs/sections/user_guide/yaml/components/mpas.rst b/docs/sections/user_guide/yaml/components/mpas.rst
@@ -17,15 +17,20 @@ An MPAS build provides prototype versions of certain required runtime files. Her
 UW YAML for the ``mpas:`` Block
 -------------------------------
 
+domain:
+^^^^^^^
+
+Accepted values are ``global`` and ``regional``.
+
 execution:
 ^^^^^^^^^^
 
 See :ref:`this page <execution_yaml>` for details.
 
-boundary_conditions:
-^^^^^^^^^^^^^^^^^^^^
+lateral_boundary_conditions:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Describes the boundary condition files needed for the forecast. These will be the output from the ``init_atmosphere`` executable, which may be run using the ``mpas_init`` UW driver. Please see its documentation :ref:`here <mpas_init_yaml>`.
+Describes the boundary condition files needed for a regional forecast. This section is not used when ``domain`` is set to ``global``. These will be the output from the ``init_atmosphere`` executable, which may be run using the ``mpas_init`` UW driver. Please see its documentation :ref:`here <mpas_init_yaml>`.
 
   **interval_hours:**
 

diff --git a/docs/sections/user_guide/yaml/components/mpas_init.rst b/docs/sections/user_guide/yaml/components/mpas_init.rst
@@ -17,11 +17,6 @@ An MPAS build provides prototype versions of certain required runtime files. Her
 UW YAML for the ``mpas_init:`` Block
 ------------------------------------
 
-execution:
-^^^^^^^^^^
-
-See :ref:`this page <execution_yaml>` for details.
-
 boundary_conditions:
 ^^^^^^^^^^^^^^^^^^^^
 
@@ -43,6 +38,11 @@ Describes the boundary condition files needed for the forecast. These will most
 
 An absolute path to the output of the ``ungrib`` tool that will be used to prepare MPAS-ready initial and lateral boundary conditions. The names of the files are specified in the ``streams.init_atmosphere`` XML file, and may be specified in the ``streams: values:`` block of the driver YAML.
 
+execution:
+^^^^^^^^^^
+
+See :ref:`this page <execution_yaml>` for details.
+
 files_to_copy:
 ^^^^^^^^^^^^^^
 

diff --git a/docs/sections/user_guide/yaml/tags.rst b/docs/sections/user_guide/yaml/tags.rst
@@ -23,6 +23,23 @@ Or explicit:
 
 Additionally, UW defines the following tags to support use cases not covered by standard tags:
 
+``!bool``
+^^^^^^^^^
+
+Converts the tagged node to a Python ``boolean`` object. For example, given ``input.yaml``:
+
+.. code-block:: yaml
+
+   flag1: True
+   flag2: !bool "{{ flag1 }}"
+
+.. code-block:: text
+
+   % uw config realize -i ../input.yaml --output-format yaml
+   flag1: True
+   flag2: True
+
+
 ``!datetime``
 ^^^^^^^^^^^^^
 

diff --git a/docs/shared/binder_links.rst b/docs/shared/binder_links.rst
@@ -0,0 +1,13 @@
+Jupyter Notebooks
+-----------------
+
+* Jupyter Notebook Tutorials (API)
+
+   * `Config Tool <https://mybinder.org/v2/gh/ufs-community/uwtools/main?labpath=notebooks%2Fconfig.ipynb>`_
+   * `File System Tool <https://mybinder.org/v2/gh/ufs-community/uwtools/main?labpath=notebooks%2Ffs.ipynb>`_
+   * `Rocoto Tool <https://mybinder.org/v2/gh/ufs-community/uwtools/main?labpath=notebooks%2Frocoto.ipynb>`_
+   * `Template Tool <https://mybinder.org/v2/gh/ufs-community/uwtools/main?labpath=notebooks%2Ftemplate.ipynb>`_
+
+* Cookbooks
+
+   * `Building and Validating an Experiment Configuration <https://mybinder.org/v2/gh/ufs-community/uwtools/main?labpath=notebooks%2Fexp-config-cb.ipynb>`_
diff --git a/docs/shared/mpas.yaml b/docs/shared/mpas.yaml
@@ -1,4 +1,5 @@
 mpas:
+  domain: regional
   execution:
     batchargs:
       cores: 32

diff --git a/notebooks/.gitignore b/notebooks/.gitignore
@@ -0,0 +1,2 @@
+.ipynb_checkpoints
+tmp
diff --git a/notebooks/Makefile b/notebooks/Makefile
@@ -0,0 +1,18 @@
+TARGETS = format lint test-nb unittest
+
+.PHONY: $(TARGETS)
+
+all:
+	$(error Valid targets are: $(TARGETS))
+
+format:
+	black tests
+	isort tests
+
+lint:
+	pylint tests
+
+test-nb: lint unittest
+
+unittest:
+	pytest tests