Fixes for regional run; build strict

Author: zmoon

.github/workflows/deploy.yml

@@ -23,17 +23,17 @@ jobs:
     steps:
       - uses: actions/checkout@v5
 
-      - name: Setup Pages
+      - name: Set up Pages
         uses: actions/configure-pages@v5
 
-      - name: Setup Python
+      - name: Set up Python
         uses: mamba-org/setup-micromamba@v2
         with:
           environment-file: environment.yml
           cache-environment: true
 
-      - name: Build HTML Assets
-        run: jupyter-book build --html --execute --ci
+      - name: Build HTML
+        run: jupyter-book build --html --execute --strict --ci
         shell: micromamba-shell {0}
 
       - name: Upload artifact

01-compile.md

@@ -1,7 +1,7 @@
 ---
 title: Build
 subtitle: Building MPAS on NSF NCAR Derecho
-label: build
+label: page:build
 ---
 
 First we need to clone the model repository.
@@ -15,6 +15,8 @@ cd $_
 git switch isolevels-v8
 ```
 
+(p:interactive-job)=
+
 It's good practice to compile the model in an interactive job,
 to avoid stressing the login nodes, which are a shared resource,
 _and_ to ensure that the CPU resources detected at build time are the same as those used at run time[^derecho-nodes].
@@ -115,4 +117,10 @@ we can build the main program.
 make -j4 intel CORE=atmosphere
 ```
 
-If this completes successfully, we should have an `atmosphere_model` executable.
+If this completes successfully, we should have an `atmosphere_model` executable
+(and `build_tables`)
+and we can leave our interactive job.
+
+```bash
+exit
+```

02-run.md

@@ -1,7 +1,7 @@
 ---
 title: Run
 subtitle: Running MPAS on NSF NCAR Derecho
-label: run
+label: page:run
 ---
 
 # Global
@@ -267,6 +267,8 @@ A successful run will produce various model output files:
 - `history.*.nc` (2- and 3-d prognostic and diagnostic fields; specified in `stream_list.atmosphere.output`)
 - `restart.*.nc` (checkpoints of the model state that we can use for a warm start)
 
+(sec:run-regional)=
+
 # Regional
 
 We will use the limited-area domain as in:
@@ -280,11 +282,31 @@ created by rotating, moving, and cropping the `x5.8060930` global 15–3-km elli
 
 ```{figure} africa-domain.png
 
-Made with [GeoVista](viz#geovista).
+Made with {ref}`GeoVista <sec:geovista>`.
 ```
 
 ## Run directory
 
+First we need to generate the tables for the Thompson microphysics scheme.
+As when we {ref}`built <p:interactive-job>` the model, we can use an interactive job.
+
+```bash
+qsub -I -l walltime=3600 -l select=1:ncpus=2:mem=16gb -A UTAM0025 -q develop
+```
+
+```bash
+source ~/mpas-modules-intel.sh
+
+cd ~/MPAS-Model_v8.3
+
+./build_tables
+
+mv MP_THOMPSON_* src/core_atmosphere/physics/physics_wrf/files/
+ln -s src/core_atmosphere/physics/physics_wrf/files/MP_THOMPSON_* .
+
+exit
+```
+
 As before, we first build out our run directory.
 We use the same MPAS-Model directory, but copy a different mesh.
 
@@ -334,6 +356,7 @@ Update `namelist.init_atmosphere` with these settings:
 | `nhyd_model.config_init_case`                   | `7`                         |
 | `nhyd_model.config_start_time`                  | `'2017-09-12_00:00:00'`     |
 | `data_sources.config_met_prefix`                | `'FILE'`                    |
+| `data_sources.config_noahmp_static`             | `false` [^noahmp]           |
 | `preproc_stages.config_static_interp`           | `false`                     |
 | `preproc_stages.config_native_gwd_static`       | `false`                     |
 | `preproc_stages.config_native_gwd_gsl_static`   | `false`                     |
@@ -345,6 +368,13 @@ Update `namelist.init_atmosphere` with these settings:
 
 :::
 
