NCAR · grantfirl · Sep 5, 2024 · May 13, 2024 · Jun 10, 2024 · Jun 10, 2024
@@ -1,3 +1,5 @@
+!>\file samfaerosols.F
+!!
       module samfcnv_aerosols
 
       implicit none

@@ -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,8 @@
+!>\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.
       module progsigma
 
         implicit none
@@ -6,12 +11,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

@@ -6,9 +6,7 @@ module drag_suite
 
       contains
 
-!> \defgroup gfs_drag_suite_mod GSL drag_suite Module
 !> This module contains the CCPP-compliant GSL orographic gravity wave drag scheme.
-!> @{
 !!
 !> \brief This subroutine initializes the orographic gravity wave drag scheme.
 !!

@@ -62,9 +62,6 @@ module ugwpv1_gsldrag
 !>@brief The subroutine initializes the unified UGWP
 !> \section arg_table_ugwpv1_gsldrag_init Argument Table
 !! \htmlinclude ugwpv1_gsldrag_init.html
-!!
-! -----------------------------------------------------------------------
-!
     subroutine ugwpv1_gsldrag_init  (                                          &
                 me, master, nlunit, input_nml_file, logunit,                   &
                 fn_nml2, jdat, lonr, latr, levs, ak, bk, dtp,                  &
@@ -291,18 +288,14 @@ end subroutine ugwpv1_gsldrag_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 ugwpv1_gsldrag_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).
+!>\section gen_ugwpv1_gsldrag_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 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_ugwpv1_gsldrag_run Argument Table
 !! \htmlinclude ugwpv1_gsldrag_run.html
 !!
-!> \section gen_ugwpv1_gsldrag CIRES UGWP Scheme General Algorithm
-!! @{
      subroutine ugwpv1_gsldrag_run(me, master, im, levs, ak, bk, ntrac, lonr, dtp,      &
           fhzero, kdt, ldiag3d, lssav, flag_for_gwd_generic_tend, do_gsl_drag_ls_bl,    &
           do_gsl_drag_ss, do_gsl_drag_tofd, do_ugwp_v1, do_ugwp_v1_orog_only,           &
@@ -734,6 +727,4 @@ subroutine ugwpv1_gsldrag_run(me, master, im, levs, ak, bk, ntrac, lonr, dtp,
      dtdt  = dtdt  + dtdt_gw
 
     end subroutine ugwpv1_gsldrag_run
-!! @}
-!>@}
 end module ugwpv1_gsldrag
@@ -5,7 +5,6 @@ module ugwpv1_gsldrag_post
 contains
 
 !>\defgroup ugwpv1_gsldrag_post ugwpv1_gsldrag Scheme Post
-!! @{
 !> \section arg_table_ugwpv1_gsldrag_post_run Argument Table
 !! \htmlinclude ugwpv1_gsldrag_post_run.html
 !!
@@ -142,5 +141,4 @@ subroutine ugwpv1_gsldrag_post_run ( im, levs, ldiag_ugwp,       &
 !=====================================================================
       end subroutine ugwpv1_gsldrag_post_run      
 
-!! @}
 end module ugwpv1_gsldrag_post
@@ -9,7 +9,6 @@ module GFS_GWD_generic_pre
 !> \section arg_table_GFS_GWD_generic_pre_run Argument Table
 !! \htmlinclude GFS_GWD_generic_pre_run.html
 !!
-!!  \section gfs_gwd_ge_pre_ga General Algorithm
       subroutine GFS_GWD_generic_pre_run(                               &
      &           im, levs, nmtvr, mntvar,                               &
      &           oc, oa4, clx, theta,                                   &

@@ -8,16 +8,13 @@
       module GFS_MP_generic_post
       contains
 
-!>\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()
+!> 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.
 !! 
 !> \section arg_table_GFS_MP_generic_post_run Argument Table
 !! \htmlinclude GFS_MP_generic_post_run.html
 !!
-!> \section gfs_mp_gen GFS MP Generic Post General Algorithm
-!> @{
       subroutine GFS_MP_generic_post_run(                                                                                 &
         im, levs, kdt, nrcm, nncl, ntcw, ntrac, imp_physics, imp_physics_gfdl, imp_physics_thompson, imp_physics_nssl,    &
         imp_physics_mg, imp_physics_fer_hires, cal_pre, cplflx, cplchm, cpllnd, progsigma, con_g, rhowater, rainmin, dtf, &
@@ -545,6 +542,5 @@ subroutine GFS_MP_generic_post_run(
       endif
 
       end subroutine GFS_MP_generic_post_run
-!> @}
 
       end module GFS_MP_generic_post
@@ -1,3 +1,6 @@
+!>\file GFS_ccpp_suite_sim_pre.F90
+!! Interstitial CCPP suite to couple UFS physics to CCPP suite simulator.
+
 ! ########################################################################################
 ! 
 ! Description: Interstitial CCPP suite to couple UFS physics to ccpp_suite_simulator.
@@ -17,12 +20,7 @@ module GFS_ccpp_suite_sim_pre
   public GFS_ccpp_suite_sim_pre_run, load_ccpp_suite_sim
 contains
 
-  ! ######################################################################################
-  !
-  ! SUBROUTINE GFS_ccpp_suite_sim_pre_run
-  !
-  ! ######################################################################################
-!! \section arg_table_GFS_ccpp_suite_sim_pre_run
+!> \section arg_table_GFS_ccpp_suite_sim_pre_run Argument Table
 !! \htmlinclude GFS_ccpp_suite_sim_pre_run.html
 !! 
   subroutine GFS_ccpp_suite_sim_pre_run(do_ccpp_suite_sim, dtend, ntqv, dtidx, dtp,      &
@@ -110,6 +108,7 @@ subroutine GFS_ccpp_suite_sim_pre_run(do_ccpp_suite_sim, dtend, ntqv, dtidx, dtp
   end subroutine GFS_ccpp_suite_sim_pre_run
 
   ! ######################################################################################
+!>
   subroutine load_ccpp_suite_sim(nlunit, nml_file, physics_process, iactive_T,           &
        iactive_u, iactive_v, iactive_q, errmsg, errflg)
 

@@ -28,7 +28,7 @@ module GFS_cloud_diagnostics
 !! This was bundled together with the prognostic cloud modules within the RRTMG implementation.
 !! For the RRTMGP implementation we propose to keep these diagnostics independent.
 !> @{
-!> \section arg_table_GFS_cloud_diagnostics_run
+!> \section arg_table_GFS_cloud_diagnostics_run Argument Table
 !! \htmlinclude GFS_cloud_diagnostics_run.html
 !!  
   subroutine GFS_cloud_diagnostics_run(nCol, nLev, iovr, iovr_rand, iovr_maxrand,        &

@@ -1,4 +1,3 @@
-! ###########################################################################################
 !> \file GFS_physics_post.F90
 !!
 !! This module contains GFS specific calculations (e.g. diagnostics) and suite specific
@@ -13,10 +12,7 @@ module GFS_physics_post
   public GFS_physics_post_run
 contains
 
-! ###########################################################################################
-! SUBROUTINE GFS_physics_post_run
-! ###########################################################################################
-!! \section arg_table_GFS_physics_post_run Argument Table
+!> \section arg_table_GFS_physics_post_run Argument Table
 !! \htmlinclude GFS_physics_post_run.html
 !!
   subroutine GFS_physics_post_run(nCol, nLev, ntoz, ntracp100, nprocess, nprocess_summed,   &
@@ -26,39 +22,39 @@ subroutine GFS_physics_post_run(nCol, nLev, ntoz, ntracp100, nprocess, nprocess_
 
     ! Inputs
     integer, intent(in) :: &
-         nCol,           & ! Horizontal dimension
-         nLev,           & ! Number of vertical layers
-         ntoz,           & ! Index for ozone mixing ratio
-         ntracp100,      & ! Number of tracers plus 100
-         nprocess,       & ! Number of processes that cause changes in state variables 
-         nprocess_summed,& ! Number of causes in dtidx per tracer summed for total physics tendency
-         ip_physics,     & ! Index for process in diagnostic tendency output
-         ip_photochem,   & ! Index for process in diagnostic tendency output
-         ip_prod_loss,   & ! Index for process in diagnostic tendency output
-         ip_ozmix,       & ! Index for process in diagnostic tendency output
-         ip_temp,        & ! Index for process in diagnostic tendency output
-         ip_overhead_ozone ! Index for process in diagnostic tendency output    
+         nCol,           & !< Horizontal dimension
+         nLev,           & !< Number of vertical layers
+         ntoz,           & !< Index for ozone mixing ratio
+         ntracp100,      & !< Number of tracers plus 100
+         nprocess,       & !< Number of processes that cause changes in state variables 
+         nprocess_summed,& !< Number of causes in dtidx per tracer summed for total physics tendency
+         ip_physics,     & !< Index for process in diagnostic tendency output
+         ip_photochem,   & !< Index for process in diagnostic tendency output
+         ip_prod_loss,   & !< Index for process in diagnostic tendency output
+         ip_ozmix,       & !< Index for process in diagnostic tendency output
+         ip_temp,        & !< Index for process in diagnostic tendency output
+         ip_overhead_ozone !< Index for process in diagnostic tendency output    
     integer, intent(in), dimension(:,:) :: &
-         dtidx             ! Bookkeeping indices for GFS diagnostic tendencies
+         dtidx             !< Bookkeeping indices for GFS diagnostic tendencies
     logical, intent(in) :: &
-         ldiag3d           ! Flag for 3d diagnostic fields
+         ldiag3d           !< Flag for 3d diagnostic fields
     logical, intent(in), dimension(:) :: &
-         is_photochem      ! Flags for photochemistry processes to sum
+         is_photochem      !< Flags for photochemistry processes to sum
 
     ! Inputs (optional)
     real(kind=kind_phys), intent(in), dimension(:,:), pointer, optional :: &
-         do3_dt_prd,     & ! Physics tendency: production and loss effect
-         do3_dt_ozmx,    & ! Physics tendency: ozone mixing ratio effect
-         do3_dt_temp,    & ! Physics tendency: temperature effect
-         do3_dt_ohoz       ! Physics tendency: overhead ozone effect
+         do3_dt_prd,     & !< Physics tendency: production and loss effect
+         do3_dt_ozmx,    & !< Physics tendency: ozone mixing ratio effect
+         do3_dt_temp,    & !< Physics tendency: temperature effect
+         do3_dt_ohoz       !< Physics tendency: overhead ozone effect
 
     ! Outputs
     real(kind=kind_phys), intent(inout), dimension(:,:,:), optional :: &
-         dtend             ! Diagnostic tendencies for state variables
+         dtend             !< Diagnostic tendencies for state variables
     character(len=*), intent(out) :: &
-         errmsg            ! CCPP error message
+         errmsg            !< CCPP error message
     integer, intent(out) :: &
-         errflg            ! CCPP error flag
+         errflg            !< CCPP error flag
 
     ! Locals
     integer :: idtend, ichem, iphys, itrac
@@ -123,6 +119,7 @@ subroutine GFS_physics_post_run(nCol, nLev, ntoz, ntracp100, nprocess, nprocess_
 
   contains
 
+!>
     subroutine sum_it(isum,itrac,sum_me)
       integer, intent(in) :: isum ! third index of dtend of summary process
       integer, intent(in) :: itrac ! tracer or state variable being summed