Merge pull request NCAR#366 from climbfuji/update_dtc_develop_from_em…

…c_develop_and_collect_updates_20191205

dtc/develop: collect updates to CCPP physics 2019/12/05

physics/cires_ugwp.F90

@@ -135,7 +135,13 @@ end subroutine cires_ugwp_finalize
 ! -----------------------------------------------------------------------
 !  order = dry-adj=>conv=mp-aero=>radiation -sfc/land- chem -> vertdiff-> [rf-gws]=> ion-re
 ! -----------------------------------------------------------------------
-!>@brief The subroutine executes the CIRES UGWP
+!>@brief These subroutines and modules execute the CIRES UGWP Version 0
+!>\defgroup cires_ugwp_run Unified Gravity Wave Physics General Algorithm
+!> @{
+!! The physics of NGWs in the UGWP framework (Yudin et al. 2018 \cite yudin_et_al_2018) is represented by four GW-solvers, which is introduced in Lindzen (1981) \cite lindzen_1981, Hines (1997) \cite hines_1997, Alexander and Dunkerton (1999) \cite alexander_and_dunkerton_1999, and Scinocca (2003) \cite scinocca_2003. The major modification of these GW solvers is represented by the addition of the background dissipation of temperature and winds to the saturation criteria for wave breaking. This feature is important in the mesosphere and thermosphere for WAM applications and it considers appropriate scale-dependent dissipation of waves near the model top lid providing the momentum and energy conservation in the vertical column physics (Shaw and Shepherd 2009 \cite shaw_and_shepherd_2009). In the UGWP-v0, the modification of Scinocca (2003) \cite scinocca_2003 scheme for NGWs with non-hydrostatic and rotational effects for GW propagations and background dissipation is represented by the subroutine \ref fv3_ugwp_solv2_v0. In the next release of UGWP, additional GW-solvers will be implemented along with physics-based triggering of waves and stochastic approaches for selection of GW modes characterized by horizontal phase velocities, azimuthal directions and magnitude of the vertical momentum flux (VMF).
+!!
+!! In UGWP-v0, the specification for the VMF function is adopted from the GEOS-5 global atmosphere model of GMAO NASA/GSFC, as described in Molod et al. (2015) \cite molod_et_al_2015 and employed in the MERRRA-2 reanalysis (Gelaro et al., 2017 \cite gelaro_et_al_2017). The Fortran subroutine \ref slat_geos5_tamp describes the latitudinal shape of VMF-function as displayed in Figure 3 of Molod et al. (2015) \cite molod_et_al_2015. It shows that the enhanced values of VMF in the equatorial region gives opportunity to simulate the QBO-like oscillations in the equatorial zonal winds and lead to more realistic simulations of the equatorial dynamics in GEOS-5 operational and MERRA-2 reanalysis products. For the first vertically extended version of FV3GFS in the stratosphere and mesosphere, this simplified function of VMF allows us to tune the model climate and to evaluate multi-year simulations of FV3GFS with the MERRA-2 and ERA-5 reanalysis products, along with temperature, ozone, and water vapor observations of current satellite missions. After delivery of the UGWP-code, the EMC group developed and tested approach to modulate the zonal mean NGW forcing by 3D-distributions of the total precipitation as a proxy for the excitation of NGWs by convection and the vertically-integrated  (surface - tropopause) Turbulent Kinetic Energy (TKE). The verification scores with updated NGW forcing, as reported elsewhere by EMC researchers, display noticeable improvements in the forecast scores produced by FV3GFS configuration extended into the mesosphere.
+!!
 !> \section arg_table_cires_ugwp_run Argument Table
 !! \htmlinclude cires_ugwp_run.html
 !!

physics/cires_ugwp_triggers.F90

@@ -463,6 +463,10 @@ end subroutine get_spectra_tau_okw
 !
 !
 !      
+!>\ingroup cires_ugwp_run
+!> @{
+!!
+!!
       subroutine slat_geos5_tamp(im, tau_amp, xlatdeg, tau_gw)
 !=================
 ! GEOS-5 & MERRA-2 lat-dependent GW-source function  tau(z=Zlaunch) =rho*<u'w'>

physics/docs/ccpp_doxyfile

@@ -120,6 +120,7 @@ INPUT                  =  pdftxt/mainpage.txt     \
                           pdftxt/GFS_SAMF.txt     \
                           pdftxt/GFS_SAMFdeep.txt \
                           pdftxt/GFS_GWDC.txt     \
+                          pdftxt/UGWPv0.txt     \
                           pdftxt/GFS_SAMFshal.txt \
                           pdftxt/GFDL_cloud.txt   \
 ###                          pdftxt/GFS_SURFACE_PERT.txt    \
@@ -134,6 +135,7 @@ INPUT                  =  pdftxt/mainpage.txt     \
 ###                          pdftxt/GFSphys_namelist.txt    \
 ###                          pdftxt/GFS_STOCHY_PHYS.txt     \
                           pdftxt/suite_input.nml.txt    \
+                          pdftxt/NoahMP.txt \
 ### in-core MP
                         ../gfdl_fv_sat_adj.F90    \
 ### time_vary
@@ -172,6 +174,10 @@ INPUT                  =  pdftxt/mainpage.txt     \
                         ../sflx.f    \
                         ../namelist_soilveg.f   \
                         ../set_soilveg.f        \
+                        ../sfc_noahmp_drv.f \
+                        ../module_sf_noahmplsm.f90 \
+                        ../module_sf_noahmp_glacier.f90 \
+                        ../noahmp_tables.f90 \
 ### Sea Ice Surface
                         ../sfc_sice.f \
 ### PBL
@@ -199,6 +205,10 @@ INPUT                  =  pdftxt/mainpage.txt     \
 ### Shallow Convection
                         ../samfshalcnv.f \
                         ../cnvc90.f \
+### Unified Gravity Wave
+                        ../cires_ugwp.F90 \
+                        ../ugwp_driver_v0.F \
+                        ../cires_ugwp_triggers.F90 \
 ### Microphysics
 ###                        ../gscond.f \
 ###                        ../precpd.f \

physics/docs/pdftxt/NoahMP.txt

@@ -0,0 +1,41 @@
+/**
+\page NoahMP GFS NoahMP Land Surface Model
+\section des_noahmp  Description
+
+This implementation of the NoahMP Land Surface Model (LSM) is adapted from the version implemented in WRF v3.7 with additions by NOAA EMC staff to work with the UFS Atmosphere model. Authoritative documentation of the NoahMP scheme can be accessed at the following links:
+
+[University of Texas at Austin NoahMP Documentation](http://www.jsg.utexas.edu/noah-mp "University of Texas at Austin NoahMP Documentation")
+
+[NCAR Research Application Laboratory NoahMP Documentation](https://ral.ucar.edu/solutions/products/noah-multiparameterization-land-surface-model-noah-mp-lsm "NCAR RAL NoahMP Documentation")
+
+A primary reference for the NoahMP LSM is Niu et al. (2011) \cite niu_et_al_2011.
+
+The CCPP interface to the NoahMP LSM is a driving software layer on top of the actual NoahMP LSM. During the run sequence, code organization is as follows:
++ \ref noahmpdrv_run() calls
+ + \ref transfer_mp_parameters()
+ + \ref noahmp_options()
+ + \ref noahmp_options_glacier() and noahmp_glacier() if over the ice vegetation type (glacier)
+ + \ref noahmp_sflx() if over other vegetation types
+ + \ref penman()
+
+Note that noahmp_glacer() and noahmp_sflx() are the actual NoahMP codes.
+
+\section Default NoahMP LSM Options used in UFS atmosphere
++ Dynamic Vegetation (opt_dveg): 2 [On]
++ Canopy Stomatal Resistance (opt_crs): 1 [Ball-Berry]
++ Soil Moisture Factor for Stomatal Resistance (opt_btr): 1 [Noah soil moisture]
++ Runoff and Groundwater (opt_run): 1 [topmodel with groundwater (Niu et al. 2007 \cite niu_et_al_2007)]
++ Surface Layer Drag Coeff (opt_sfc): 1 [Monin-Obukhov]
++ Supercooled Liquid Water or Ice Fraction (opt_frz): 1 [no iteration (Niu and Yang, 2006 \cite niu_and_yang_2006)]
++ Frozen Soil Permeability (opt_inf): 1 [linear effects, more permeable (Niu and Yang, 2006, \cite niu_and_yang_2006)]
++ Radiation Transfer (opt_rad): 1 [modified two-stream (gap = f(solar angle, 3d structure ...)<1-fveg)]
++ Ground Snow Surface Albedo (opt_alb): 2 [class]
++ Partitioning Precipitation into Rainfall & Snowfall (opt_snf): 4 [use microphysics output]
++ Lower Boundary Condition of Soil Temperature (opt_tbot): 2 [tbot at zbot (8m) read from a file (original Noah)]
++ Snow/Soil Temperature Time Scheme (only layer 1) (opt_stc): 1 [semi-implicit; flux top boundary condition] 
+
+\section intra_noahmp Intraphysics Communication
+ +  GFS NoahMP LSM Driver (\ref arg_table_noahmpdrv_run)
+\section gen_al_noahmp General Algorithm of Driver
++ \ref general_noahmpdrv
+*/

physics/docs/pdftxt/UGWPv0.txt

@@ -0,0 +1,21 @@
+/**
+\page UGWPv0 Unified Gravity Wave Physics Version 0
+\section des_UGWP Description
+<!--brief introduction of gravity wave (GW) drag and the sources of GW (consistent as GWDC)-->
+Gravity waves (GWs) are generated by a variety of sources in the atmosphere including orographic GWs (OGWs; quasi-stationary waves) and non-orographic GWs (NGWs; non-stationary oscillations). The subgrid scale parameterization scheme for OGWs can be found in Section \ref GFS_GWDPS. This scheme represents the operational version of the subgrid scale orography effects in Version 15 of Global Forecast System (GFS).
+
+The NGW physics scheme parameterizes the effects of non-stationary subgrid-scale waves in the global atmosphere models extended into the stratosphere, mesosphere, and thermosphere. These non-stationary oscillations with periods bounded by Coriolis and Brunt-Väisälä frequencies and typical horizontal scales from tens to several hundreds of kilometers are forced by the imbalance of convective and frontal/jet dynamics in the troposphere and lower stratosphere (Fritts 1984 \cite fritts_1984; Alexander et al. 2010 \cite alexander_et_al_2010; Plougonven and Zhang 2014 \cite plougonven_and_zhang_2014). The NGWs propagate upwards and the amplitudes exponentially grow with altitude until instability and breaking of waves occur. Convective and dynamical instability induced by GWs with large amplitudes can trigger production of small-scale turbulence and self-destruction of waves. The latter process in the theory of atmospheric GWs is frequently referred as the wave saturation (Lindzen 1981 \cite lindzen_1981; Weinstock 1984 \cite weinstock_1984; Fritts 1984 \cite fritts_1984). Herein, “saturation” or "breaking" refers to any processes that act to reduce wave amplitudes due to instabilities and/or interactions arising from large-amplitude perturbations limiting the exponential growth of GWs with height. Background dissipation processes such as molecular diffusion and radiative cooling, in contrast, act independently of GW amplitudes. In the middle atmosphere, impacts of NGW saturation (or breaking) and dissipation on the large-scale circulation, mixing, and transport have been acknowledged in the physics of global weather and climate models after pioneering studies by Lindzen 1981 \cite lindzen_1981 and Holton 1983 \cite holton_1983. Comprehensive reviews on the physics of NGWs and OGWs in the climate research and weather forecasting highlighted the variety of parameterization schemes for NGWs （Alexander et al. 2010 \cite alexander_et_al_2010; Geller et al. 2013 \cite geller_et_al_2013; Garcia et al. 2017 \cite garcia_et_al_2017). They are formulated using different aspects of the nonlinear and linear propagation, instability, breaking and dissipation of waves along with different specifications of GW sources (Garcia et al. 2007 \cite garcia_et_al_2007; Richter et al 2010 \cite richter_et_al_2010; Eckermann et al. 2009 \cite eckermann_et_al_2009; Eckermann 2011 \cite eckermann_2011; Lott et al. 2012 \cite lott_et_al_2012).
+
+The current operational GFS physics parameterizes effects of stationary OGWs and convective GWs, neglecting the impacts of non-stationary subgrid scale GW physics. This leads to well-known shortcomings in the global model predictions in the stratosphere and upper atmosphere (Alexander et al. 2010 \cite alexander_et_al_2010; Geller et al. 2013). In order to describe the effects of unresolved GWs by dynamical cores in global forecast models, subgrid scales physics of stationary and non-stationary GWs needs to be implemented in the self-consistent manner under the Unified Gravity Wave Physics (UGWP) framework.
+
+The concept of UGWP and the related programming architecture implemented in FV3GFS was first proposed by CU-CIRES, NOAA Space Weather Prediction Center (SWPC) and Environmental Modeling Center (EMC) for the Unified Forecast System (UFS) with variable positions of the model top lids (Alpert et al. 2019 \cite alpert_et_al_2019; Yudin et al. 2016 \cite yudin_et_al_2016; Yudin et al. 2018 \cite yudin_et_al_2018). As above, the UGWP considers identical GW propagation solvers for OGWs and NGWs with different approaches for specification of subgrid wave sources. <!--Both deterministic (Garcia et al. 2017 \cite garcia_et_al_2017) and stochastic (Eckermann 2011 \cite eckermann_2011; Lott et al. 2012 \cite lott_et_al_2012) approaches for the excitation of NGWs in global models will be evaluated in the UGWP framework.--> The current set of the input and control parameters for UGWP version 0 (UGWP-v0) can select different options for GW effects including momentum deposition (also called GW drag), heat deposition, and mixing by eddy viscosity, conductivity and diffusion. The input GW parameters can control the number of directional azimuths in which waves can propagate, number of waves in single direction, and the interface model layer from the surface at which NGWs can be launched. Among the input parameters, the GW efficiency factors reflect intermittency of wave excitation. They can vary with horizontal resolutions, reflecting capability of the FV3 dynamical core to resolve mesoscale wave activity with the enhancement of model resolution. The prescribed distributions for vertical momentum flux (VMF) of NGWs have been employed in the global forecast models of NWP centers and reanalysis projects to ease tuning of GW schemes to the climatology of the middle atmosphere dynamics in the absence of the global wind data above about 35 km (Eckermann et al. 2009 \cite eckermann_et_al_2009; Molod et al. 2015 \cite molod_et_al_2015). These distributions of VMF qualitatively describe the general features of the latitudinal and seasonal variations of the global GW activity in the lower stratosphere, observed from the ground and space (Ern et al. 2018 \cite ern_et_al_2018). For the long-term climate projections, global models seek to establish communication between model physics and dynamics. This provides variable in time and space excitation of subgrid GWs under year-to-year variations of solar input and anthropogenic emissions (Richter et al 2010 \cite richter_et_al_2010; 2014 \cite richter_et_al_2014).
+
+Note that in the first release of UGWP (UGWP-v0), the momentum and heat deposition due to GW breaking and dissipation have been tested in the multi-year simulations and medium-range forecasts using FV3GFS-L127 configuration with top lid at about 80 km. In addition, the eddy mixing effects induced by instability of GWs are not activated in this version. Along with the GW heat and momentum depositions, GW eddy mixing is an important element of the Whole Atmosphere Model (WAM) physics, as shown in WAM simulations with the spectral dynamics (Yudin et al. 2018 \cite yudin_et_al_2018). The additional impact of eddy mixing effects in the middle and upper atmosphere need to be further tested, evaluated, and orchestrated with the subgrid turbulent diffusion of the GFS physics (work in progress). In UFS, the WAM with FV3 dynamics (FV3-WAM) will represent the global atmosphere model configuration extended into the thermosphere (top lid at ~600 km). In the mesosphere and thermosphere, the background attenuation of subgrid waves due to molecular and turbulent diffusion, radiative damping and ion drag will be the additional mechanism of NGW and OGW dissipation along with convective and dynamical instability of waves described by the linear (Lindzen 1981 \cite lindzen_1981) and nonlinear (Weinstock 1984 \cite weinstock_1984; Hines 1997 \cite hines_1997) saturation theories.
+
+\section intra_UGWPv0 Intraphysics Communication
+\ref arg_table_cires_ugwp_run
+
+\section gen_al_ugwpv0 General Algorithm
+\ref cires_ugwp_run
+
+*/

physics/docs/pdftxt/all_shemes_list.txt

@@ -19,6 +19,7 @@ parameterizations in suites.
 - \b Land \b Surface \b Model
  - \subpage GFS_NOAH
  - \subpage GSD_RUCLSM
+ - \subpage NoahMP
 
 - \b Cumulus \b Parameterizations
  - \subpage GFS_SAMF
@@ -44,6 +45,7 @@ parameterizations in suites.
 - \b Gravity \b Wave \b Drag
  - \subpage GFS_GWDPS 
  - \subpage GFS_GWDC
+ - \subpage UGWPv0
 
 - \b Surface \b Layer \b and \b Simplified \b Ocean \b and \b Sea \b Ice \b Representation
  - \subpage GFS_SFCLYR

physics/module_MP_FER_HIRES.F90

@@ -2395,7 +2395,8 @@ END SUBROUTINE EGCP01COLUMN_hr
 
 !-----------------------------------------------------------------------
 !>\ingroup hafs_famp
-      SUBROUTINE FERRIER_INIT_hr (GSMDT,MPI_COMM_COMP,MYPE,mpiroot,THREADS)
+      SUBROUTINE FERRIER_INIT_hr (GSMDT,MPI_COMM_COMP,MYPE,mpiroot,THREADS, &
+        errmsg,errflg)
 !-----------------------------------------------------------------------
 !-------------------------------------------------------------------------------
 !---  SUBPROGRAM DOCUMENTATION BLOCK
@@ -2448,11 +2449,13 @@ SUBROUTINE FERRIER_INIT_hr (GSMDT,MPI_COMM_COMP,MYPE,mpiroot,THREADS)
       INTEGER, PARAMETER :: MDR1=XMR1, MDR2=XMR2, MDR3=XMR3
 !
 !     VARIABLES PASSED IN
-      real,INTENT(IN) :: GSMDT
-      INTEGER,   INTENT(IN) :: MYPE 
-      INTEGER,   INTENT(IN) :: MPIROOT
-      INTEGER,   INTENT(IN) :: MPI_COMM_COMP
-      INTEGER,   INTENT(IN) :: THREADS
+      REAL,             INTENT(IN) :: GSMDT
+      INTEGER,          INTENT(IN) :: MYPE 
+      INTEGER,          INTENT(IN) :: MPIROOT
+      INTEGER,          INTENT(IN) :: MPI_COMM_COMP
+      INTEGER,          INTENT(IN) :: THREADS
+      CHARACTER(LEN=*), INTENT(OUT)   :: errmsg
+      INTEGER,          INTENT(OUT)   :: errflg
 !
 !-----------------------------------------------------------------------
 !     LOCAL VARIABLES
@@ -2486,12 +2489,11 @@ SUBROUTINE FERRIER_INIT_hr (GSMDT,MPI_COMM_COMP,MYPE,mpiroot,THREADS)
             ENDIF
           ENDDO
           IF (etampnew_unit1<0) THEN
-            write(0,*)'FERRIER_INIT_hr: Can not find unused fortran '  &
-                     ,'unit to read in lookup tables'
-            write(0,*)' ABORTING!'
-#ifdef MPI
-            call MPI_ABORT(MPI_COMM_COMP, rc, IRTN)
-#endif
+            errmsg = 'FERRIER_INIT_hr: Can not find unused fortran &
+                     &unit to read in lookup tables'
+            errmsg = trim(errmsg)//NEW_LINE('A')//' ABORTING!'
+            errflg = 1
+            RETURN 
           ENDIF
         ENDIF
 !