+[^noahmp]:
+    Our static file was created with v8.0, before the Noah-MP land model was added to MPAS-A (v8.2),
+    so we [have to](https://forum.mmm.ucar.edu/threads/3-km-static-file-created-by-create_region-doesnt-have-nsoilcomps-as-a-dimension-and-results-in-error-when-creating-initial-conditions.21865/post-54423)
+    disable collecting input fields for Noah-MP.
+
+    This is a hidden option; add it to the end of its section (`data_sources`).
+
 Then, in `streams.init_atmosphere`, set the input file name template to `Africa.static.nc`
 and the output file name template to `Africa.init.nc`.
 
@@ -378,15 +408,16 @@ qsub init.pbs
 
 Update `namelist.init_atmosphere` with these settings:
 
-:::{table} `namelist.init_atmosphere` settings for BC generation for the regional example
+:::{table} `namelist.init_atmosphere` settings for LBC generation for the regional example
 :label: africa-namelist-bc
 
 | parameter                                       | value                       |
 | ----------------------------------------------- | --------------------------- |
 | `nhyd_model.config_init_case`                   | `9`                         |
 | `nhyd_model.config_start_time`                  | `'2017-09-12_00:00:00'`     |
-| `nhyd_model.config_stop_time`                   | `'2017-09-13_11:00:00'`     |
+| `nhyd_model.config_stop_time`                   | `'2017-09-13_12:00:00'`     |
 | `data_sources.config_met_prefix`                | `'FILE'`                    |
+| `data_sources.config_fg_interval`               | `3600` (seconds)            |
 | `preproc_stages.config_static_interp`           | `false`                     |
 | `preproc_stages.config_native_gwd_static`       | `false`                     |
 | `preproc_stages.config_native_gwd_gsl_static`   | `false`                     |
@@ -398,11 +429,12 @@ Update `namelist.init_atmosphere` with these settings:
 
 :::
 
-👆 The differences are that now we are using init case 9,
+👆 Compared to {ref}`africa-namelist-ic`, the differences are that now we are using init case 9,
 and we need to set a stop time.
 
-Then, in `streams.init_atmosphere`, set the input file name template to `Africa.init.nc`
-and the LBC output interval to `1:00:00` (hourly).
+Then, in `streams.init_atmosphere`, set the input file name template to `Africa.init.nc`,
+the output file name template to `foo.nc` (unused, but it can't be the same as others),
+and the LBC output interval to `1:00:00` (hourly; consistent with our `config_fg_interval`).
 
 Submit the job (same one we used to create the initial conditions):
 
@@ -419,19 +451,28 @@ Update `namelist.atmosphere` with these settings:
 :::{table} `namelist.atmosphere` settings for the regional example
 :label: africa-namelist-run
 
-| parameter                                       | value                       |
-| ----------------------------------------------- | --------------------------- |
-| `nhyd_model.config_dt`                          | `13.0`                      |
-| `nhyd_model.config_start_time`                  | `'2017-09-12_00:00:00'`     |
-| `nhyd_model.config_run_duration`                | `'1_12:00:00'`              |
-| `nhyd_model.config_radtlw_interval`             | `'00:30:00'`                |
-| `nhyd_model.config_radtsw_interval`             | `'00:30:00'`                |
-| `physics.config_physics_suite`                  | `'convection_permitting'`   |
-| `decomposition.config_block_decomp_file_prefix` | `'Africa.graph.info.part.'` |
+| parameter                                       | value                         |
+| ----------------------------------------------- | ----------------------------- |
+| `nhyd_model.config_dt`                          | `13.0`                        |
+| `nhyd_model.config_start_time`                  | `'2017-09-12_00:00:00'`       |
+| `nhyd_model.config_run_duration`                | `'1_12:00:00'`                |
+| `nhyd_model.config_len_disp`                    | `3000.0` (meters) [^len-disp] |
+| `limited_area.config_apply_lbcs`                | `true`                        |
+| `physics.config_radtlw_interval`                | `'00:30:00'`                  |
+| `physics.config_radtsw_interval`                | `'00:30:00'`                  |
+| `physics.config_physics_suite`                  | `'convection_permitting'`     |
+| `decomposition.config_block_decomp_file_prefix` | `'Africa.graph.info.part.'`   |
 
 :::
 
-👆 Note that we have set a much smaller time step than in the coarse global example,
+[^len-disp]:
+    Horizontal length scale for Smagorinsky diffusion (meters).
+    We have to set it because `nominalMinDc` is 0 in our static file.
+
+    This is a hidden option; add it to the end of its section (`nhyd_model`).
+
+👆 Note that we have set a much smaller time step than in the {ref}`coarse global example <global-namelist-run>`,
+we turn on application of LBCs,
 we use the default RT interval,
 and we have selected the convection-permitting physics suite.
 

03-viz.ipynb

@@ -14,7 +14,7 @@
     "---\n",
     "title: Viz\n",
     "subtitle: Visualizing native-grid output in Python\n",
-    "label: viz\n",
+    "label: page:viz\n",
     "---"
    ]
   },
