Merge branch 'bishtgautam/doc/top-parameterization'(PR #5980)

Adds the technical documentation for parameterization of the topographic solar radiation.

[BFB]

.github/workflows/e3sm-gh-pages.yml

@@ -29,7 +29,7 @@ jobs:
         with:
           python-version: "3.10"
       - name: Install python deps
-        run: python3 -m pip install mkdocs-material pymdown-extensions mkdocs-monorepo-plugin mdutils
+        run: python3 -m pip install mkdocs-material pymdown-extensions mkdocs-monorepo-plugin mdutils mkdocs-bibtex
       # build every time (PR or push to master)
       - name: Build
         run: mkdocs build --strict --verbose

components/elm/docs/dev-guide/index.md

@@ -1 +1,4 @@
-start of the ELM Developer's Guide
+This guide contains information for developing ELM and MOSART.
+
+###
+* [Testing development branches](testing.md): Generating baselines and comparing new development against baselines

components/elm/docs/dev-guide/testing.md

@@ -0,0 +1,183 @@
+When a developer is ready to issue a PR to integrate their new developments into E3SM's `master` branch, they need to test their code development to ensure the new development does not introduce unexpected bugs. A land developer needs to atleast run the `e3sm_land_developer` test suite that involves following two steps: 
+
+- **Step-1**: Generate the baselines using the hash on `master` that was the starting point of the 
+  development branch, and
+- **Step-2**: Switch to the development branch and re-run the test suite to compare against 
+  the baselines generated in Step-1.
+
+For the purpose of these document, let's assume the developer branch is `bishtgautam/lnd/emi-example`.
+
+## Step-1: Generate Baselines
+
+Find the starting hash on `master` by switching to the developer branch and looking at the Git
+graph.
+
+```bash
+cd <e3sm-dir>
+
+# Switch to your branch
+git checkout bishtgautam/lnd/emi-example
+
+# Let's look at the graph
+git log --oneline --decorate --graph
+* 9a2cd8459 (HEAD -> bishtgautam/lnd/emi-example, origin/bishtgautam/lnd/emi-example) Updates the Stub EM code
+* d11fb8c52 Adds a readme and makefile for EMI Demo code
+* 15a0e4b8d Minor update to the EMI demo code
+* 63e2f6dcd Minor fix to ELM configure script
+* 551fc79cc Updates ELM stub and demo code to use CNCarbonStateType
+* 8c9d41f87 Adds code to exchange CNCarbonStateType
+* 0000ded51 Minor fix
+* 2baa4ebec Adds fixes to cmake
+* f77ae2cea Rename few cmake files
+* b48b66dd6 Adds a demo for a Stub EM
+* fa94aea0d Fixes length of variable to store name of EMI data
+* cca0e0be1 Adds capability to print all EMI Data in a list
+* beb1fe9ee Adds .gitignore files for EMI
+* 301acfe7a Renames ExternalModelInterfaceDataMod.F90
+* f0eb5b40b Renames ExternalModelInterfaceDataDimensionMod.F90
+* 076100882 Restructures ELM's EMI directory
+*   cfb7fc2b2 Merge branch 'qzhu-lbl/lnd/ch4_inundation_bugfix' (PR #2814)
+|\
+| * ec99b1cb4 (origin/qzhu-lbl/lnd/ch4_inundation_bugfix)  - fix ch4 inundatation parameter read in bug
+* |   c59c98116 Merge branch 'darincomeau/mpaso/enable_eddystats' (PR #2821)
+|\ \
+| * | c21bb46a4 Turn on eddy stats for oEC60to30v3 and oEC60to30v3wLI ocn grids by default
+* | |   a2dd2fce5 Merge pull request #2811 from E3SM-Project/jayeshkrishna/pio2_cime_changes
+```
+
+The above Git graph tells us that `bishtgautam/lnd/emi-example` started with the `cfb7fc2b2` hash on the `master`. So, we will generate the baselines using `cfb7fc2b2`. Checkout `cfb7fc2b2` and update the submodels via:
+
+```bash
+git checkout cfb7fc2b2
+Note: checking out 'cfb7fc2b2'.
+
+You are in 'detached HEAD' state. You can look around, make experimental
+changes and commit them, and you can discard any commits you make in this
+state without impacting any branches by performing another checkout.
+
+If you want to create a new branch to retain commits you create, you may
+do so (now or later) by using -b with the checkout command again. Example:
+
+  git checkout -b <new-branch-name>
+
+HEAD is now at cfb7fc2b2... Merge branch 'qzhu-lbl/lnd/ch4_inundation_bugfix' (PR #2814)
+
+git submodule update --init
+```
+
+Now we will use `cime/scripts/create_test` to generate baseline for the `e3sm_land_developer`
+test suite.
+
+```bash
+cd cime/scripts
+```
+
+A few things that you need to decide at this stage include the directory location where the baselines will be saved, the name and ID for the baselines, the project allocation that you will use for running the simulation, if you would like to recieve email notirications about tests, etc.
+
+```bash
+# Define the directory to hold the baseline 
+export MY_BASELINE_DIR=/global/cscratch1/sd/gbisht/e3sm_baselines
+
+# Do you want to use a name for the baseline? 
+# One choice could be the git hash that is being used to generate the baselines.
+export BASELINE_NAME=cfb7fc2b2
+
+# Let's set TEST_ID to be same as BASELINE_NAME
+export TEST_ID=${BASELINE_NAME}
+
+# If you are a member of E3SM, you could use 'e3sm' project allocation
+export PROJECT=e3sm
+
+# Set your email
+export MAIL_USER=<your-mail@something>
+
+```
+
+Use `./create_test --help` to get a complete list of arguments. Below are some additional
+useful arguments for `./create_test`:
+
+```bash
+# Other arguments
+# -v         : Verbose option
+# -g         : Generate the baseline
+# -q         : If you want to use a particular job queue (e.g. 'debug' queue on NERSC)
+# --walltime : Specify the wall time for jobs (e.g. 30 min is max allowable for 'debug' queue on NERSC)
+# --mail-user: If you want to receive emails about your jobs
+# --mail-type: When to receive emails. Options are: never, all, begin, end, fail.
+# -j         : Number of parallel jobs
+```
+
+Now run the `e3sm_land_developer`
+
+```bash
+./create_test e3sm_land_developer  \
+--baseline-root ${MY_BASELINE_DIR} \
+-b ${BASELINE_NAME}                \
+-t ${TEST_ID}                      \
+-q regular                         \
+-p ${PROJECT}                      \
+--walltime 00:30:00                \
+--mail-user $MAIL_USER             \
+--mail-type all                    \
+-g                                 \
+-v                                 \
+-j 4
+```
+
+The cases would be named `*.G.*` to denote one is generating the baselines.
+It will take a while to compile all the cases and submit the code.
+After the cases have been successfully compiled and submitted, you can check that 
+status of test by running the `cs.status.${TEST_ID}` file that was created in the scratch directory.
+
+
+
+## Step-2: Compare against previously generated baselines
+
+Now, switch to the development branch and be sure to update submodules.
+
+
+```bash
+cd <e3sm-dir>
+git checkout bishtgautam/lnd/emi-example
+Previous HEAD position was cfb7fc2b2... Merge branch 'qzhu-lbl/lnd/ch4_inundation_bugfix' (PR #2814)
+Switched to branch 'bishtgautam/lnd/emi-example'
+Your branch is up-to-date with 'origin/bishtgautam/lnd/emi-example'.
+
+# Checkout the appropriate submodules
+git submodule update --init
+```
+
+Again initialize few settings.
+
+```bash
+cd cime/scripts
+
+# Let's use the settings as the last time
+export MY_BASELINE_DIR=/global/cscratch1/sd/gbisht/e3sm_baselines
+
+# IMPORTANT: One needs to use the same BASELINE_NAME as in Step-1 because one wants
+#            to compare against the baselines previously generated in Step-1.
+export BASELINE_NAME=cfb7fc2b2
+
+# You can use the hash at the tip of your branch as the ID
+export TEST_ID=9a2cd8459
+```
+
+Run the test suite and compare (via `-c`) against previously generated baselines.
+
+```bash
+./create_test e3sm_land_developer  \
+--baseline-root ${MY_BASELINE_DIR} \
+-b ${BASELINE_NAME}                \
+-t ${TEST_ID}                      \
+-q debug                           \
+--walltime 00:30:00                \
+--mail-user $MAIL_USER             \
+--mail-type all                    \
+-c                                 \
+-v                                 \
+-j 4
+```
+
+The cases would be named `*.C.*` to denote one is comparing against previously generated baselines. Similar to the last time, a new `cs.status.${TEST_ID}` would be created and
+you can check the status of test by running it.

components/elm/docs/refs.bib

@@ -0,0 +1,59 @@
+@article{hao2021parameterization,
+  title={A parameterization of sub-grid topographical effects on solar radiation in the E3SM Land Model (version 1.0): implementation and evaluation over the Tibetan Plateau},
+  author={Hao, Dalei and Bisht, Gautam and Gu, Yu and Lee, Wei-Liang and Liou, Kuo-Nan and Leung, L Ruby},
+  journal={Geoscientific Model Development},
+  volume={14},
+  number={10},
+  pages={6273--6289},
+  year={2021},
+  publisher={Copernicus GmbH},
+  doi={https://doi.org/10.5194/gmd-14-6273-2021}
+}
+
+@techreport{oleson2013clm45,
+  author      = "Oleson, K. and Lawrence, D. and Bonan, G. and Drewniak, B. and Huang, M. and Koven, C. and Subin, Z. M. and Swenson, S. C.",
+  title       = "Technical description of version 4.5 of the Community Land Model (CLM), NCAR Technical Note",
+  institution = "National Center for Atmospheric Research (NCAR)",
+  year        = "2013",
+  type        = "",
+  number      = "NCAR/TN-503+ STR",
+  address     = "Boulder, CO, USA",
+  month       = "",
+  note        = "",
+  doi         = "https://doi.org/10.5065/D6RR1W7M"
+}
+
+@article{lee2011parameterization,
+  title={Parameterization of solar fluxes over mountain surfaces for application to climate models},
+  author={Lee, Wei-Liang and Liou, KN and Hall, Alex},
+  journal={Journal of Geophysical Research: Atmospheres},
+  volume={116},
+  number={D1},
+  year={2011},
+  publisher={Wiley Online Library},
+  doi={https://doi.org/10.1029/2010JD014722}
+}
+
+@article{zakvsek2011sky,
+  title={Sky-view factor as a relief visualization technique},
+  author={Zak{\v{s}}ek, Klemen and O{\v{s}}tir, Kristof and Kokalj, {\v{Z}}iga},
+  journal={Remote sensing},
+  volume={3},
+  number={2},
+  pages={398--415},
+  year={2011},
+  publisher={MDPI},
+  doi={https://doi.org/10.3390/rs3020398}
+}
+
+@article{dozier1990rapid,
+  title={Rapid calculation of terrain parameters for radiation modeling from digital elevation data},
+  author={Dozier, Jeff and Frew, James},
+  journal={IEEE Transactions on geoscience and remote sensing},
+  volume={28},
+  number={5},
+  pages={963--969},
+  year={1990},
+  publisher={IEEE},
+  doi={https://doi.org/10.1109/36.58986}
+}

components/elm/docs/tech-guide/index.md

@@ -1 +1,3 @@
 start of the ELM Technical Guide
+
+- [TOP Parameterization](top_solar_parameterization.md): Solar Radiation ParaTopgraphic parameterization for

components/elm/docs/tech-guide/top_solar_parameterization.md

@@ -0,0 +1,103 @@
+The TOP solar radiation parameterization in ELM accounts for the effects of sub-grid topography on solar radiation flux, including the shadow effects and multi-scattering between adjacent terrain[@hao2021parameterization].
+
+## Overview
+
+The incoming solar radiation for a flat surface is composed of direct radiation ($F_{dir}^{PP}$) from sun, diffuse radiation ($F_{dif}^{PP}$) from sky, and coupled radiation ($F_{couple}^{PP}$) that represents surface reflected radiation that is further reflected or scattered by atmospheric particles. ELM v1.0 and ELM v2.0 assume flat surfaces and accounts for $F_{dir}^{PP}$ and $F_{dif}^{PP}$, while neglecting $F_{couple}^{PP}$. The solar radiation scheme of ELM v1.0 and  ELM v2.0 uses the two-stream approximations[@oleson2013clm45]. In contrast, the incoming solar radiation parametrization of Lee et al. (2011)[@lee2011parameterization] over mountainous regions includes five components (illustrated in Fig. 1): 
+
+1. direct flux ($F_{dir}^{TOP}$) represents photons that are transmitted from the sun to the ground surface without encountering any reflection or scattering, 
+2. the direct-reflected flux ($F_{rdir}^{TOP}$) represents photons that are not scattered photons reflected by surrounding terrain, 
+3. diffuse flux ($F_{dif}^{TOP}$) represents photons that are scattered by atmospheric particles but are not reflected by the ground surface, 
+4. diffuse-reflected flux ($F_{rdif}^{TOP}$) represents scattered photons reflected by surrounding terrain, and 
+5. coupled flux ($F_{couple}^{TOP}$) represents remaining photons that are reflected multiple times or scattered by ground surface and atmospheric particles.
+
+<figure markdown>
+  ![Image title](../figures/TOP_schematic.jpg)
+  <figcaption>
+  Fig 1.: A schematic diagram of the five components of incoming solar radiation over mountains adapted from Lee et al. (2011)[@lee2011parameterization]. The components of incoming solar radiation included are (1) direct flux, (2) diffuse flux, (3) direct-reflected flux, (4) diffuse-reflected flux, and (5) coupled flux. Local solar zenith angle (θ), sky view factor (V<sub>d</sub>), and terrain configuration factor (C<sub>T</sub>) are also marked.
+  </figcaption>
+</figure>
+
+$F_{dir}^{TOP}$ is different from $F_{dir}^{PP}$ because of the adjustment of solar illumination geometry and shadowing effects. $F_{dif}^{PP}$ is different from $F_{dif}^{TOP}$ because the sky hemisphere is occluded by adjacent terrain. Lee et al. (2011)[@lee2011parameterization] used the radiation fluxes over flat surfaces (i.e., $F_{dir}^{PP}$ and $F_{dif}^{PP}$) to calculate the radiation fluxes over mountainous terrain based on sub-grid topographic factors. The relative deviation ($f_{dir}$) of direct flux between flat surfaces and mountains under the same atmospheric condition is defined as follows
+
+$$
+\label{eqn_fdir}
+f_{dir} = \frac{F_{dir}^{TOP} - F_{dir}^{PP}}{F_{dir}^{PP}}
+$$
+
+The relative deviation ($f_{rdir}$) of direct-reflected flux over mountains to direct flux over flat surfaces is defined as follows:
+
+$$
+\label{eqn_frdir}
+f_{rdir} = \frac{F_{rdir}^{TOP}}{F_{dir}^{PP}}
+$$
+
+Similarly, the relative deviations ($f_{dif}$ and $f_{rdif}$) of diffuse and diffuse-reflected fluxes are expressed as follows:
+
+$$
+\label{eqn_fdif}
+f_{dif} = \frac{F_{dif}^{TOP} - F_{dif}^{PP}}{F_{dir}^{PP}}
+$$
+
+$$
+\label{eqn_frdif}
+f_{rdif} = \frac{F_{rdif}^{TOP}}{F_{dif}^{PP}}
+$$
+
+## Multiple Linear Regression Model of Lee et al. (2011)
+
+In theory, these four relative deviations (i.e., $f_{dir}$, $f_{rdir}$, $f_{dif}$ and $f_{rdif}$) depend on solar illumination geometry and sub-grid topographic distribution. Based on a series of 3D Monte Carlo photon tracing simulations, Lee et al. (2011)[@lee2011parameterization] built a multiple linear regression parameterization to predict these four relative deviations well. The parameterization of Lee et al. (2011)[@lee2011parameterization] uses four variables that include the standard deviation of elevation ($\sigma_h$) within a grid cell, grid-averaged values of cosine of the local solar incident angle ($\mu$), sky view factor ($\overline{V_d}$), and terrain configuration factor ($\overline{C_T}$). Lee et al. (2011)[@lee2011parameterization] parameterization is given as follows:
+
+$$\begin{bmatrix}
+f_{dir} \\
+f_{dif} \\
+f_{rdir} \\
+f_{rdif}
+\end{bmatrix}
+= \mathbf{A} \cdot 
+\begin{bmatrix}
+\overline{\mu} \\
+\sigma_h \\
+\overline{V_d} \\
+\overline{C_T} \\
+1
+\end{bmatrix}
+$$
+
+where $\mathbf{A}$ represents the fitted parameter matrix, which was obtained based on the data generated by the 3D Monte Carlo simulations. The sky view factor ($V_d$) represents the portion of visible sky limited by surrounding terrain[@zakvsek2011sky], while the terrain configuration factor ($C_T$), the counterpart of the sky view factor, represents the portion of surrounding terrain which is visible to the ground target[@dozier1990rapid]. For an unobstructed infinite slope with the slope of $\alpha$ and aspect of $\beta$ and a given solar illumination geometry (i.e., solar zenith angle, $SZA$, and solar azimuth angle, $SAA$), the cosine of the local solar incident angle ($\mu$) can be calculated by
+
+$$
+\mu = \cos(SZA) \cos(\alpha) + \sin(SZA) \sin(\alpha) \cos(SAA-\beta)
+$$
+
+The $SZA$ and $SAA$ are assumed to be constant within a grid cell, but $\alpha$ and $\beta$ vary within a grid cell. The grid cell average solar incident angle, , can be expressed as follows:
+
+$$
+\begin{eqnarray}
+\overline{\mu} &=& \overline{\cos(SZA) \cos(\alpha)} + \overline{\sin(SZA) \sin(\alpha) \cos(SAA-\beta)} \nonumber \\
+&=& \cos(SZA)  \overline{\cos(\alpha)} + 
+\sin(SZA) \cos(SAA) +
+\overline{\sin(\alpha) \cos(\beta)} + \nonumber \\
+& & \sin(SZA) \sin(SAA) +
+\overline{\sin(\alpha) \sin(\beta)}
+\end{eqnarray}
+$$
+
+where overlines represent grid-averaged values. To further improve the regression parameterization, $\mu$, $V_d$, and $C_T$ are normalized by $\cos(\alpha)$. The land surface albedo is adjusted, instead of modifying incoming solar radiation, to maintain the surface energy conservation and the consistency between the surface and the first levels of atmosphere above the surface (Lee et al., 2015). Specifically, to keep the absorbed solar radiation of the ground surface unchanged, Lee et al. (2015) built the relationship between direct ($\alpha_{dir}^{TOP}$) and diffuse ($\alpha_{dif}^{TOP}$) albedo over mountains and those ($\alpha_{dir}^{PP}$ and $\alpha_{dif}^PP$) over flat surfaces as follows:
+
+$$
+\begin{eqnarray}
+F_{dir}^{PP} (1 - \alpha_{dir}^{TOP}) &=& (F_{dir}^{TOP} + F_{rdir}^{TOP})(1 - \alpha_{dir}^{PP}) \label{eqn_fdir_pp} \\
+F_{dif}^{PP} (1 - \alpha_{dif}^{TOP}) &=& (F_{dif}^{TOP} + F_{rdif}^{TOP})(1 - \alpha_{dif}^{PP}) \label{eqn_fdif_pp}
+\end{eqnarray}
+$$
+
+Substituting Eqns \eqref{eqn_fdir}-\eqref{eqn_frdif} into Eqs \eqref{eqn_fdir_pp}-\eqref{eqn_fdif_pp} leads to
+
+$$
+\begin{eqnarray}
+\alpha_{dir}^{TOP} &=& 1 - (1 + f_{dir} + f_{rdir}) (1 - \alpha_{dir}^{PP}) \label{eqn_alb_dir_top} \\
+\alpha_{dif}^{TOP} &=& 1 - (1 + f_{dif} + f_{rdif}) (1 - \alpha_{dif}^{PP}) \label{eqn_alb_dif_top}
+\end{eqnarray}
+$$
+
+The parameterizations represented by Eqs. \eqref{eqn_linear_reg}, \eqref{eqn_alb_dir_top}, and \eqref{eqn_alb_dif_top} are implemented in ELM to account for the sub-grid topographic effects on solar radiation fluxes.

components/mosart/docs/dev-guide/index.md

@@ -1 +1 @@
-start of the MOSART Developer's Guide
+Please refer to the [ELM's Developer Guide](../../ELM/dev-guide/index.md) for MOSART development.

docs/javascript/mathjax.js

@@ -0,0 +1,14 @@
+window.MathJax = {
+  tex: {
+    tags: 'all',
+    inlineMath: [["\\(", "\\)"]],
+    displayMath: [["\\[", "\\]"]],
+    processEscapes: true,
+    processEnvironments: true
+  },
+};
+
+document$.subscribe(() => {
+  MathJax.typesetPromise()
+})
+