move rad calls docs from tech to user, update nudging and aerocom docs

components/eamxx/docs/technical/aerocom_cldtop.md

@@ -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,7 @@ $$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.
+Helpful pointers:
+
+- 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.
+- References in this ECMWF report: Tiedtke, M., Geleyn, J.-F., Hollingsworth, A., and Louis, J.-F.: ECMWF model parameterisation of sub-grid scale processes, Technical Report, ECMWF, Shinfield Park, Reading, 10, 1979.

components/eamxx/docs/user/clean_clear_sky.md

@@ -0,0 +1,83 @@
+# Clean- and clean-clear-sky diagnostics
+
+In order to decompose the aerosol effective radiative forcing, additional diagnostic radiation calls are needed.
+These extra diagnostics are optionally added to the main radiation call. The extra diagnostics are:
+
+- 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
+```
+
+An example output file with the additional radiation diagnostics requested.
+
+```yaml
+%YAML 1.1
+---
+filename_prefix: monthly.outputs
+Averaging Type: Average
+Max Snapshots Per File: 1
+Fields:
+  Physics PG2:
+    Field Names:
+    #2D vars
+    - SW_flux_up_at_model_top
+    - SW_flux_dn_at_model_top
+    - LW_flux_up_at_model_top
+    - SW_clnclrsky_flux_up_at_model_top
+    - LW_clnclrsky_flux_up_at_model_top
+    - SW_clrsky_flux_up_at_model_top
+    - LW_clrsky_flux_up_at_model_top
+    - SW_clnsky_flux_up_at_model_top
+    - LW_clnsky_flux_up_at_model_top
+    - SW_flux_dn_at_model_bot
+    - SW_clnclrsky_flux_dn_at_model_bot
+    - SW_clrsky_flux_dn_at_model_bot
+    - SW_clnsky_flux_dn_at_model_bot
+    - SW_flux_up_at_model_bot
+    - SW_clnclrsky_flux_up_at_model_bot
+    - SW_clrsky_flux_up_at_model_bot
+    - SW_clnsky_flux_up_at_model_bot
+    - LW_flux_dn_at_model_bot
+    - LW_clnclrsky_flux_dn_at_model_bot
+    - LW_clrsky_flux_dn_at_model_bot
+    - LW_clnsky_flux_dn_at_model_bot
+    - LW_flux_up_at_model_bot
+    - LongwaveCloudForcing
+    - ShortwaveCloudForcing
+    - ps
+    - SeaLevelPressure
+    - T_2m
+    - qv_2m
+    - surf_radiative_T
+    - VapWaterPath
+    - IceWaterPath
+    - LiqWaterPath
+    - RainWaterPath
+    - ZonalVapFlux
+    - MeridionalVapFlux
+    - surf_evap
+    - surf_sens_flux
+    - surface_upward_latent_heat_flux
+    - precip_liq_surf_mass_flux
+    - precip_ice_surf_mass_flux
+    - landfrac
+    - ocnfrac
+    - PotentialTemperature_at_700hPa
+    - PotentialTemperature_at_1000hPa
+    - omega_at_500hPa
+    - RelativeHumidity_at_700hPa
+output_control:
+  Frequency: 1
+  frequency_units: nmonths
+  MPI Ranks in Filename: false
+
+```

components/eamxx/docs/user/coarse_nudging.md

@@ -5,21 +5,23 @@ Instead, in EAMxx, it is possible to nudge from coarse data.
 This is done by remapping the coarse data provided by the user to the runtime physics grid of EAMxx.
 In order to enable nudging from coarse data, the user must provide nudging data at the coarse resolution desired and an appropriate     ncremap-compatible mapping file.
 
-## Example setup
+## Example setup (current as of April 2024)
 
 A user can produce coarse nudging data from running EAMxx or EAM at a ne30pg2 or any other applicable resolution.
-Additionally, several users in the E3SM projects have produced nudging data at the ne30pg2 resolution from the MERRA2 and ERA5 datasets.
-A limitation for now is that the nudging data must be provided explicitly, either as one file or as a list of files.
-This can be problematic for long list of files, but we are working on a solution to this problem.
+Additionally, several users in the E3SM projects have produced nudging data at the ne30pg2 resolution from the MERRA2 and ERA5 datasets. Then, to enable nudging as a process, one must declare it in the `atm_procs_list` runtime parameter.
 
-Let's say that the nudging data is provided as one file in the following path: `/path/to/nudging_data_ne4pg2_L72.nc`.
-Then, a mapping file is provided as `/another/path/to/mapping_file_ne4pg2_to_ne120pg2.nc`.
-Then if the physics grid is ne120pg2, the user must enable the nudging process, specify the nudging files, and provide the specifies the nudging data and a remap file.
-In other words, the following options are needed:
+```shell
+    ./atmchange physics::atm_procs_list="mac_aero_mic,rrtmgp,cosp,nudging"
+```
+
+The following options are needed to specify the nudging.
 
 ```shell
