release/public-v5: update of scientific documentation

physics/GFS_GWD_generic.F90

@@ -1,4 +1,4 @@
-!> \file GFS_GWD_generic.f
+!> \file GFS_GWD_generic.F90
 !! This file contains the CCPP-compliant orographic gravity wave
 !! drag pre interstitial codes.
 

physics/GFS_MP_generic.F90

@@ -71,6 +71,7 @@ end subroutine GFS_MP_generic_pre_finalize
 
       end module GFS_MP_generic_pre
 
+!>\defgroup gfs_calpreciptype GFS Precipitation Type Diagnostics Module
 !> This module contains the subroutine that calculates 
 !! precipitation type and its post, which provides precipitation forcing
 !! to LSM.
@@ -82,8 +83,7 @@ module GFS_MP_generic_post
       subroutine GFS_MP_generic_post_init
       end subroutine GFS_MP_generic_post_init
 
-!>\defgroup gfs_calpreciptype GFS Precipitation Type Diagnostics Module
-!! \brief If dominant precip type is requested (i.e., Zhao-Carr MP scheme), 4 more algorithms in calpreciptype()
+!> \brief If dominant precip type is requested (i.e., Zhao-Carr MP scheme), 4 more algorithms in calpreciptype()
 !! will be called.  the tallies are then summed in calwxt_dominant(). For GFDL cloud MP scheme, determine convective 
 !! rain/snow by surface temperature;  and determine explicit rain/snow by rain/snow coming out directly from MP.
 !! 

physics/GFS_rad_time_vary.fv3.F90

@@ -1,5 +1,7 @@
-!>\file GFS_rad_time_vary.F90
+!>\file GFS_rad_time_vary.fv3.F90
 !!  Contains code related to GFS physics suite setup (radiation part of time_vary_step)
+
+!>\defgroup gfs_rad_time_vary_mod  GFS Radiation Time Update Module
    module GFS_rad_time_vary
 
       implicit none
@@ -10,13 +12,11 @@ module GFS_rad_time_vary
 
       contains
 
-!! \section arg_table_GFS_rad_time_vary_init Argument Table
+!> \section arg_table_GFS_rad_time_vary_init Argument Table
 !!
       subroutine GFS_rad_time_vary_init
       end subroutine GFS_rad_time_vary_init
 
-!>\defgroup mod_GFS_rad_time_vary GFS Radiation Time Update
-!> @{
 !> \section arg_table_GFS_rad_time_vary_run Argument Table
 !! \htmlinclude GFS_rad_time_vary_run.html
 !!
@@ -98,7 +98,6 @@ subroutine GFS_rad_time_vary_run (Model, Data, nthrds, errmsg, errflg)
          endif
 
       end subroutine GFS_rad_time_vary_run
-!> @}
 
 !> \section arg_table_GFS_rad_time_vary_finalize Argument Table
 !!

physics/GFS_rrtmg_post.F90

@@ -1,10 +1,10 @@
 !>\file GFS_rrtmg_post.f90
 !! This file contains
+
+!>\defgroup GFS_rrtmg_post_mod GFS RRTMG Scheme Post
        module GFS_rrtmg_post
        contains
 
-!>\defgroup GFS_rrtmg_post GFS RRTMG Scheme Post
-!! @{
 !> \section arg_table_GFS_rrtmg_post_init Argument Table
 !!
        subroutine GFS_rrtmg_post_init ()
@@ -203,5 +203,4 @@ end subroutine GFS_rrtmg_post_run
       subroutine GFS_rrtmg_post_finalize ()
       end subroutine GFS_rrtmg_post_finalize
 
-!! @}
       end module GFS_rrtmg_post

physics/GFS_rrtmg_pre.F90

@@ -1,14 +1,15 @@
 !> \file GFS_rrtmg_pre.f90
 !! This file contains
+
+!> \defgroup GFS_rrtmg_pre_mod GFS RRTMG Scheme Pre
+!! @{
       module GFS_rrtmg_pre
 
       public GFS_rrtmg_pre_run
 
       contains
 
-!> \defgroup GFS_rrtmg_pre GFS RRTMG Scheme Pre
-!! @{
-!! \section arg_table_GFS_rrtmg_pre_init Argument Table
+!> \section arg_table_GFS_rrtmg_pre_init Argument Table
 !!
       subroutine GFS_rrtmg_pre_init ()
       end subroutine GFS_rrtmg_pre_init
@@ -941,5 +942,5 @@ end subroutine GFS_rrtmg_pre_run
       subroutine GFS_rrtmg_pre_finalize ()
       end subroutine GFS_rrtmg_pre_finalize
 
-!! @}
       end module GFS_rrtmg_pre
+!! @}

