NCAR · grantfirl · Sep 5, 2024 · May 13, 2024 · Jun 10, 2024 · Jun 10, 2024
@@ -1,6 +1,7 @@
 !>\file cu_gf_deep.F90 
 !! This file is the Grell-Freitas deep convection scheme.
 
+!> This module contains the Grell_Freitas deep convection scheme
 module cu_gf_deep
      use machine , only : kind_phys
      use physcons, only : qamin

@@ -1,7 +1,7 @@
 !>\file cu_gf_driver.F90
 !! This file is scale-aware Grell-Freitas cumulus scheme driver.
 
-
+!> This module contains the scale-aware Grell-Freitas cumulus scheme driver.
 module cu_gf_driver
 
    ! DH* TODO: replace constants with arguments to cu_gf_driver_run

@@ -1,6 +1,7 @@
 !> \file cu_gf_driver_post.F90
 !!  Contains code related to GF convective schemes to be used within the GFS physics suite.
 
+!> This module contains code related to GF convective schemes to be used within the GFS physics suite
 module cu_gf_driver_post
 
    implicit none

@@ -1,6 +1,7 @@
 !> \file cu_gf_driver_pre.F90
 !!  Contains code related to GF convective schemes to be used within the GFS physics suite.
 
+!> This module contains code related to GF convective schemes to be used within the GFS physics suite.
 module cu_gf_driver_pre
 
    implicit none

@@ -1,6 +1,7 @@
 !>\file cu_gf_sh.F90
 !! This file contains Grell-Freitas shallow convection scheme.
 
+!> This module contains the Grell-Freitas shallow convection scheme
 module cu_gf_sh
     use machine , only : kind_phys
     !real(kind=kind_phys), parameter:: c1_shal=0.0015! .0005

@@ -1,3 +1,5 @@
+!>\file samfaerosols.F
+!!
       module samfcnv_aerosols
 
       implicit none

@@ -1,6 +1,7 @@
 !>  \file samfshalcnv.f
-!!  This file contains the Scale-Aware mass flux Shallow Convection scheme.
+!!
 
+!>  This module contains the Scale-Aware mass flux Shallow Convection scheme.
       module samfshalcnv
 
       use samfcnv_aerosols, only : samfshalcnv_aerosols

