UW-608 filter_topo driver (ufs-community#510)

maddenp-noaa · Jun 17, 2024 · 7646f58 · 7646f58
1 parent 71bf1e8
commit 7646f58
Show file tree

Hide file tree

Showing 75 changed files with 1,073 additions and 774 deletions.
diff --git a/docs/index.rst b/docs/index.rst
@@ -115,6 +115,12 @@ esg_grid
 | **CLI**: ``uw esg_grid -h``
 | **API**: ``import uwtools.api.esg_grid``
 
+filter_topo
+"""""""""""
+
+| **CLI**: ``uw filter_topo -h``
+| **API**: ``import uwtools.api.filter_topo``
+
 global_equiv_resol
 """"""""""""""""""
 

diff --git a/docs/sections/user_guide/api/filter_topo.rst b/docs/sections/user_guide/api/filter_topo.rst
@@ -0,0 +1,5 @@
+``uwtools.api.filter_topo``
+===========================
+
+.. automodule:: uwtools.api.filter_topo
+    :members:
diff --git a/docs/sections/user_guide/api/index.rst b/docs/sections/user_guide/api/index.rst
@@ -6,6 +6,7 @@ API
    config
    esg_grid
    file
+   filter_topo
    fv3
    global_equiv_resol
    jedi

diff --git a/docs/sections/user_guide/cli/drivers/filter_topo.rst b/docs/sections/user_guide/cli/drivers/filter_topo.rst
@@ -0,0 +1,52 @@
+``filter_topo``
+===============
+
+The ``uw`` mode for configuring and running the UFS Utils preprocessing component ``filter_topo``. Documentation for this UFS Utils component is :ufs-utils:`here <filter-topo>`.
+
+.. literalinclude:: filter_topo/help.cmd
+   :language: text
+   :emphasize-lines: 1
+.. literalinclude:: filter_topo/help.out
+   :language: text
+
+All tasks take the same arguments. For example:
+
+.. literalinclude:: filter_topo/run-help.cmd
+   :language: text
+   :emphasize-lines: 1
+.. literalinclude:: filter_topo/run-help.out
+   :language: text
+
+Examples
+^^^^^^^^
+
+The examples use a configuration file named ``config.yaml`` with contents similar to:
+
+.. highlight:: yaml
+.. literalinclude:: /shared/filter_topo.yaml
+
+Its contents are described in section :ref:`filter_topo_yaml`.
+
+* Run ``filter_topo`` on an interactive node
+
+  .. code-block:: text
+
+     $ uw filter_topo run --config-file config.yaml
+
+  The driver creates a ``runscript.filter_topo`` file in the directory specified by ``run_dir:`` in the config and runs it, executing ``filter_topo``.
+
+* Run ``filter_topo`` via a batch job
+
+  .. code-block:: text
+
+     $ uw filter_topo run --config-file config.yaml --batch
+
+  The driver creates a ``runscript.filter_topo`` file in the directory specified by ``run_dir:`` 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 ``filter_topo:``.
+
+* 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 filter_topo run --config-file config.yaml --batch --dry-run
+
+.. include:: /shared/key_path.rst
diff --git a/docs/sections/user_guide/cli/drivers/filter_topo/Makefile b/docs/sections/user_guide/cli/drivers/filter_topo/Makefile
@@ -0,0 +1 @@
+../../Makefile.outputs
diff --git a/docs/sections/user_guide/cli/drivers/filter_topo/help.cmd b/docs/sections/user_guide/cli/drivers/filter_topo/help.cmd
@@ -0,0 +1 @@
+uw filter_topo --help
diff --git a/docs/sections/user_guide/cli/drivers/filter_topo/help.out b/docs/sections/user_guide/cli/drivers/filter_topo/help.out
@@ -0,0 +1,24 @@
+usage: uw filter_topo [-h] [--version] TASK ...
+
+Execute filter_topo tasks
+
+Optional arguments:
+  -h, --help
+      Show help and exit
+  --version
+      Show version info and exit
+
+Positional arguments:
+  TASK
+    input_grid_file
+      The input grid file
+    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
diff --git a/docs/sections/user_guide/cli/drivers/filter_topo/run-help.cmd b/docs/sections/user_guide/cli/drivers/filter_topo/run-help.cmd
@@ -0,0 +1 @@
+uw filter_topo run --help
diff --git a/docs/sections/user_guide/cli/drivers/filter_topo/run-help.out b/docs/sections/user_guide/cli/drivers/filter_topo/run-help.out
@@ -0,0 +1,26 @@
+usage: uw filter_topo 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
diff --git a/docs/sections/user_guide/cli/drivers/index.rst b/docs/sections/user_guide/cli/drivers/index.rst
@@ -6,6 +6,7 @@ Drivers
 
    chgres_cube
    esg_grid
+   filter_topo
    fv3
    global_equiv_resol
    jedi

diff --git a/docs/sections/user_guide/cli/drivers/make_hgrid.rst b/docs/sections/user_guide/cli/drivers/make_hgrid.rst
@@ -35,6 +35,14 @@ Its contents are described in section :ref:`make_hgrid_yaml`.
 
   The driver creates a ``runscript.make_hgrid`` file in the directory specified by ``run_dir:`` in the config and runs it, executing ``make_hgrid``.
 
+  An example runscript:
+
+  .. literalinclude:: make_hgrid/runscript.cmd
+     :language: text
+     :emphasize-lines: 5
+  .. literalinclude:: make_hgrid/runscript.out
+     :language: text
+
 * Run ``make_hgrid`` via a batch job
 
   .. code-block:: text
@@ -43,12 +51,6 @@ Its contents are described in section :ref:`make_hgrid_yaml`.
 
   The driver creates a ``runscript.make_hgrid`` file in the directory specified by ``run_dir:`` 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 ``make_hgrid:``.
 
-  Looking at the run command in ``runscript.make_hgrid`` shows us the specified executable as well as the YAML keys converted to appropriate command line flags.
-
-  .. code-block:: text
-
-     time make_hgrid --grid_type gnomonic_ed --do_schmidt --great_circle_algorithm --grid_name C96_foo --halo 1 --nest_grids 1 --istart_nest 10 --iend_nest 87 --jstart_nest 19 --jend_nest 78 --nlon 192 --parent_tile 6 --refine_ratio 2 --stretch_factor 1.0001 --target_lon -97.5 --target_lat 38.5
-
 * Specifying the ``--dry-run`` flag results in the driver logging messages about actions it would have taken, without actually taking any.
 
   .. code-block:: text

diff --git a/docs/sections/user_guide/cli/drivers/make_hgrid/.gitignore b/docs/sections/user_guide/cli/drivers/make_hgrid/.gitignore
@@ -0,0 +1,2 @@
+config.yaml
+runscript.make_hgrid
diff --git a/docs/sections/user_guide/cli/drivers/make_hgrid/runscript.cmd b/docs/sections/user_guide/cli/drivers/make_hgrid/runscript.cmd
@@ -0,0 +1,5 @@
+rm -f runscript.make_hgrid
+base=../../../../../shared/make_hgrid.yaml
+echo "make_hgrid: {run_dir: $PWD}" | uw config realize --input-file $base --update-format yaml --output-file config.yaml
+uw make_hgrid runscript --config-file config.yaml 2>/dev/null
+cat runscript.make_hgrid
diff --git a/docs/sections/user_guide/cli/drivers/make_hgrid/runscript.out b/docs/sections/user_guide/cli/drivers/make_hgrid/runscript.out
@@ -0,0 +1,4 @@
+#!/bin/bash
+
+time /path/to/make_hgrid --do_schmidt --great_circle_algorithm --grid_name C96_foo --grid_type gnomonic_ed --halo 1 --iend_nest 87 --istart_nest 10 --jend_nest 78 --jstart_nest 19 --nest_grids 1 --nlon 192 --parent_tile 6 --refine_ratio 2 --stretch_factor 1.0001 --target_lat 38.5 --target_lon -97.5
+test $? -eq 0 && touch runscript.make_hgrid.done
diff --git a/docs/sections/user_guide/cli/drivers/make_solo_mosaic.rst b/docs/sections/user_guide/cli/drivers/make_solo_mosaic.rst
@@ -35,6 +35,15 @@ Its contents are described in section :ref:`make_solo_mosaic_yaml`.
 
   The driver creates a ``runscript.make_solo_mosaic`` file in the directory specified by ``run_dir:`` in the config and runs it, executing ``make_solo_mosaic``.
 
+..
+  An example runscript:
+
+  .. literalinclude:: make_solo_mosaic/runscript.cmd
+     :language: text
+     :emphasize-lines: 5
+  .. literalinclude:: make_solo_mosaic/runscript.out
+     :language: text
+
 * Run ``make_solo_mosaic`` via a batch job
 
   .. code-block:: text
@@ -43,12 +52,6 @@ Its contents are described in section :ref:`make_solo_mosaic_yaml`.
 
   The driver creates a ``runscript.make_solo_mosaic`` file in the directory specified by ``run_dir:`` 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 ``make_solo_mosaic:``.
 
-  Looking at the run command in ``runscript.make_solo_mosaic`` shows us the specified executable as well as the YAML keys converted to appropriate command line flags.
-
-  .. code-block:: text
-
-     time make_solo_mosaic --num_tiles 1 --dir /path/to/grid/ --tile_file C403_grid.tile7.halo6.nc --periodx 360 --periody 360
-
 * Specifying the ``--dry-run`` flag results in the driver logging messages about actions it would have taken, without actually taking any.
 
   .. code-block:: text

diff --git a/docs/sections/user_guide/cli/drivers/make_solo_mosaic/.gitignore b/docs/sections/user_guide/cli/drivers/make_solo_mosaic/.gitignore
@@ -0,0 +1,2 @@
+config.yaml
+runscript.make_solo_mosaic
diff --git a/docs/sections/user_guide/cli/drivers/make_solo_mosaic/runscript.cmd b/docs/sections/user_guide/cli/drivers/make_solo_mosaic/runscript.cmd
@@ -0,0 +1,5 @@
+rm -f runscript.make_solo_mosaic
+base=../../../../../shared/make_solo_mosaic.yaml
+echo "make_solo_mosaic: {run_dir: $PWD}" | uw config realize --input-file $base --update-format yaml --output-file config.yaml
+uw make_solo_mosaic runscript --config-file config.yaml 2>/dev/null
+cat runscript.make_solo_mosaic
diff --git a/docs/sections/user_guide/cli/drivers/make_solo_mosaic/runscript.out b/docs/sections/user_guide/cli/drivers/make_solo_mosaic/runscript.out
@@ -0,0 +1 @@
+cat: runscript.make_solo_mosaic: No such file or directory
diff --git a/docs/sections/user_guide/cli/drivers/orog_gsl.rst b/docs/sections/user_guide/cli/drivers/orog_gsl.rst
@@ -43,12 +43,6 @@ Its contents are described in section :ref:`orog_gsl_yaml`.
 
   The driver creates a ``runscript.orog_gsl`` file in the directory specified by ``run_dir:`` 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_gsl:``.
 
-  Looking at the run command in ``runscript.orog_gsl`` shows us the specified executable as well as the YAML keys converted to appropriate command line flags.
-
-  .. code-block:: text
-
-     time orog_gsl --num_tiles 1 --dir /path/to/grid/ --tile_file C403_grid.tile7.halo6.nc --periodx 360 --periody 360
-
 * Specifying the ``--dry-run`` flag results in the driver logging messages about actions it would have taken, without actually taking any.
 
   .. code-block:: text

diff --git a/docs/sections/user_guide/yaml/components/chgres_cube.rst b/docs/sections/user_guide/yaml/components/chgres_cube.rst
@@ -23,7 +23,7 @@ See :ref:`this page <execution_yaml>` for details.
 namelist
 ^^^^^^^^
 
-Supports ``base_file:`` and ``update_values:`` blocks (see the :ref:`updating_values` for details). Namelist options are described :ufs-utils:`here<global-chgres-cube-namelist-options>`.
+Supports ``base_file:`` and ``update_values:`` blocks (see :ref:`updating_values` for details). Namelist options are described :ufs-utils:`here<global-chgres-cube-namelist-options>`.
 
 .. include:: /shared/validate_namelist.rst
 

diff --git a/docs/sections/user_guide/yaml/components/esg_grid.rst b/docs/sections/user_guide/yaml/components/esg_grid.rst
@@ -20,7 +20,8 @@ See :ref:`this page <execution_yaml>` for details.
 
 namelist:
 ^^^^^^^^^
-Supports ``base_file:`` and ``update_values:`` blocks (see the :ref:`updating_values` for details). Namelist options are described :ufs-utils:`regional_esg_grid<regional-esg-grid>`.
+
+Supports ``base_file:`` and ``update_values:`` blocks (see :ref:`updating_values` for details). Namelist options are described :ufs-utils:`here<regional-esg-grid>`.
 
 .. include:: /shared/validate_namelist.rst
 

diff --git a/docs/sections/user_guide/yaml/components/filter_topo.rst b/docs/sections/user_guide/yaml/components/filter_topo.rst
@@ -0,0 +1,42 @@
+.. _filter_topo_yaml:
+
+filter_topo
+===========
+
+Structured YAML to run the component ``filter_topo`` is validated by JSON Schema and requires the ``filter_topo:`` block, described below. If ``filter_topo`` is to be run via a batch system, the ``platform:`` block, described :ref:`here <platform_yaml>`, is also required.
+
+Documentation for the UFS Utils ``filter_topo`` program is :ufs-utils:`here <orog-gsl>`.
+
+Here is a prototype UW YAML ``filter_topo:`` block, explained in detail below:
+
+.. highlight:: yaml
+.. literalinclude:: /shared/filter_topo.yaml
+
+UW YAML for the ``filter_topo:`` Block
+--------------------------------------
+
+config:
+^^^^^^^
+
+Configuration parameters for the ``orog_gsl`` component.
+
+  **input_grid_file:**
+
+  Path to the tiled input grid file.
+
+namelist:
+^^^^^^^^^
+
+Supports ``base_file:`` and ``update_values:`` blocks (see :ref:`updating_values` for details). Namelist options are described :ufs-utils:`here<id48>`.
+
+.. include:: /shared/validate_namelist.rst
+
+execution:
+^^^^^^^^^^
+
+See :ref:`here <execution_yaml>` for details.
+
+run_dir:
+^^^^^^^^
+
+The path to the run directory.
diff --git a/docs/sections/user_guide/yaml/components/fv3.rst b/docs/sections/user_guide/yaml/components/fv3.rst
@@ -70,12 +70,12 @@ The length of the forecast in integer hours.
 model_configure:
 ^^^^^^^^^^^^^^^^
 
-Supports ``base_file:`` and ``update_values:`` blocks (see the :ref:`updating_values` for details). See FV3 ``model_configure`` documentation :weather-model-io:`here<model-configure-file>`.
+Supports ``base_file:`` and ``update_values:`` blocks (see :ref:`updating_values` for details). See FV3 ``model_configure`` documentation :weather-model-io:`here<model-configure-file>`.
 
 namelist:
 ^^^^^^^^^
 
-Supports ``base_file:`` and ``update_values:`` blocks (see the :ref:`updating_values` for details). See FV3 ``model_configure`` documentation :weather-model-io:`here<namelist-file-input-nml>`.
+Supports ``base_file:`` and ``update_values:`` blocks (see :ref:`updating_values` for details). See FV3 ``model_configure`` documentation :weather-model-io:`here<namelist-file-input-nml>`.
 
 .. include:: /shared/validate_namelist.rst
 

diff --git a/docs/sections/user_guide/yaml/components/index.rst b/docs/sections/user_guide/yaml/components/index.rst
@@ -6,6 +6,7 @@ UW YAML for Components
 
    chgres_cube
    esg_grid
+   filter_topo
    fv3
    global_equiv_resol
    jedi

diff --git a/docs/sections/user_guide/yaml/components/jedi.rst b/docs/sections/user_guide/yaml/components/jedi.rst
@@ -22,7 +22,8 @@ See :ref:`this page <execution_yaml>` for details.
 
 configuration_file:
 ^^^^^^^^^^^^^^^^^^^
-Supports ``base_file:`` and ``update_values:`` blocks (see the :ref:`updating_values` for details).
+
+Supports ``base_file:`` and ``update_values:`` blocks (see :ref:`updating_values` for details).
 
 files_to_copy:
 ^^^^^^^^^^^^^^

diff --git a/docs/sections/user_guide/yaml/components/mpas.rst b/docs/sections/user_guide/yaml/components/mpas.rst
@@ -73,7 +73,7 @@ Identical to ``files_to_copy:`` except that symbolic links will be created in th
 namelist:
 ^^^^^^^^^
 
-Supports ``base_file:`` and ``update_values:`` blocks (see the :ref:`updating_values` for details).
+Supports ``base_file:`` and ``update_values:`` blocks (see :ref:`updating_values` for details).
 
 .. include:: /shared/validate_namelist.rst
 

diff --git a/docs/sections/user_guide/yaml/components/mpas_init.rst b/docs/sections/user_guide/yaml/components/mpas_init.rst
@@ -72,7 +72,7 @@ Identical to ``files_to_copy:`` except that symbolic links will be created in th
 namelist:
 ^^^^^^^^^
 
-Supports ``base_file:`` and ``update_values:`` blocks (see the :ref:`updating_values` for details).
+Supports ``base_file:`` and ``update_values:`` blocks (see :ref:`updating_values` for details).
 
 .. include:: /shared/validate_namelist.rst
 

diff --git a/docs/sections/user_guide/yaml/components/sfc_climo_gen.rst b/docs/sections/user_guide/yaml/components/sfc_climo_gen.rst
@@ -21,7 +21,7 @@ See :ref:`this page <execution_yaml>` for details.
 namelist:
 ^^^^^^^^^
 
-Supports ``base_file:`` and ``update_values:`` blocks (see the :ref:`updating_values` for details). Namelist options are described :ufs-utils:`here<id57>`.
+Supports ``base_file:`` and ``update_values:`` blocks (see :ref:`updating_values` for details). Namelist options are described :ufs-utils:`here <id56>`.
 
 .. include:: /shared/validate_namelist.rst
 

diff --git a/docs/sections/user_guide/yaml/components/upp.rst b/docs/sections/user_guide/yaml/components/upp.rst
@@ -34,7 +34,7 @@ Identical to ``files_to_copy:`` except that symbolic links will be created in th
 namelist:
 ^^^^^^^^^
 
-Supports ``base_file:`` and ``update_values:`` blocks (see the :ref:`updating_values` for details).
+Supports ``base_file:`` and ``update_values:`` blocks (see :ref:`updating_values` for details).
 
 The following namelists and variables can be customized:
-Original file line number
+Diff line change
@@ Expand Up / @@ -6,6 +6,7 @@ API @@
        config
        esg_grid
        file
+       filter_topo
        fv3
        global_equiv_resol
        jedi
@@ Expand Down @@
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		cat: runscript.make_solo_mosaic: No such file or directory