-./atmchange atm_procs_list=(sc_import,nudging,homme,physics,sc_export)
-./atmchange nudging_fields=U,V
-./atmchange nudging_filenames_patterns=/path/to/nudging_data_ne4pg2_L72.nc
-./atmchange nudging_refine_remap_mapfile=/another/path/to/mapping_file_ne4pg2_to_ne120pg2.nc
+    ./atmchange nudging::nudging_filenames_patterns="${PSCRATCH}/mo_ne45pg2_nudg_trim_merra/*.nc"
+    ./atmchange nudging::source_pressure_type=TIME_DEPENDENT_3D_PROFILE
+    ./atmchange nudging::nudging_fields=U,V
+    ./atmchange nudging::nudging_timescale=21600 #  6-hr
+    ./atmchange nudging::nudging_refine_remap_mapfile="${PSCRATCH}/map_ne45pg2_to_ne256pg2.trbilin.20240410.nc"
 ```
+
+To gain a deeper understanding of these parameters and options, please refer to the overarching nudging documentation.

components/eamxx/mkdocs.yml

@@ -9,6 +9,7 @@ nav:
     - 'Model input': 'user/model_input.md'
     - 'Runtime parameters': 'common/eamxx_params.md'
     - 'Coarse nudging': 'user/coarse_nudging.md'
+    - 'Extra radiation calls': 'user/clean_clear_sky.md'
   - 'Developer Guide':
     - 'Overview': 'developer/index.md'
     - 'Installation': 'common/installation.md'
@@ -26,8 +27,7 @@ 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'
+    - 'AeroCom cloud top': 'technical/aerocom_cldtop.md'
 
 edit_uri: ""
 

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

@@ -160,7 +160,7 @@ void RRTMGPRadiation::set_grids(const std::shared_ptr<const GridsManager> grids_
   add_field<Computed>("dtau105"       , scalar3d_layout_mid, nondim, grid_name);
   add_field<Computed>("sunlit"        , scalar2d_layout    , nondim, grid_name);
   add_field<Computed>("cldfrac_rad"   , scalar3d_layout_mid, nondim, grid_name);
-  // Cloud-top diagnostics following AeroCOM recommendation
+  // Cloud-top diagnostics following AeroCom recommendation
   add_field<Computed>("T_mid_at_cldtop", scalar2d_layout, K, grid_name);
   add_field<Computed>("p_mid_at_cldtop", scalar2d_layout, Pa, grid_name);
   add_field<Computed>("cldfrac_ice_at_cldtop", scalar2d_layout, nondim, grid_name);
@@ -521,7 +521,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 =
@@ -998,7 +998,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/src/physics/rrtmgp/scream_rrtmgp_interface.cpp

@@ -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/scream_rrtmgp_interface.hpp

@@ -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/tests/multi-process/dynamics_physics/homme_shoc_cld_p3_rrtmgp_pg2/output.yaml

@@ -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/tests/single-process/rrtmgp/output.yaml

@@ -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