@@ -29,7 +29,7 @@
     "tags": []
    },
    "source": [
-    "With unstructured-grid data, the grid/coordinate information is usually stored in a separate file from the model output fields. Considerably more information is needed to reconstruct the grid than in the case of a rectangular lat/lon grid, for example, which can be expressed with 1-D coordinate variables.\n",
+    "With unstructured-grid data, the grid/coordinate information is usually stored in a separate file from the model output fields. Considerably more information is needed to reconstruct the grid than in the case of a rectangular lat/lon grid, for example, which can be expressed with 1-D coordinate variables (e.g. ERA5).\n",
     "\n",
     "With MPAS-A, the necessary grid variables are available in multiple files:\n",
     "\n",
@@ -632,6 +632,8 @@
    "id": "270910cf-d6df-4846-b644-39def35d008a",
    "metadata": {},
    "source": [
+    "(sec:geovista)=\n",
+    "\n",
     "# GeoVista\n",
     "\n",
     "Built on PyVista/VTK, [GeoVista](https://geovista.readthedocs.io/) provides GPU-accelerated interactive visualization of geospatial data and has [builtin support](https://geovista.readthedocs.io/en/v0.5.3/reference/generated/api/geovista/bridge/#geovista.bridge.Transform.from_unstructured) for unstructured meshes.\n",

04-regrid.md

@@ -1,7 +1,7 @@
 ---
 title: Regrid
 subtitle: Tools for regridding MPAS-A output to regular lat-lon grids
-label: regrid
+label: page:regrid
 ---
 
 # Options
@@ -18,7 +18,7 @@ and works with global and limited-area meshes.
 
 pyremap [is available](https://mpas-dev.github.io/pyremap/2.1.0/quick_start.html#installation) on conda-forge.
 
-In the below example, we use the data we downloaded in {ref}`viz`.
+In the below example, we use the data we downloaded in {ref}`page:viz`.
 
 ```{include} pyremap-example.py
 :lang: python
@@ -65,7 +65,7 @@ On Casper/Derecho:
 module load nco
 ```
 
-Let's use the grid data we downloaded in {ref}`viz`.
+Let's use the grid data we downloaded in {ref}`page:viz`.
 
 ```bash
 ln -s x1.2562.grid.nc grid.nc
@@ -167,7 +167,7 @@ module load cdo
 ```
 
 Global regridding with CDO is straightforward.
-As in the [NCO example](#nco-examples), we can use the data from {ref}`viz`,
+As in the [NCO example](#nco-examples), we can use the data from {ref}`page:viz`,
 aliased to `grid.nc` and `static.nc`.
 
 ```bash
@@ -208,7 +208,7 @@ Now we can use the `convert_mpas` command[^rc].
 
 ### Examples
 
-Here we use the data from our global run in {ref}`run`.
+Here we use the data from our global run in {ref}`page:run`.
 
 ```bash
 # Default 0.5-degree global, one file

myst.yml

@@ -17,6 +17,11 @@ project:
       email: [email protected]
       url: https://zmoon.info
   github: https://github.com/NunezOcasioLab/mpas-tutorial
+  error_rules:
+    - rule: link-resolves
+      severity: ignore
+      keys:
+        - https://sigma.mcs.anl.gov/category/moab/ # 403
 site:
   template: book-theme
   options: