Merge branch 'main' into 230-replace-cable_gw_hydrof90-with-its-new-v…

…ersion
CABLE-LSM · Aug 26, 2024 · 1dd3724 · 1dd3724
2 parents fb4cc3b + 420ca49
commit 1dd3724
Show file tree

Hide file tree

Showing 59 changed files with 2,932 additions and 3,313 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/assets/re-review.png b/documentation/docs/assets/re-review.png
diff --git a/documentation/docs/assets/request_review.png b/documentation/docs/assets/request_review.png
diff --git a/documentation/docs/assets/review-comment.png b/documentation/docs/assets/review-comment.png
diff --git a/documentation/docs/assets/review-suggestion.png b/documentation/docs/assets/review-suggestion.png
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/developer_guide/contribution/resources/how_to.md b/documentation/docs/developer_guide/contribution/resources/how_to.md
@@ -81,4 +81,59 @@ Once you push at least one commit to a new branch, you can create a pull request
       ![how describe pr](../../../assets/describe_pr.png){ width="90%", align=right }
     </figure>
 
+## Review
+
+### Ask for a review
+
+To ask for a review, on the pull request screen, click on the Reviewers menu or its cog icon and choose the `CABLE-LSM/reviewers` team:
+    <figure markdown>
+      ![how request review](../../../assets/request_review.png){ width="90%", align=right }
+    </figure>
+
+### Understand a review
+
+Reviewers can either leave comments or suggestions during the review. All of these need to be resolved to finish the current review. The GitHub documentation has more information about reviews, in particular around [comments on PR][github-commentPR] and how to [incorporate feedback][github-feedback].
+
+#### Suggestions from the reviewer
+
+A reviewer can directly suggest a specific code change. These suggestions appear like this:
+    <figure markdown>
+       ![how review suggestion](../../../assets/review-suggestion.png){ width="90%", align=right }
+    </figure>
+
+These suggestions can be directly applied within GitHub without requiring the author to copy them to their own local branch. It is recommended to:
+
+- first apply the suggestions you agree with via GitHub
+- then update your local branch with `git pull`
+- apply other changes required by the review locally to the branch
+- and finally push the fully revised version to GitHub (`git push`)
+
+#### Comments from the reviewer
+
+These comments can be:
+
+- generic to the whole set of changes
+- attached to a specific file
+- or attached to a specific set of modified lines in a file
+
+Comments to a specific set of lines look like this:
+    <figure markdown>
+       ![how review comment](../../../assets/review-comment.png){ width="90%", align=right }
+    </figure>
+
+It shows the specific lines commented on and the comment from the reviewer and it allows to reply to that specific comment.
+
+Changes arising from these comments need to be applied on your local repository.
+
+### Request a re-review
+
+Once you have finished addressing all the comments from the reviewer, you should ask the reviewer to re-review the pull request:
+    <figure markdown>
+       ![how re-review](../../../assets/re-review.png){ width="90%", align=right }
+    </figure>
+
+You will only be able to merge you work after getting approval from a reviewer.
+
 [CABLE-repo]: https://github.com/CABLE-LSM/CABLE
+[github-commentPR]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request
+[github-feedback]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request
diff --git a/documentation/docs/developer_guide/contribution/review_guide.md b/documentation/docs/developer_guide/contribution/review_guide.md
@@ -1,5 +1,59 @@
 # Review guidelines
 
-!!! note "Available soon"
+All contributions to the CABLE land surface model will be reviewed before inclusion in the model. The review is intended to ensure submissions to CABLE are of the best quality and integrate correctly within the CABLE's code design.
 
