Merge branch 'jinboxie/atm/e3smv3_oro_merge' into next (PR #6667)

Implementation of new orographic drag parameterization scheme to alleviate wind bias in E3SM

Add a new suite of orographic drag parameterization schemes into EAM.
It includes 4 components all combined in one module (i.e. subroutine gwdo2d).
The schemes include orographic gravity wave drag (oGWD, Xie et al.,2020),
flow-blocking drag (FBD, Xie et al.,2020), small-scale GWD (sGWD, Tsiringakis et al.,2017),
and turbulent-scale orographic form drag (TOFD, Beljaars et al., 2004).

The scheme is distributed by the interface named gwdo_gsd. The oGWD, FBD, and
sGWD are implemented in gw_drag.F90, while TOFD is implemented in clubb_intr.F90
to join the vertical diffusion process. Another change is in the startup_initialconds.F90
and gw_drag.F90 where the new topographic parameters (OA, OC, OL) are input into the model.

Although it is possible to turn each new scheme on/off individually, the only validated
config is to have them all on (and the original scheme off).

Technical guide for this scheme is available at
https://docs.e3sm.org/E3SM/EAM/tech-guide/orodrag/

[BFB] The new scheme is a stealth feature.

Author: wlin7

cime_config/tests.py

@@ -177,7 +177,7 @@
             )
         },
 
