Merge Pull Request #2796 from E3SM-Project/scream/mahf708/docs/updates

Automatically Merged using E3SM Pull Request AutoTester
PR Title: move rad calls docs from tech to user, update nudging and aerocom docs
PR Author: mahf708
PR LABELS: AT: AUTOMERGE, documentation, AT: Integrate Without Testing

Author: E3SM-Bot

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

@@ -53,14 +53,14 @@ jobs:
         run: |
           echo "= The job was automatically triggered by a ${{github.event_name}} event."
 
-      - name: Set up Python 3.10
+      - name: Set up Python 3.11
         uses: actions/setup-python@v5.1.0
         with:
-          python-version: "3.10"
+          python-version: "3.11"
 
       - name: Install Python deps
         run: |
-          pip install mkdocs pymdown-extensions mkdocs-material mdutils
+          pip install mkdocs pymdown-extensions mkdocs-material mdutils mkdocs-bibtex
   
       - name: Generate EAMxx params docs
         working-directory: components/eamxx/scripts

components/eamxx/docs/refs/aerocom_cldtop.bib

@@ -0,0 +1,24 @@
+
+@techreport{tiedtke_ecmwf_1979,
+	address = {Shinfield Park, Reading},
+	type = {Technical {Report}},
+	title = {{ECMWF} model parameterisation of sub-grid scale processes},
+	language = {en},
+	institution = {ECMWF},
+	author = {Tiedtke, M. and Geleyn, J.-F. and Hollingsworth, A. and Louis, J.-F.},
+	month = jan,
+	year = {1979},
+	note = {10},
+	pages = {146},
+}
+
+@article{raisanen2004stochastic,
+  title={Stochastic generation of subgrid-scale cloudy columns for large-scale models},
+  author={R{\"a}is{\"a}nen, Petri and Barker, Howard W and Khairoutdinov, Marat F and Li, Jiangnan and Randall, David A},
+  journal={Quarterly Journal of the Royal Meteorological Society: A journal of the atmospheric sciences, applied meteorology and physical oceanography},
+  volume={130},
+  number={601},
+  pages={2047--2067},
+  year={2004},
+  publisher={Wiley Online Library}
+}

components/eamxx/docs/refs.bib renamed to components/eamxx/docs/refs/general.bib

@@ -1,6 +1,6 @@
-# The AeroCOM algorithm
+# The AeroCom algorithm
 
-The goal of the AeroCOM algorithm is to calculate properties at cloud top based on the AeroCOM recommendation. There are two main parts of the algorithm: probabilistically determining "cloud top" and then "calculating properties" at said cloud top.
+The goal of the AeroCom algorithm is to calculate properties at cloud top based on the AeroCom recommendation. There are two main parts of the algorithm: probabilistically determining "cloud top" and then "calculating properties" at said cloud top.
 
 We treat model columns independently, so we loop over all columns in parallel. We then loop over all layers in serial (due to needing an accumulative product), starting at 2 (second highest) layer because the highest is assumed to have no clouds. Let's take a photonic approach from above the model top. Let's say that $p_{k}$ is the probability of a photon passing through the layer $k$. We follow the maximum-random overlap assumption. In all cases, we assume the cloudiness (or cloudy fraction) is completely opaque.
 
@@ -24,4 +24,4 @@ $$c\Phi_{i,k} = \frac{cQ_{i,k}}{iQ_{i,k} + cQ_{i,k}}$$
 
 The thermodynamic phase is used only for cloud properties (e.g., cloud-top cloud droplet number concentration) or cloud content (e.g., cloud liquid content). Further, $X_{i,k}$ is the three-dimensional cloud property of interest which is needed if we are converting a property from three-dimensional ($X$) to its two-dimensional counterpart ($x$). "Other" properties here include temperature and pressure which are not dependent on the thermodynamic phase.
 
-A helpful references: Räisänen, P., Barker, H. W., Khairoutdinov, M. F., Li, J., & Randall, D. A. (2004). Stochastic generation of subgrid‐scale cloudy columns for large‐scale models. Quarterly Journal of the Royal Meteorological Society: A journal of the atmospheric sciences, applied meteorology and physical oceanography, 130(601), 2047-2067.
+Most studies in this topic refer a technical report by Tiedtke et al. (1979)[@tiedtke_ecmwf_1979]. Another more recent general reference that may be of interest is that of Räisänen et al. (2004)[@raisanen2004stochastic].

components/eamxx/docs/technical/aerocom_cldtop.md

@@ -1,6 +1,6 @@
 # EAMxx Technical Guide
 
-The goal of this document is to describe the specific equations, parameterizations, and numerical methods used in the current version of EAMxx. Because our master-branch implementation changes every time we make a new commit, this documentation will also evolve continuously. As such, documentation for master should always be considered to be preliminary and under construction. If you want trustworthy documentation, pull it from an official model release. 
+The goal of this document is to describe the specific equations, parameterizations, and numerical methods used in the current version of EAMxx. Because our master-branch implementation changes every time we make a new commit, this documentation will also evolve continuously. As such, documentation for master should always be considered to be preliminary and under construction. If you want trustworthy documentation, pull it from an official model release.
 
 ## Overview
 

components/eamxx/docs/technical/index.md

@@ -6,5 +6,33 @@ These extra diagnostics are optionally added to the main radiation call. The ext
 - Clean-clear-sky fluxes: the fluxes that would be present if there were neither aerosols nor clouds, and are calculated by adding an additional radiation call at the very beginning of the logic before the optics class is endowed with aerosol and cloud properties.
 - Clean-sky fluxes: the fluxes that would be present if there were no aerosols, and are calculated by adding an additional radiation call after substantiating an additional optics class, but not endowing it with aerosol properties.
 
-It was necessary to add an additional optics class because the original optics class is endowed with aerosols before clouds (in order to calculate the clear-sky fluxes).
+## Example setup (current as of April 2024)
+
 The extra calls are controlled by runtime flags `extra_clnclrsky_diag` and `extra_clnsky_diag` (they take either `true` or `false` as their values).
+
+```shell
+    ./atmchange extra_clnclrsky_diag=true
+    ./atmchange extra_clnsky_diag=true
+```
+
+Below is an example output file to output the extra (clean and clean-clear-sky) radiation diagnostics atop the atmosphere.
+
+```yaml
+%YAML 1.1
+---
+filename_prefix: monthly.outputs
+Averaging Type: Average
+Max Snapshots Per File: 1
+Fields:
+  Physics PG2:
+    Field Names:
+    - SW_clnclrsky_flux_up_at_model_top
+    - LW_clnclrsky_flux_up_at_model_top
+    - SW_clnsky_flux_up_at_model_top
+    - LW_clnsky_flux_up_at_model_top
+output_control:
+  Frequency: 1
+  frequency_units: nmonths
+  MPI Ranks in Filename: false
+
+```

components/eamxx/docs/technical/clean_clear_sky.md renamed to components/eamxx/docs/user/clean_clear_sky.md

@@ -0,0 +1,42 @@
+# Nudging in EAMxx
+
+Nudging is supported in EAMxx.
+Currently, it is possible to nudge EAMxx to the output from a different EAMxx run or to reanalysis. Nudging data can be on your model grid or an arbitrary coarser grid. Inline interpolating of finer-grid nudging data to a coarser model resolution isn't implemented yet but may be in the future.
+
+## Data to nudge towards
+
+The user is expected to prepapre (and then use `atmchange` to point to) nudging data files that are compliant with EAMxx specification.
+In practice, this means that the data files must contain variable names known to EAMxx (only U, V, T_mid, and qv are supported now).
+The files can be specified with an explicit list or via pattern matching.
+The files must contain an arbitary global attribute `case_t0`, and it is recommended to be the same as the time dimension unit (the files must be time-dimensioned).
+Finally, the dimension order must be such that `lev` is the last dimension, so most likely, the user must transpose the dimensions.
+
+## Pressure in the nudging data
+
+Pressure can be explicitly provided in the nudging data as time-varying `p_mid` corresponding to the option `TIME_DEPENDENT_3D_PROFILE` for `source_pressure_type`.
+Alternatively, the data can contain a time-invariant pressure variable `p_lev` corresponding to the option `TIME_DEPENDENT_3D_PROFILE` for `source_pressure_type`.
+
+## Weighted nudging for RRM applications
+
+In regionally refined model applications, it is possible to use weighted nudging, for example, to avoid nudging the refined region.
+To achieve that, the user can use `atmchange` to set `use_nudging_weights` (boolean) and provide `nudging_weights_file` that has the weight to apply for nudging (for example, zeros in the refined region).
+Currently, weighted nudging is only supported if the user provides the nudging data at the target grid.
+
+## Example setup (current as of April 2024)
+
+To enable nudging as a process, one must declare it in the `atm_procs_list` runtime parameter.
+
+```shell
+./atmchange physics::atm_procs_list="mac_aero_mic,rrtmgp,cosp,nudging"
+```
+
+The following options are needed to specify the nudging.
+
+```shell
+./atmchange nudging::nudging_filenames_patterns="/pathto/nudging_files/*.nc" # can provide file name explicitly here instead (or multiple patterns)
+./atmchange nudging::source_pressure_type=TIME_DEPENDENT_3D_PROFILE # see section on pressure
+./atmchange nudging::nudging_fields=U,V # can include qv, T_mid as well
+./atmchange nudging::nudging_timescale=21600 # in seconds
+```
+
+To gain a deeper understanding of these parameters and options, please refer to code implementation of the nudging process.

components/eamxx/docs/user/coarse_nudging.md

@@ -8,7 +8,8 @@ nav:
     - 'Model output': 'user/model_output.md'
     - 'Model input': 'user/model_input.md'
     - 'Runtime parameters': 'common/eamxx_params.md'
-    - 'Coarse nudging': 'user/coarse_nudging.md'
+    - 'Nudging': 'user/nudging.md'
+    - 'Extra radiation calls': 'user/clean_clear_sky.md'
   - 'Developer Guide':
     - 'Overview': 'developer/index.md'
     - 'Installation': 'common/installation.md'
@@ -26,8 +27,8 @@ nav:
       - 'Full model': 'developer/cime_testing.md'
       - 'CI and Nightly Testing': 'developer/ci_nightly.md'
   - 'Technical Guide':
-    - 'AeroCOM cloud top': 'technical/aerocom_cldtop.md'
-    - 'Extra radiation calls': 'technical/clean_clear_sky.md'
+    - 'Overview': 'technical/index.md'
+    - 'AeroCom cloud top': 'technical/aerocom_cldtop.md'
 
 edit_uri: ""
 
@@ -58,10 +59,16 @@ markdown_extensions:
       alternate_style: true
   - pymdownx.arithmatex:
       generic: true
+  - footnotes
 
 extra_javascript:
   # - javascript/mathjax.js
   - https://polyfill.io/v3/polyfill.min.js?features=es6
   - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
 
 repo_url: https://github.com/E3SM-Project/scream
+
+plugins:
+  - search
+  - bibtex:
+      bib_dir: docs/refs

components/eamxx/docs/user/nudging.md

@@ -158,7 +158,7 @@ void RRTMGPRadiation::set_grids(const std::shared_ptr<const GridsManager> grids_
   add_field<Computed>("dtau105"       , scalar3d_mid, nondim, grid_name);
   add_field<Computed>("sunlit"        , scalar2d    , nondim, grid_name);
   add_field<Computed>("cldfrac_rad"   , scalar3d_mid, nondim, grid_name);
-  // Cloud-top diagnostics following AeroCOM recommendation
+  // Cloud-top diagnostics following AeroCom recommendation
   add_field<Computed>("T_mid_at_cldtop", scalar2d, K, grid_name);
   add_field<Computed>("p_mid_at_cldtop", scalar2d, Pa, grid_name);
   add_field<Computed>("cldfrac_ice_at_cldtop", scalar2d, nondim, grid_name);
@@ -519,7 +519,7 @@ void RRTMGPRadiation::run_impl (const double dt) {
 
   Kokkos::deep_copy(d_dtau067,0.0);
   Kokkos::deep_copy(d_dtau105,0.0);
-  // Outputs for AeroCOM cloud-top diagnostics
+  // Outputs for AeroCom cloud-top diagnostics
   auto d_T_mid_at_cldtop = get_field_out("T_mid_at_cldtop").get_view<Real *>();
   auto d_p_mid_at_cldtop = get_field_out("p_mid_at_cldtop").get_view<Real *>();
   auto d_cldfrac_ice_at_cldtop =
@@ -996,7 +996,7 @@ void RRTMGPRadiation::run_impl (const double dt) {
       // Get IR 10.5 micron band for COSP
       auto idx_105 = rrtmgp::get_wavelength_index_lw(10.5e-6);
 
-      // Compute cloud-top diagnostics following AeroCOM recommendation
+      // Compute cloud-top diagnostics following AeroCom recommendation
       real1d T_mid_at_cldtop ("T_mid_at_cldtop", d_T_mid_at_cldtop.data() + m_col_chunk_beg[ic], ncol);
       real1d p_mid_at_cldtop ("p_mid_at_cldtop", d_p_mid_at_cldtop.data() + m_col_chunk_beg[ic], ncol);
       real1d cldfrac_ice_at_cldtop ("cldfrac_ice_at_cldtop", d_cldfrac_ice_at_cldtop.data() + m_col_chunk_beg[ic], ncol);

components/eamxx/mkdocs.yml

@@ -1047,7 +1047,7 @@ namespace scream {
             real1d &cldfrac_tot_at_cldtop, real1d &cdnc_at_cldtop,
             real1d &eff_radius_qc_at_cldtop, real1d &eff_radius_qi_at_cldtop) {
           /* The goal of this routine is to calculate properties at cloud top
-           * based on the AeroCOM recommendation. See reference for routine
+           * based on the AeroCom recommendation. See reference for routine
            * get_subcolumn_mask above, where equation 14 is used for the
            * maximum-random overlap assumption for subcolumn generation. We use
            * equation 13, the column counterpart.

components/eamxx/src/physics/rrtmgp/eamxx_rrtmgp_process_interface.cpp

@@ -122,7 +122,7 @@ namespace scream {
                 int ncol, int nlay, int ngpt, Real pmin, Real pmax,
                 const real2d& pmid, const real3d& cld_tau_gpt, real1d& cld_area);
         /*
-         * Return select cloud-top diagnostics following AeroCOM recommendation
+         * Return select cloud-top diagnostics following AeroCom recommendation
          */
         void compute_aerocom_cloudtop(
             int ncol, int nlay, const real2d &tmid, const real2d &pmid,

components/eamxx/src/physics/rrtmgp/scream_rrtmgp_interface.cpp

@@ -64,7 +64,7 @@ Fields:
       - rad_heating_pdel
       - sfc_flux_lw_dn
       - sfc_flux_sw_net
-      # AeroCOM in RRTMGP
+      # AeroCom in RRTMGP
       - cdnc_at_cldtop
       - cldfrac_tot_at_cldtop
       - cldfrac_liq_at_cldtop

components/eamxx/src/physics/rrtmgp/scream_rrtmgp_interface.hpp

@@ -17,7 +17,7 @@ Field Names:
   - sfc_flux_lw_dn
   - sfc_flux_sw_net
   - rad_heating_pdel
-  # AeroCOM in RRTMGP
+  # AeroCom in RRTMGP
   - cdnc_at_cldtop
   - cldfrac_tot_at_cldtop
   - cldfrac_liq_at_cldtop