Flags for range checks in CABLE vars (#225)

Fixes #225 Add 2 flags to range checks ``` check%ranges (0, 1, 2) - When to do the range checks NO_CHECK, ON_TIMESTEP, ON_WRITE check%exit (.true., .false.) - Whether to exit the program if range checks are done, and out of range - the other option is to provide a warning ``` - Checks are being done in the following stages 1. Parameters of `soil` and `veg` before running the spinloop 2. Parameters when creating the NetCDF output file (some of them clash with `soil` and `veg` but code can be refactored in the future to account for that) 3. Landuse variables I/O 4. Variables in creating restart file 5. Variables at every timestep - Redesign `cable_output` with introducing `generate_out_write_acc`, and `check_and_write` - Change the range checks to be done in `cable_write` during `cable_output`. - Make `output_inclusion_type` dependencies clear between group output and individual values Tested with `AU-Tum_2002-2017_OzFlux_Met` for `main` vs current commit.  ---- 📚 Documentation preview 📚: https://cable--287.org.readthedocs.build/en/287/
CABLE-LSM · Jun 26, 2024 · 0e8df87 · 0e8df87
1 parent 46830b3
commit 0e8df87
Show file tree

Hide file tree

Showing 21 changed files with 1,913 additions and 2,542 deletions.
diff --git a/.github/workflows/model-build-test-ci.yml b/.github/workflows/model-build-test-ci.yml
@@ -10,6 +10,6 @@ on:
 jobs:
   build:
     name: Build ${{ github.repository }} via spack
-    uses: access-nri/build-ci/.github/workflows/model-1-build.yml@983fb50caaf0fe7e93bb3b13e09e81a7b846f7d1
+    uses: access-nri/build-ci/.github/workflows/model-1-build.yml@3c0840d775d8f3d67cfeedb44173caa2682fa27e
     permissions:
-      packages: read
+      packages: read
diff --git a/build.bash b/build.bash
@@ -1,64 +1,66 @@
 #!/usr/bin/env bash
 
-nproc_default=4
+ncpus_default=4
 
 script_name=$(basename "${0}")
 
 show_help() {
     cat << EOF
-Usage: ./$script_name [OPTIONS]
+Usage: ./${script_name} [OPTIONS]
 
 Build script wrapper around CMake. Supplied arguments that do not match the
 options below will be passed to CMake when generating the build system.
 
 Options:
-      --clean   Delete build directory before invoking CMake.
-      --mpi     Compile MPI executable.
-      --compiler <compiler>
+  -c, --clean   Delete build directory before invoking CMake.
+  -m, --mpi     Compile MPI executable.
+  -C, --compiler <compiler>
                 Specify the compiler to use.
-  -j <jobs>     Specify the number of parallel jobs in the compilation. By
-                default this value is set to $nproc_default.
+  -n, --ncpus <ncpus>
+                Specify the number of parallel jobs in the compilation. By
+                default this value is set to ${ncpus_default}.
   -h, --help    Show this screen.
 
 Enabling debug mode:
 
   The release build is default. To enable debug mode, specify the CMake option
-  -DCMAKE_BUILD_TYPE=Debug when invoking $script_name.
+  -DCMAKE_BUILD_TYPE=Debug when invoking ${script_name}.
 
 Enabling verbose output from Makefile builds:
 
   To enable more verbose output from Makefile builds, specify the CMake option
-  -DCMAKE_VERBOSE_MAKEFILE=ON when invoking $script_name.
+  -DCMAKE_VERBOSE_MAKEFILE=ON when invoking ${script_name}.
 
 EOF
 }
 
-cmake_args=(-DCMAKE_BUILD_TYPE=Release)
+cmake_args=(-DCMAKE_BUILD_TYPE=Release -DCABLE_MPI=OFF)
 
 # Argument parsing adapted and stolen from http://mywiki.wooledge.org/BashFAQ/035#Complex_nonstandard_add-on_utilities
-while [ $# -gt 0 ]; do
-    case $1 in
-        --clean)
-            rm -r build
+while [ ${#} -gt 0 ]; do
+    case ${1} in
+        -c|--clean)
+            rm -r build bin
+            exit
             ;;
-        --mpi)
+        -m|--mpi)
             mpi=1
             cmake_args+=(-DCABLE_MPI="ON")
             ;;
-        --compiler)
-            compiler=$2
+        -C|--compiler)
+            compiler=${2}
             shift
             ;;
-        -j)
-            CMAKE_BUILD_PARALLEL_LEVEL=$2
+        -n|--ncpus)
+            CMAKE_BUILD_PARALLEL_LEVEL=${2}
             shift
             ;;
         -h|--help)
             show_help
             exit
             ;;
         ?*)
-            cmake_args+=("$1")
+            cmake_args+=("${1}")
             ;;
     esac
     shift
@@ -75,24 +77,23 @@ if hostname -f | grep gadi.nci.org.au > /dev/null; then
         intel)
             module add intel-compiler/2019.5.281
             compiler_lib_install_dir=Intel
+            [[ -n ${mpi} ]] && module add intel-mpi/2019.5.281
             ;;
         gnu)
             module add gcc/13.2.0
             compiler_lib_install_dir=GNU
+            [[ -n ${mpi} ]] && module add openmpi/4.1.4
             ;;
         ?*)
             echo -e "\nError: compiler ${compiler} is not supported.\n"
             exit 1
+            ;;
     esac
 
     # This is required so that the netcdf-fortran library is discoverable by
     # pkg-config:
     prepend_path PKG_CONFIG_PATH "${NETCDF_BASE}/lib/${compiler_lib_install_dir}/pkgconfig"
 
-    if [[ -n $mpi ]]; then
-        module add intel-mpi/2019.5.281
-    fi
-
     if module is-loaded openmpi; then
         # This is required so that the openmpi MPI libraries are discoverable
         # via CMake's `find_package` mechanism:
@@ -115,7 +116,7 @@ elif hostname -f | grep -E '(mc16|mcmini)' > /dev/null; then
     esac
 fi
 
-export CMAKE_BUILD_PARALLEL_LEVEL="${CMAKE_BUILD_PARALLEL_LEVEL:=$nproc_default}"
+export CMAKE_BUILD_PARALLEL_LEVEL="${CMAKE_BUILD_PARALLEL_LEVEL:=${ncpus_default}}"
 
 cmake -S . -B build "${cmake_args[@]}" &&\
 cmake --build build &&\

diff --git a/documentation/docs/css/cable.css b/documentation/docs/css/cable.css
@@ -1,5 +1,5 @@
 .md-grid {
    margin-left: auto;
    margin-right: auto;
-   max-width: 70rem;
-}
+   max-width: 120rem;
+}
diff --git a/documentation/docs/javascripts/mathjax.js b/documentation/docs/javascripts/mathjax.js
@@ -1,16 +1,21 @@
+//https://squidfunk.github.io/mkdocs-material/reference/math/#mathjax-docsjavascriptsmathjaxjs 
+
 window.MathJax = {
-    tex: {
-      inlineMath: [["\\(", "\\)"]],
-      displayMath: [["\\[", "\\]"]],
-      processEscapes: true,
-      processEnvironments: true
-    },
-    options: {
-      ignoreHtmlClass: ".*|",
-      processHtmlClass: "arithmatex"
-    }
-  };
-
-  document$.subscribe(() => { 
-    MathJax.typesetPromise()
-  })
+  tex: {
+    inlineMath: [["\\(", "\\)"]],
+    displayMath: [["\\[", "\\]"]],
+    processEscapes: true,
+    processEnvironments: true
+  },
+  options: {
+    ignoreHtmlClass: ".*|",
+    processHtmlClass: "arithmatex"
+  }
+};
+
+document$.subscribe(() => {
+  MathJax.startup.output.clearCache()
+  MathJax.typesetClear()
+  MathJax.texReset()
+  MathJax.typesetPromise()
+})
diff --git a/documentation/docs/user_guide/inputs/cable_nml.md b/documentation/docs/user_guide/inputs/cable_nml.md
@@ -50,7 +50,8 @@ applications. The following are annotated examples of cable.nml:
 | output%balances                  | logical            | .TRUE. .FALSE.                                             | .FALSE.                          | Output energy and water balances when .TRUE..                                                           |
 | output%grid                      | character(len=7)   | 'default' 'land' 'mask' 'ALMA'                             | 'default'                        | Output grid convention. `'land'` outputs land-only points, `'mask'` outputs masked spatial grids. `'ALMA'` uses the Assistance for Land-surface Modelling Activities convention. `'default'` uses the whichever convention the input meteorological file is using. |
 | output%averaging                 | character(len=7)   | 'all' 'daily' 'monthly' 'user6'                            | 'all'                            | Output averaging.                                                                                       |
-| check%ranges                     | logical            | .TRUE. .FALSE.                                             | uninitialised                    | Check input and output variables against valid ranges.                                                  |
+| check%ranges                     | integer            |  0 (`NO_CHECK`), 1 (`ON_TIMESTEP`), 2 (`ON_WRITE`)         | uninitialised                    | Check input and output variables at certain timesteps against valid ranges.                             |
+| check%exit                       | logical            | .TRUE. .FALSE.                                             | .FALSE.                          | Behaviour on failed range checks. If true , write to console and exit the program, else write to logfile as warning |
 | check%energy_bal                 | logical            | .TRUE. .FALSE.                                             | uninitialised                    | Check the energy balance.                                                                               |
 | check%mass_bal                   | logical            | .TRUE. .FALSE.                                             | uninttialised                    | Check the water/mass balance.                                                                           |
 | verbose                          | logical            | .TRUE. .FALSE.                                             | uninitialised                    | Write details of every grid cell initialisation and parameters to log.                                  |
@@ -160,7 +161,8 @@ applications. The following are annotated examples of cable.nml:
    output%veg       = .TRUE.  ! vegetation states
    output%params    = .TRUE.  ! input parameters used to produce run
    output%balances  = .TRUE.  ! energy and water balances
-   check%ranges     = .FALSE.  ! variable ranges, input and output
+   check%ranges     = 1  ! Range-checks on every timestep
+   check%exit = .TRUE.  ! Exit the program if range checks fail
    check%energy_bal = .TRUE.  ! energy balance
    check%mass_bal   = .TRUE.  ! water/mass balance
    verbose = .TRUE. ! write details of every grid cell init and params to log?

diff --git a/documentation/docs/user_guide/inputs/index.md b/documentation/docs/user_guide/inputs/index.md
@@ -0,0 +1,19 @@
+# Input files
+
+CABLE can be used in many configurations, in part determined by the input files supplied to the code.
+Table 1 lists the various input files used in offline CABLE. A description of each file can be accessed through the left navigation bar.
+
+
+## Table 1: CABLE input files for the offline case
+
+|   Input file         	 | Description |
+|------------------------|-------------|
+| cable.nml            	 | main configuration file for CABLE |
+| pft_params.nml       	 | default parameter values for each PFT |
+| cable_soilparm.nml   	 | default parameter values for each soil type |
+| pftlookup.csv        	 | default parameter values for CASA-CNP |          
+| Meteorological forcing | atmospheric forcing data for CABLE |
+| Surface forcing        | information about the surface characteristics |
+| Restart                | information from a previous CABLE run to restart a simulation | 
+
+