@@ -1,16 +1,12 @@
-!> \defgroup SASHAL Mass-Flux Shallow Convection
-!! @{
-!!  \brief The Mass-Flux shallow convection scheme parameterizes the effect of shallow convection on the environment much like the \ref SAS scheme with a few key modifications. Perhaps most importantly, no quasi-equilibrium assumption is necessary since the shallow cloud base mass flux is parameterized from the surface buoyancy flux. Further, there are no convective downdrafts, the entrainment rate is greater than for deep convection, and the shallow convection is limited to not extend over the level where \f$p=0.7p_{sfc}\f$.
+!> \file shalcnv.F
+!!  Contains the entire SAS shallow convection scheme.
+
+!>  \brief The Mass-Flux shallow convection scheme parameterizes the effect of shallow convection on the environment much like the \ref SAS scheme with a few key modifications. Perhaps most importantly, no quasi-equilibrium assumption is necessary since the shallow cloud base mass flux is parameterized from the surface buoyancy flux. Further, there are no convective downdrafts, the entrainment rate is greater than for deep convection, and the shallow convection is limited to not extend over the level where \f$p=0.7p_{sfc}\f$.
 !!
 !!  This scheme was designed to replace the previous eddy-diffusivity approach to shallow convection with a mass-flux based approach as it is used for deep convection. Differences between the shallow and deep SAS schemes are presented in Han and Pan (2011) \cite han_and_pan_2011 . Like the deep scheme, it uses the working concepts put forth in Arakawa and Schubert (1974) \cite arakawa_and_schubert_1974 but includes modifications and simplifications from Grell (1993) \cite grell_1993 such as only one cloud type (the deepest possible, up to \f$p=0.7p_{sfc}\f$), rather than a spectrum based on cloud top heights or assumed entrainment rates, although it assumes no convective downdrafts. It contains many modifications associated with deep scheme as discussed in Han and Pan (2011) \cite han_and_pan_2011 , including the calculation of cloud top, a greater CFL-criterion-based maximum cloud base mass flux, and the inclusion of convective overshooting.
 !!
-!!  \section diagram Calling Hierarchy Diagram
+!!  \section diagram_sashal Calling Hierarchy Diagram
 !!  \image html Shallow_SAS_Flowchart.png "Diagram depicting how the SAS shallow convection scheme is called from the GSM physics time loop" height=2cm
-!!  \section intraphysics Intraphysics Communication
-!!  This space is reserved for a description of how this scheme uses information from other scheme types and/or how information calculated in this scheme is used in other scheme types.
-
-!> \file shalcnv.F
-!!  Contains the entire SAS shallow convection scheme.
       module shalcnv
 
       implicit none
@@ -80,17 +76,17 @@ end subroutine shalcnv_init
 !!  \param[out] cnvw convective cloud water (kg/kg)
 !!  \param[out] cnvc convective cloud cover (unitless)
 !!
-!!  \section general General Algorithm
+!!  \section general_shalcnv General Algorithm
 !!  -# Compute preliminary quantities needed for the static and feedback control portions of the algorithm.
 !!  -# Perform calculations related to the updraft of the entraining/detraining cloud model ("static control").
 !!  -# Calculate the tendencies of the state variables (per unit cloud base mass flux) and the cloud base mass flux.
 !!  -# For the "feedback control", calculate updated values of the state variables by multiplying the cloud base mass flux and the tendencies calculated per unit cloud base mass flux from the static control.
-!!  \section detailed Detailed Algorithm
+!!  \section detailed_shalcnv Detailed Algorithm
 !!
 !! \section arg_table_shalcnv_run Argument Table
 !! \htmlinclude shalcnv_run.html
 !!
-!!  @{
+!>  @{
       subroutine shalcnv_run(                                           &
      &     grav,cp,hvap,rv,fv,t0c,rd,cvap,cliq,eps,epsm1,               &
      &     im,km,jcap,delt,delp,prslp,psp,phil,qlc,qli,                 &
@@ -1341,4 +1337,3 @@ end subroutine shalcnv_run
 
       end module shalcnv
 !> @}
-!! @}
@@ -1,3 +1,9 @@
+!>\file progsigma_calc.f90
+
+!> This module contains the subroutine that calculates the prognostic
+!! updraft area fraction that is used for closure computations in
+!! saSAS deep and shallow convection, based on a moisture budget
+!! as described in Bengtsson et al. 2022 \cite Bengtsson_2022.
       module progsigma
 
         implicit none
@@ -6,14 +12,6 @@ module progsigma
 
       contains
 
-!>\file progsigma_calc.f90
-!! This file contains the subroutine that calculates the prognostic
-!! updraft area fraction that is used for closure computations in 
-!! saSAS deep and shallow convection, based on a moisture budget
-!! as described in Bengtsson et al. 2022 \cite Bengtsson_2022.
-
-!>\ingroup SAMFdeep
-!>\ingroup SAMF_shal
 !> This subroutine computes a prognostic updraft area fraction
 !! used in the closure computations in the samfdeepcnv.f scheme
 !! This subroutine computes a prognostic updraft area fracftion

@@ -1,12 +1,12 @@
 !>\file cires_orowam2017.f
+!!
 
-
+!> This module includes the OROGW solver of WAM2017.
       module cires_orowam2017
       contains
 
 !>\defgroup cires_orowam2017_mod CIRES UGWP orowam2017 Module
 !>This is the OROGW-solver of WAM2017.
-!>@{
 
 !>
       subroutine oro_wam_2017(im, levs,npt,ipt, kref,kdt,me,master,
@@ -394,4 +394,3 @@ subroutine ugwpv0_tofd1d(levs, sigflt, elvmax, zsurf,
 !                
       end subroutine ugwpv0_tofd1d
       end module cires_orowam2017
-!>@}
@@ -1,3 +1,6 @@
+!>\file cires_tauamf_data.F90
+!!
+
 module cires_tauamf_data
 
   use machine, only: kind_phys
@@ -16,6 +19,7 @@ module cires_tauamf_data
 
 contains
 
+!>
    subroutine read_tau_amf(me, master, errmsg, errflg)
 
     use  netcdf
@@ -70,6 +74,7 @@ subroutine read_tau_amf(me, master, errmsg, errflg)
 
   end  subroutine read_tau_amf  
 
+!>
     subroutine cires_indx_ugwp (npts, me, master, dlat,j1_tau,j2_tau, w1_j1tau, w2_j2tau)
 
     use machine, only: kind_phys
@@ -110,6 +115,7 @@ subroutine cires_indx_ugwp (npts, me, master, dlat,j1_tau,j2_tau, w1_j1tau, w2_j
       return
     end subroutine cires_indx_ugwp   
 
+!>
     subroutine tau_amf_interp(me, master, im, idate, fhour, j1_tau,j2_tau, ddy_j1, ddy_j2, tau_ddd)    
     use machine, only: kind_phys	           
     implicit none
@@ -163,6 +169,7 @@ subroutine tau_amf_interp(me, master, im, idate, fhour, j1_tau,j2_tau, ddy_j1, d
 
     end subroutine tau_amf_interp  
 
+!>
     subroutine gfs_idate_calendar(idate, fhour, ddd, fddd) 
 
     use machine, only: kind_phys    		 

@@ -1,16 +1,17 @@
 !>  \file cires_ugwp.F90
 !! This file contains the Unified Gravity Wave Physics (UGWP) scheme by Valery Yudin (University of Colorado, CIRES)
+
+!> This module contains the UGWP v0 scheme by Valery Yudin (University of Colorado, CIRES)
+!!
 !! See Valery Yudin's presentation at 2017 NGGPS PI meeting:
 !! Gravity waves (GWs): Mesoscale GWs transport momentum, energy (heat) , and create eddy mixing in the whole atmosphere domain; Breaking and dissipating GWs deposit: (a) momentum; (b) heat (energy); and create (c) turbulent mixing of momentum, heat, and tracers
 !! To properly incorporate GW effects (a-c) unresolved by DYCOREs we need GW physics
 !! "Unified": a) all GW effects due to both dissipation/breaking; b) identical GW solvers for all GW sources; c) ability to replace solvers.
 !! Unified Formalism:
-!! 1. GW Sources: Stochastic and physics based mechanisms for GW-excitations in the lower atmosphere, calibrated by the high-res analyses/forecasts, and observations (3 types of GW sources: orography, convection, fronts/jets).
-!! 2. GW Propagation: Unified solver for "propagation, dissipation and breaking" excited from all type of GW sources.
-!! 3. GW Effects: Unified representation of GW impacts on the "resolved" flow for all sources (energy-balanced schemes for momentum, heat and mixing).
+!! - GW Sources: Stochastic and physics based mechanisms for GW-excitations in the lower atmosphere, calibrated by the high-res analyses/forecasts, and observations (3 types of GW sources: orography, convection, fronts/jets).
+!! - GW Propagation: Unified solver for "propagation, dissipation and breaking" excited from all type of GW sources.
+!! - 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
-
-
 module cires_ugwp
 
     use machine, only: kind_phys
@@ -33,9 +34,7 @@ module cires_ugwp
 ! ------------------------------------------------------------------------
 ! CCPP entry points for CIRES Unified Gravity Wave Physics (UGWP) scheme v0
 ! ------------------------------------------------------------------------
-!>\defgroup cires_ugwp_run_mod CIRES Unified Gravity Wave Physics v0 Module
-!> @{
-!>@ The subroutine initializes the CIRES UGWP V0.
+!> The subroutine initializes the CIRES UGWP V0.
 !> \section arg_table_cires_ugwp_init Argument Table
 !! \htmlinclude cires_ugwp_init.html
 !!
@@ -112,7 +111,7 @@ end subroutine cires_ugwp_init
 ! finalize of cires_ugwp   (_finalize)
 ! -----------------------------------------------------------------------
 
-!>@brief The subroutine finalizes the CIRES UGWP
+!> The subroutine finalizes the CIRES UGWP
 #if 0
 !> \section arg_table_cires_ugwp_finalize Argument Table
 !! \htmlinclude cires_ugwp_finalize.html
@@ -445,5 +444,4 @@ subroutine cires_ugwp_run(do_ugwp, me,  master, im,  levs, ntrac, dtp, kdt, lonr
     endif
 
     end subroutine cires_ugwp_run
-!> @}
 end module cires_ugwp
@@ -6,7 +6,7 @@
 !  init gw-background dissipation
 !===============================    
 
-!> Define constants
+!> This module contains UGWP v0 initialization schemes 
     module ugwp_common_v0
 !
      use machine,  only: kind_phys
@@ -95,6 +95,7 @@ end subroutine init_global_gwdis_v0
 !    ugwpv0_oro_init
 !
 !=========================================================================
+!> This module contains orographic wave source schemes for UGWP v0.
      module ugwpv0_oro_init
 
      use ugwp_common_v0, only : bnv2min, grav, grcp, fv, grav, cpd, grcp, pi
@@ -225,6 +226,7 @@ end module ugwpv0_oro_init
 !  Part -3  init  wave solvers
 !===============================
 
+!> This module contains initialization of wave solvers for UGWP v0
   module ugwpv0_lsatdis_init
      implicit none
 
@@ -270,6 +272,7 @@ end subroutine initsolv_lsatdis_v0
   end module ugwpv0_lsatdis_init
 !
 !
+!>This module contains init-solvers for "broad" non-stationary multi-wave spectra
   module ugwpv0_wmsdis_init
 
     use ugwp_common_v0, only :   pi, pi2

@@ -1,5 +1,7 @@
 !>\file cires_ugwp_module.F90
+!!
 
+!>This module contains the UGWPv0 driver
 module  cires_ugwpv0_module
 
 !
@@ -9,33 +11,33 @@ module  cires_ugwpv0_module
     implicit none
     logical            :: module_is_initialized
 
-    logical            :: do_physb_gwsrcs = .false.        ! control for physics-based GW-sources
-    logical            :: do_rfdamp       = .false.        ! control for Rayleigh friction inside ugwp_driver
+    logical            :: do_physb_gwsrcs = .false.        !< control for physics-based GW-sources
+    logical            :: do_rfdamp       = .false.        !< control for Rayleigh friction inside ugwp_driver
 
     real, parameter    :: arad=6370.e3
     real, parameter    :: pi = atan(1.0)
     real, parameter    :: pi2 = 2.*pi
     real, parameter    :: hps   = 7000.
     real, parameter    :: hpskm = hps/1000.
 !
-    real               :: kxw = 6.28e-3/100.               ! single horizontal wavenumber of ugwp schemes
+    real               :: kxw = 6.28e-3/100.               !< single horizontal wavenumber of ugwp schemes
     real, parameter    :: ricrit = 0.25
     real, parameter    :: frcrit = 0.50
     real, parameter    :: linsat = 1.00
     real, parameter    :: linsat2 = linsat*linsat
 !
 
-    integer               :: knob_ugwp_solver=1            ! 1, 2, 3, 4 - (linsat, ifs_2010, ad_gfdl, dsp_dis)
-    integer, dimension(4) :: knob_ugwp_source              ! [1,1,1,0]  - (oro, fronts, conv, imbf-owp]
-    integer, dimension(4) :: knob_ugwp_wvspec              !  number of waves for- (oro, fronts, conv, imbf-owp]
-    integer, dimension(4) :: knob_ugwp_azdir               !   number of wave azimuths for- (oro, fronts, conv, imbf-owp]
-    integer, dimension(4) :: knob_ugwp_stoch               !  1 - deterministic ; 0 - stochastic
-    real,    dimension(4) :: knob_ugwp_effac               !  efficiency factors for- (oro, fronts, conv, imbf-owp]
+    integer               :: knob_ugwp_solver=1            !< 1, 2, 3, 4 - (linsat, ifs_2010, ad_gfdl, dsp_dis)
+    integer, dimension(4) :: knob_ugwp_source              !< [1,1,1,0]  - (oro, fronts, conv, imbf-owp]
+    integer, dimension(4) :: knob_ugwp_wvspec              !<  number of waves for- (oro, fronts, conv, imbf-owp]
+    integer, dimension(4) :: knob_ugwp_azdir               !<   number of wave azimuths for- (oro, fronts, conv, imbf-owp]
+    integer, dimension(4) :: knob_ugwp_stoch               !<  1 - deterministic ; 0 - stochastic
+    real,    dimension(4) :: knob_ugwp_effac               !<  efficiency factors for- (oro, fronts, conv, imbf-owp]
 
-    integer               :: knob_ugwp_doaxyz=1            ! 1 -gwdrag
-    integer               :: knob_ugwp_doheat=1            ! 1 -gwheat
-    integer               :: knob_ugwp_dokdis=0            ! 1 -gwmixing
-    integer               :: knob_ugwp_ndx4lh = 2          ! n-number  of  "unresolved" "n*dx" for lh_gw
+    integer               :: knob_ugwp_doaxyz=1            !< 1 -gwdrag
+    integer               :: knob_ugwp_doheat=1            !< 1 -gwheat
+    integer               :: knob_ugwp_dokdis=0            !< 1 -gwmixing
+    integer               :: knob_ugwp_ndx4lh = 2          !< n-number  of  "unresolved" "n*dx" for lh_gw
 !
     integer  :: ugwp_azdir
     integer  :: ugwp_stoch
@@ -45,12 +47,12 @@ module  cires_ugwpv0_module
     real     :: ugwp_effac
 
 !
-    data knob_ugwp_source / 1,0, 1, 0 /                    !  oro-conv-fjet-okw-taub_lat:      1-active 0-off
-    data knob_ugwp_wvspec /1,32,32,32/                     !  number of waves for- (oro, fronts, conv, imbf-owp, taulat]
-    data knob_ugwp_azdir  /2, 4, 4,4/                      !  number of wave azimuths for- (oro, fronts, conv, imbf-okwp]
-    data knob_ugwp_stoch  /0, 0, 0,0/                      !  0 - deterministic ; 1 - stochastic, non-activated option
-    data knob_ugwp_effac  /1.,1.,1.,1./                    !  efficiency factors for- (oro, fronts, conv, imbf-owp]
-    integer  :: knob_ugwp_version = 0                      !  version control had sense under IPD in CCPP=> to SUITES
+    data knob_ugwp_source / 1,0, 1, 0 /                    !<  oro-conv-fjet-okw-taub_lat:      1-active 0-off
+    data knob_ugwp_wvspec /1,32,32,32/                     !<  number of waves for- (oro, fronts, conv, imbf-owp, taulat]
+    data knob_ugwp_azdir  /2, 4, 4,4/                      !<  number of wave azimuths for- (oro, fronts, conv, imbf-okwp]
+    data knob_ugwp_stoch  /0, 0, 0,0/                      !<  0 - deterministic ; 1 - stochastic, non-activated option
+    data knob_ugwp_effac  /1.,1.,1.,1./                    !<  efficiency factors for- (oro, fronts, conv, imbf-owp]
+    integer  :: knob_ugwp_version = 0                      !<  version control had sense under IPD in CCPP=> to SUITES
     integer  :: launch_level = 55
 !
     namelist /cires_ugwp_nml/ knob_ugwp_solver, knob_ugwp_source,knob_ugwp_wvspec, knob_ugwp_azdir,  &

@@ -1,6 +1,7 @@
 !>  \file cires_ugwp_post.F90
-!! This file contains
+!! This file contains the calcualtion of the UGWP v0 diagnostics
 
+!> This module contains the calculation of the UGWP v0 diagnostics (ldiag_ugwp)
 module cires_ugwp_post
 
 contains

@@ -1,10 +1,13 @@
 !>\file cires_ugwp_triggers.F90
 !!
 
+!> This module contains routines describing the the latitudinal shape of 
+!! vertical momentum flux function in UGWP v0.
       module cires_ugwp_triggers
       contains
 !
 
+!>
       subroutine slat_geos5_tamp_v0(im, tau_amp, xlatdeg, tau_gw)
 !=================
 ! GEOS-5 & MERRA-2 lat-dependent GW-source function  tau(z=Zlaunch) =rho*<u'w'>
@@ -38,6 +41,7 @@ subroutine slat_geos5_tamp_v0(im, tau_amp, xlatdeg, tau_gw)
 !      
       end subroutine slat_geos5_tamp_v0
 
+!>
       subroutine slat_geos5_v0(im, xlatdeg, tau_gw)
 !=================
 ! GEOS-5 & MERRA-2 lat-dependent GW-source function  tau(z=Zlaunch) =rho*<u'w'>
@@ -76,7 +80,8 @@ subroutine slat_geos5_v0(im, xlatdeg, tau_gw)
       enddo
 !      
       end subroutine slat_geos5_v0
-!      
+
+!>      
       subroutine init_nazdir_v0(naz,  xaz,  yaz)
       use ugwp_common_v0 , only : pi2
       implicit none

@@ -12,7 +12,7 @@
 ! Part-0   specifications of common constants, limiters and "criiical" values
 ! 
 !
-
+!> This module contains common constants, limiters and "critical" values in      
     module ugwp_common
 !
      use machine,  only : kind_phys