-        "e3sm_p3_developer" : {
+    "e3sm_p3_developer" : {
         "tests"   : (
             "ERP.ne4pg2_oQU480.F2010.eam-p3",
             "REP_Ln5.ne4pg2_oQU480.F2010.eam-p3",
@@ -189,6 +189,17 @@
             "ERS.ne4pg2_oQU480.F2010.eam-p3"
             )
         },
+	
+	"e3sm_orodrag_developer" : {
+        "tests"   : (
+            "ERP.ne4pg2_oQU480.F2010.eam-orodrag_ne4pg2",
+            "REP_Ln5.ne4pg2_oQU480.F2010.eam-orodrag_ne4pg2",
+            "PET.ne4pg2_oQU480.F2010.eam-orodrag_ne4pg2",
+            "PEM_Ln18.ne4pg2_oQU480.F2010.eam-orodrag_ne4pg2",
+            "SMS_Ln5.ne30pg2_EC30to60E2r2.F2010.eam-orodrag_ne30pg2",
+            "SMS_D_Ln5.ne4pg2_oQU480.F2010.eam-orodrag_ne4pg2"
+            )
+        },
 
     "e3sm_atm_integration" : {
         "inherit" : ("eam_preqx", "eam_theta"),

components/eam/bld/build-namelist

@@ -4093,13 +4093,24 @@ if ($waccm_phys or $cfg->get('nlev') >= 60) {
     add_default($nl, 'use_gw_oro'    , 'val'=>'.true.');
     add_default($nl, 'use_gw_front'  , 'val'=>'.true.');
     add_default($nl, 'use_gw_convect', 'val'=>'.true.');
+    add_default($nl, 'use_od_ls', 'val'=>'.false.');
+    add_default($nl, 'use_od_bl', 'val'=>'.false.');
+    add_default($nl, 'use_od_ss', 'val'=>'.false.');
+    add_default($nl, 'use_od_fd', 'val'=>'.false.');
 } else {
     add_default($nl, 'use_gw_oro'    , 'val'=>'.true.');
     add_default($nl, 'use_gw_front'  , 'val'=>'.false.');
     add_default($nl, 'use_gw_convect', 'val'=>'.false.');
+    add_default($nl, 'use_od_ls', 'val'=>'.false.');
+    add_default($nl, 'use_od_bl', 'val'=>'.false.');
+    add_default($nl, 'use_od_ss', 'val'=>'.false.');
+    add_default($nl, 'use_od_fd', 'val'=>'.false.');
 }
 add_default($nl, 'pgwv', 'val'=>'32');
 add_default($nl, 'gw_dc','val'=>'2.5D0');
+add_default($nl, 'od_ls_ncleff' ,'val'=>'3.D0');
+add_default($nl, 'od_bl_ncd'    ,'val'=>'3.D0');
+add_default($nl, 'od_ss_sncleff','val'=>'1.D0');
 
 if ($nl->get_value('use_gw_oro') =~ /$TRUE/io) {
     add_default($nl, 'effgw_oro');

components/eam/bld/namelist_files/namelist_defaults_eam.xml

@@ -127,7 +127,6 @@
 
 <!-- Topography -->
 <bnd_topo hgrid="64x128"  >atm/cam/topo/USGS-gtopo30_64x128_c050520.nc</bnd_topo>
-
 <bnd_topo hgrid="ne4np4"   npg="0">atm/cam/topo/USGS-gtopo30_ne4np4_16x.c20160612.nc</bnd_topo>
 <bnd_topo hgrid="ne4np4"   npg="2">atm/cam/topo/USGS-gtopo30_ne4np4pg2_16x_converted.c20200527.nc</bnd_topo>
 <bnd_topo hgrid="ne11np4"  npg="0">atm/cam/topo/USGS-gtopo30_ne11np4_16xconsistentSGH.c20160612.nc</bnd_topo>
@@ -1895,6 +1894,9 @@ with se_tstep, dt_remap_factor, dt_tracer_factor set to -1
 <gw_convect_plev_src_wind   phys="default">70000</gw_convect_plev_src_wind>
 <effgw_oro phys="default"> 0.375      </effgw_oro>
 <use_gw_energy_fix phys="default"> .true.      </use_gw_energy_fix>
+<od_ls_ncleff  phys="default"> 3.D0 </od_ls_ncleff>
+<od_bl_ncd     phys="default"> 3.D0 </od_bl_ncd>
+<od_ss_sncleff phys="default"> 1.D0 </od_ss_sncleff>
 <clubb_C14 phys="default"> 2.5D0      </clubb_C14>
 <clubb_tk1 phys="default"> 268.15D0   </clubb_tk1>
 <dust_emis_fact phys="default"> 13.8D0     </dust_emis_fact>

components/eam/bld/namelist_files/namelist_definition.xml

@@ -1078,6 +1078,48 @@ Whether or not to enable GWD brute-force energy fix.
 Default: set by build-namelist.
 </entry>
 
+<entry id="use_od_ls" type="logical" category="gw_drag"
+       group="phys_ctl_nl" valid_values="" >
+Whether or not to enable nonlinear orographic gravity wave drag (oGWD).
+Default: set by build-namelist.
+</entry>
+
+<entry id="use_od_bl" type="logical" category="gw_drag"
+       group="phys_ctl_nl" valid_values="" >
+Whether or not to enable flow-blocking drag (FBD).
+Default: set by build-namelist.
+</entry>
+
+<entry id="use_od_ss" type="logical" category="gw_drag"
+       group="phys_ctl_nl" valid_values="" >
+Whether or not to enable small-scale orographic GWD drag (sGWD).
+Default: set by build-namelist.
+</entry>
+
+<entry id="use_od_fd" type="logical" category="pbl"
+       group="phys_ctl_nl" valid_values="" >
+Whether or not to enable turbulent orographic form drag (TOFD).
+Default: set by build-namelist.
+</entry>
+
+<entry id="od_ls_ncleff" type="real" category="gw_drag"
+       group="oro_drag_nl" valid_values="" >
+Tuning parameter of orographic GWD (oGWD). See <varname>use_od_ls</varname>.
+Default: set by build-namelist.
+</entry>
+
+<entry id="od_bl_ncd" type="real" category="gw_drag"
+       group="oro_drag_nl" valid_values="" >
+Tuning parameter of flow-blocking drag (FBD). See <varname>use_od_bl</varname>.
+Default: set by build-namelist.
+</entry>
+
+<entry id="od_ss_sncleff" type="real" category="gw_drag"
+       group="oro_drag_nl" valid_values="" >
+Tuning parameter of small-scale GWD (sGWD). See <varname>use_od_ss</varname>.
+Default: set by build-namelist.
+</entry>
+
 <entry id="pgwv" type="integer" category="gw_drag"
        group="gw_drag_nl" valid_values="" >
 Gravity wave spectrum dimension (wave numbers are from -pgwv to pgwv).

components/eam/cime_config/testdefs/testmods_dirs/eam/orodrag_ne30pg2/user_nl_eam

@@ -0,0 +1,8 @@
+use_gw_oro=.false.
+use_od_ls=.true.
+use_od_bl=.true.
+use_od_ss=.true.
+use_od_fd=.true.
+
+
+bnd_topo='$DIN_LOC_ROOT/atm/cam/topo/USGS-gtopo30_ne30np4pg2_x6t-SGH_forOroDrag.c20241001.nc'

components/eam/cime_config/testdefs/testmods_dirs/eam/orodrag_ne4pg2/user_nl_eam

@@ -0,0 +1,7 @@
+use_gw_oro=.false.
+use_od_ls=.true.
+use_od_bl=.true.
+use_od_ss=.true.
+use_od_fd=.true.
+
+bnd_topo='$DIN_LOC_ROOT/atm/cam/topo/USGS-gtopo30_ne4np4pg2_16x_converted_forOroDrag.c20241019.nc'

components/eam/docs/figures/orodrag.png

@@ -16,6 +16,8 @@ This Technical Guide describes the physics of version 3 of the E3SM Atmospheric
 
 - [RRTMG](rrtmg.md): Parameterization of radiation.
 
+- [ORODRAG](orodrag.md): Parameterization of orographic drag
+
 - [MAM](mam.md): Primary parameterization schemes used to represent aerosols.
 
 - [VBS](vbs.md): Parameterization of secondary organic aerosols.

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

@@ -0,0 +1,35 @@
+# Orographic drag scheme
+
+## Overview
+
+The orographic drag schemes includes two main options: the default Gravity Wave Drag scheme of McFarlane (1987)[@mcfarlane_the_1987] and a new suite of orographic drag parameterization schemes. The new suite includes 4 components all combined in one module (i.e. subroutine gwdo2d). The schemes include orographic gravity wave drag (oGWD, Xie et al.,2020)[@xie_an_2020], flow-blocking drag (FBD, Xie et al.,2020)[@xie_an_2020], small-scale GWD (sGWD, Tsiringakis et al.,2017)[@tsiringakis_small_2020], and turbulent-scale orographic form drag (TOFD, Beljaars et al., 2004)[@beljaars_a_2020]. The oGWD and TOFD schemes are used to replace the default oGWD (McFarlane, 1987)[@mcfarlane_the_1987] and Turbulent Mountain Stress (TMS, documented on Richter et al., 2010)[@richter_the_2010] module in EAM, while the FBD and sGWD are added enhanced drag schemes. Each of the schemes are used to predict and add enhanced drags from surface to high level that would help decelerate the wind especially over the mountainous regions among the globe. The oGWD, FBD, and sGWD are implemented in gw_drag.F90, while TOFD is implemented in clubb_intr.F90 to join the vertical diffusion process. There are also new topographic parameters (orographic asymmetry [OA], orographic convexity [OC], effective orographic length [OL]) are input into the model for the new oGWD and FBD scheme implmented. The concept of each scheme is illustrate in the figure below. Currently, only the scheme of McFarlane (1987) is turned on as default in E3SMv3.0.
+
+![orodrag figure](../figures/orodrag.png)
+
+### Default oGWD scheme
+
+The current default oGWD scheme in E3SMv3.0 is from McFarlane (1987)[@mcfarlane_the_1987]. It is a linear orographic gravity wave drag scheme that parameterizes the subgrid process of vertical propagation of gravity wave originating from orographic source. The output from this scheme is a vertical profile of drag (or deceleration terms) when gravity wave breaks at higher levels and deposits momemtum flux to that level. This scheme is shown to improve the excessive westerly wind bias in the extratropics and the wind bias in the polar region. This scheme is turned on by default in E3SMv3.0.
+
+### Default TMS scheme
+
+The turbulent mountain stress (TMS) scheme is documented on Richter et al.,(2010)[@richter_the_2010]. It parameterizes the turbulent scale form drag (TOFD) through adding enhanced effective roughness length to the model. This method is justified by the observation that area-averaged wind sufficiently far above hilly terrain behave logarithmically. It leads to significant decrease of overspeed surface wind in the model. It is turned OFF in E3SMv3.0.
+
+### New oGWD scheme
+
+The Xie et al.(2020)[@xie_an_2020] oGWD scheme is a nonlinear orographic gravity wave drag scheme that parameterizes the subgrid oGWD (>5km). It includes both the linear oGWD like that of McFarlane (1987)[@mcfarlane_the_1987] and nonlinear oGWD like low-level wave breaking (LLWB). The LLWB downstream often results in downslope windstorm that can enhance the drag by several times that of linear oGWD. The incorporation of the nonlinear drag is by adding an "enhancement factor" that is a function of the higher moments of the orography, e.g. orographic asymmetry (OA), orographic convexity (OC), effective orographic length (OL).
+
+### FBD scheme
+
+The Xie et al.(2020)[@xie_an_2020] FBD scheme parameterizes the drag by flow blocked on the mountain flanks or flowing around the mountain under upstream stable conditions (>5km). It occurs when the mean flow does not have enough kinetic energy to traverse an obstacle and either stops upstream or diverges around the obstacle. This provides drag near the surface where the blocking occurs in addition to the oGWD.
+
+### TOFD scheme
+
+The TOFD scheme (Beljaars et al.,2004)[@beljaars_a_2020] parameterizes the drag generated by the shear stresses in the boundary layer when the flow encounters smaller obstacles (<5km). As airflow encounters an obstacle, it is disrupted, leading to the formation of eddies and vortices. These turbulent structures enhance mixing, allowing different layers of air to interact over a short distance. The intensity of the mixing is typically higher close to the obstacle, with rapid changes in velocity and direction of the airflow and can exhibit large control over the surface wind. It is an alternative scheme to the current TMS in E3SMv3. An important difference between the TOFD and TMS is that TOFD explicitly calculate the stress profile while TMS uses an enhanced effective roughtness length approach.
+
+### sGWD scheme
+
+The Tsiringakis et al.(2017)[@tsiringakis_small_2020] sGWD scheme parameterizes the small-scale orographic gravity wave drag (sGWD) within the relatively shallow stable boundary layer. Models applying the form drag such as TOFD schemes usually lack sufficient cyclonic filling and do not accurately represent the development of cyclones over land (Holstag 2006)[@holtslag_preface_2006]. This caused significant temperature bias that occurs due to runaway cooling at the surface. To bridge the gap of this missing drag in the boundary layer, studies have hypothesized that the missing drag can be generated by sGWD. sGWD occurs under the relative stable boundary layer with low winds where the turbulence is significantly reduced.
+
+## Namelist parameters
+
+[orodrag Namelist Parameters](../user-guide/namelist_parameters.md#orographic-drag-schemes)

components/eam/docs/tech-guide/orodrag.md

@@ -156,3 +156,20 @@
 | Parameter                 | Description                                                       | Default value          |
 | ------------------------- | ----------------------------------------------------------------- | ---------------------- |
 | `cosp_lite`       | This namelist sets cosp_ncolumns=10 and cosp_nradsteps=3 (appropriate for COSP statistics derived from seasonal averages), and runs MISR, ISCCP, MODIS, and CALIPSO lidar simulators (cosp_lmisr_sim=.true.,cosp_lisccp_sim=.true., cosp_lmodis_sim=.true.,cosp_llidar_sim=.true.).  | `false`                |
+
+## Orographic drag schemes
+
+| Parameter                 | Description                                                       | Default value          |
+| ------------------------- | ----------------------------------------------------------------- | ---------------------- |
+| `use_gw_oro`       | This namelist controls the default linear orographic gravity wave drag (oGWD) for E3SM, if used, the default oGWD is turned on.                                | `true`                |
+| `do_tms`           | This namelist controls the default Turbulent Mountain Stress (TMS) for E3SM, if used, the default TMS is turned on.                                 | `false`                |
+| `effgw_oro`        | Efficiency associated with orographic gravity waves.                                                                     | `0.375`                |
+| `tms_orocnst`      | Turbulent mountain stress parameter used when TMS calculation is turned on             | `1.0`                |
+| `tms_z0fac`        | Factor determining z_0 from orographic standard deviation [ no unit ] for TMS.                                                   | `0.75`                |
+| `use_od_ls`        | This namelist controls the new nonlinear oGWD, if used, the nonlinear oGWD is turned on. use_od_ls should not be used at the same time with use_gw_oro.                  | `false`                |
+| `use_od_bl`       | This namelist controls the Flow-blocking drag (FBD) scheme, if used, the FBD scheme is turned on.        | `false`                |
+| `use_od_ss`       | This namelist controls the small-scale GWD (sGWD) scheme, if used, the sGWD scheme is turned on.        | `false`                |
+| `use_od_fd`       | This namelist controls the Turbulent orographic form drag (TOFD) scheme, if used, the TOFD scheme is turned on.        | `false`                |
+| `od_ls_ncleff`    | Tuning parameter of nonlinear oGWD. Stands for effective resolution of the grid for oGWD. Scales the magnitude of nonlinear oGWD.         | `3`                |
+| `od_bl_ncd`       | Tuning parameter of FBD. Stands for bulk drag coefficient. Scales the magnitude of FBD.       | `3`                |
+| `od_ss_sncleff`   | Tuning parameter of sGWD. Stands for effective resolution of the grid for sGWD.Scales the magnitude of sGWD.        | `1`                |