-    The documentation is still a work in progress. This section will be made available soon.
+The review process checks that:
+
+- [the coding standards][coding-standards] have been applied
+- the documentation is understandable and follows at least the [minimum requirements][doc-min-req]
+- [the required test results][tests-req] are provided
+- the proposed changes address the problem explained in the issue and only this problem
+- the proposed changes are correct
+- the implementation of the changes follows the design of the CABLE model and will be maintainable
+
+## Final checks before asking for review
+
+Once you have finished the implementation of your changes and before asking for a review, please make sure:
+
+- the description of the pull request is up-to-date.
+- all the required test results are either linked to in comments or copied in. If you have performed tests beyond the required tests, make sure these tests and their results are described in comments in your pull request.
+- the automated checks pass. Contact the @CABLE-LSM/admin team, through a comment in your pull request, if you need help understanding a failure of these tests.
+- all conflicts have been solved.
+
+## Asking for review
+
+Once you are ready, [ask for a review by `CABLE-LSM/reviewers`][how-ask-review]. If you want a specific individual, you can use the same process to choose that person. Using the reviewers team is preferred as it will spread the workload across reviewers.
+
+In most cases, asking for one reviewer is enough. The system allows asking for multiple reviewers, please use this feature sparingly. It is often easier to ask for a single reviewer first and add another reviewer later as necessary.
+
+## Review process
+
+### Review response
+
+The reviewers team will try and reply to review requests quickly. If you think your review request has been lost, please ask for an update as a comment on your pull request and mention your reviewer (with @).
+
+The review is likely to be an iterative process between the reviewer and the author. As such, it is appreciated if you, the author, are responsive once the review process starts. Make sure to keep discussions polite and courteous. You can reject suggestions from reviewers but the reasoning has to be explained and the rejection has to be agreed to by the reviewer.
+
+[To incorporate code changes requested by the reviewer][how-review], you often need to incorporate these changes to your local repository and push them to GitHub again. It is possible for the reviewer to suggest changes that can be apply directly in GitHub. We recommend to:
+
+1. apply the suggestions you agree with via GitHub
+1. update your local branch with `git pull`
+1. apply other changes required by the review locally to your branch
+1. push the fully revised version to GitHub (`git push`)
+1. [ask for a re-review][how-re-review] once you have resolved all points raised by the reviewer
+
+The reviewer might ask for a complementary review by another individual if they think they are not able to review all aspects of a submission.
+
+To better understand the pull request interface for reviews on GitHub, please refer to [the GitHub documentation][github-review].
+
+### Merge approved submission
+
+Once a reviewer has approved the pull request, you can merge it. We prefer if the author merges the pull request as it provides you a last chance to spot an issue. However, the admin team will periodically merge any pull request approved some time ago and that has not been merged.
+
+[coding-standards]: ../other_resources/coding_standards.md
+[doc-min-req]: ../documentation_guidelines/index.md
+[tests-req]: testing.md
+[how-ask-review]: resources/how_to.md#ask-a-review
+[how-review]: resources/how_to.md#understand-a-review
+[how-re-review]: resources/how_to.md#request-a-re-review
+[github-review]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests
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/constants/index.md b/documentation/docs/user_guide/constants/index.md
@@ -0,0 +1,11 @@
+# CABLE constants
+
+Table 1 lists the various types of constants used in CABLE. A list of the numerical values of each type can be accessed through the left navigation bar.
+
+
+## Table 1: Various constants used in CABLE 
+
+|   CABLE constants   	 |
+|------------------------|
+| Physical constants   	 |
+| Mathematical constants |
diff --git a/documentation/docs/user_guide/constants/mathematical_constants.md b/documentation/docs/user_guide/constants/mathematical_constants.md
@@ -0,0 +1,5 @@
+## Table 1: CABLE mathematical constants
+
+| Name	                | Value            |
+|-----------------------|------------------|
+|  pi                   | 3.1415927        |
diff --git a/documentation/docs/user_guide/constants/physical_constants.md b/documentation/docs/user_guide/constants/physical_constants.md
@@ -0,0 +1,23 @@
+## Table 1: CABLE physical constants
+
+| Name	                | Value            | Units                                               | Description                                         |
+|-----------------------|------------------|-----------------------------------------------------|--------------------------------------------------   |
+|  tfrz                 | 273.16      	   | \( K \)	       				     	 |   Temperature corresponding to \( 0^{\circ}C \)     |
+|  sboltz               | 5.67E-8     	   | \( W \cdot m^{-2} \cdot K^{-4} \)                   |   Stefan-Boltzmann constant   	               |
+|  emsoil               | 1.0         	   | \(  -  \)           			      	 |   Soil emissivity                  	               |
+|  emleaf               | 1.0         	   | \(  -  \) 					      	 |   Leaf emissivity                  	               |
+|  capp                 | 1004.64     	   | \( J \cdot kg^{-1} \cdot K^{-1} \)                  |   Air specific heat                        	       |
+|  hl  	                | 2.5014E6    	   | \( J \cdot kg^{-1} \) 				 |   Latent heat of vaporization	               |
+|  hlf 	                | 0.334E6     	   | \( J \cdot kg^{-1} \)              	      	 |   Latent heat of fusion                             |
+|  hls 	                | 2.8350E6    	   | \( J \cdot kg^{-1} \) 			         |   Latent heat of Sublimation                        |
+|  dheat                | 21.5E-6     	   | \( cm^{2} \cdot s^{-1} \) 			      	 |   Molecular diffusivity for heat                    |
+|  grav                 | 9.8086      	   | \( m \cdot s^{-2} \) 			      	 |   Gravity acceleration                              |                             
+|  rgas                 | 8.3143      	   | \(J \cdot mol^{-1} \cdot K^{-1} \)                  |   Universal gas const 	                       |
+|  rmair                | 0.02897     	   | \( kg \cdot mol^{-1} \) 			      	 |   Molecular weight of dry air                       |
+|  rmh2o                | 0.018016    	   | \( kg \cdot mol^{-1} \) 			      	 |   Molecular weight of water                         |
+|  cgsnow               | 2090.0      	   | \( J \cdot kg^{-1} \cdot K^{-1} \)                	 |   Specific heat for snow	                       |           
+|  csice                | 2.100E3     	   | \( J \cdot kg^{-1} \cdot K^{-1} \)		      	 |   Specific heat for ice	                       |
+|  cswat                | 4.218E3     	   | \( J \cdot kg^{-1} \cdot K^{-1} \)		      	 |   Specific heat for water at \( 0^{\circ}C \)       |
+|  density_liq          | 1000.0      	   | \( kg \cdot m^{-3} \) 			      	 |   Density of liquid water                           |
+|  density_ice          | 921.0       	   | \( kg \cdot m^{-3} \) 			      	 |   Density of ice                                    |                
+