physics/GFS_rrtmg_setup.F90

@@ -1,5 +1,7 @@
 !> \file GFS_rrtmg_setup.f90
 !! This file contains
+
+!> \defgroup GFS_rrtmg_setup_mod GFS RRTMG Scheme Setup
 module GFS_rrtmg_setup
 
    use physparam, only : isolar , ictmflg, ico2flg, ioznflg, iaerflg,&
@@ -38,9 +40,7 @@ module GFS_rrtmg_setup
 
    contains
 
-!> \defgroup GFS_rrtmg_setup GFS RRTMG Scheme Setup
-!! @{
-!! \section arg_table_GFS_rrtmg_setup_init Argument Table
+!> \section arg_table_GFS_rrtmg_setup_init Argument Table
 !! \htmlinclude GFS_rrtmg_setup_init.html
 !!
    subroutine GFS_rrtmg_setup_init (                                    &
@@ -818,5 +818,4 @@ subroutine radupdate( idate,jdate,deltsw,deltim,lsswr, me,        &
       end subroutine radupdate
 !-----------------------------------
 
-!! @}
 end module GFS_rrtmg_setup

physics/GFS_stochastics.F90

@@ -1,6 +1,8 @@
 !> \file GFS_stochastics.f90
 !! This file contains code previously in GFS_stochastics_driver.
 
+!>\defgroup gfs_stoch GFS Stochastics Physics Module
+!! This module
     module GFS_stochastics
 
       contains
@@ -12,9 +14,6 @@ subroutine GFS_stochastics_finalize()
       end subroutine GFS_stochastics_finalize
 
 
-!>\defgroup gfs_stoch GFS Stochastics Physics Module
-!! This module
-!> @{
 !> \section arg_table_GFS_stochastics_run Argument Table
 !! \htmlinclude GFS_stochastics_run.html
 !!
@@ -250,4 +249,3 @@ subroutine GFS_stochastics_run (im, km, kdt, do_sppt, use_zmtnblck, do_shum,
       end subroutine GFS_stochastics_run
 
     end module GFS_stochastics
-!> @}

physics/GFS_time_vary_pre.fv3.F90

@@ -1,6 +1,7 @@
-!> \file GFS_time_vary_pre.F90
+!> \file GFS_time_vary_pre.fv3.F90
 !!  Contains code related to GFS physics suite setup (generic part of time_vary_step)
 
+!>\defgroup gfs_time_vary_pre_mod  GFS Time Vary Pre Module
    module GFS_time_vary_pre
 
       use funcphys, only: gfuncphys

physics/cires_ugwp.F90

@@ -10,6 +10,7 @@
 !! 3. GW Effects: Unified representation of GW impacts on the "resolved" flow for all sources (energy-balanced schemes for momentum, heat and mixing).
 !! https://www.weather.gov/media/sti/nggps/Presentations%202017/02%20NGGPS_VYUDIN_2017_.pdf
 
+!>\defgroup cires_ugwp_run Unified Gravity Wave Physics General Algorithm
 module cires_ugwp
 
     use machine, only: kind_phys
@@ -136,8 +137,6 @@ end subroutine cires_ugwp_finalize
 !  order = dry-adj=>conv=mp-aero=>radiation -sfc/land- chem -> vertdiff-> [rf-gws]=> ion-re
 ! -----------------------------------------------------------------------
 !>@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.
@@ -398,5 +397,4 @@ subroutine cires_ugwp_run(do_ugwp, me,  master, im,  levs, ntrac, dtp, kdt, lonr
 
     end subroutine cires_ugwp_run
 !! @}
-!>@}
 end module cires_ugwp

physics/cires_ugwp_post.F90

@@ -1,11 +1,11 @@
 !>  \file cires_ugwp_post.F90
 !! This file contains
+
+!>\defgroup cires_ugwp_post_mod CIRES UGWP Scheme Post
 module cires_ugwp_post
 
 contains
 
-!>\defgroup cires_ugwp_post CIRES UGWP Scheme Post
-!! @{
 !> \section arg_table_cires_ugwp_post_init Argument Table
 !!
     subroutine cires_ugwp_post_init ()
@@ -79,5 +79,4 @@ end subroutine cires_ugwp_post_run
       subroutine cires_ugwp_post_finalize ()
       end subroutine cires_ugwp_post_finalize
 
-!! @}
 end module cires_ugwp_post