Scientific documentation v4.0 for UFS public release

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_rad_time_vary.fv3.F90

@@ -1,4 +1,4 @@
-!>\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)
    module GFS_rad_time_vary
 

physics/GFS_rrtmg_pre.F90

@@ -1,4 +1,4 @@
-!> \file GFS_rrtmg_pre.f90
+!> \file GFS_rrtmg_pre.F90
 !! This file contains
       module GFS_rrtmg_pre
 

physics/GFS_rrtmg_setup.F90

@@ -1,4 +1,4 @@
-!> \file GFS_rrtmg_setup.f90
+!> \file GFS_rrtmg_setup.F90
 !! This file contains
 module GFS_rrtmg_setup
 
@@ -646,9 +646,7 @@ end subroutine radinit
 !! \param slag           equation of time in radians
 !! \param sdec,cdec      sine and cosine of the solar declination angle
 !! \param solcon         solar constant adjusted by sun-earth distance \f$(W/m^2)\f$
-!> \section gen_radupdate General Algorithm
-!> @{
-!-----------------------------------
+!! \section gen_radupdate General Algorithm
       subroutine radupdate( idate,jdate,deltsw,deltim,lsswr, me,        &
      &                      slag,sdec,cdec,solcon)
 !...................................

physics/GFS_time_vary_pre.fv3.F90

@@ -1,4 +1,4 @@
-!> \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)
 
    module GFS_time_vary_pre

physics/cires_ugwp.F90

@@ -31,12 +31,11 @@ module cires_ugwp
 ! ------------------------------------------------------------------------
 ! CCPP entry points for CIRES Unified Gravity Wave Physics (UGWP) scheme v0
 ! ------------------------------------------------------------------------
-!>@brief The subroutine initializes the CIRES UGWP
+!>\ingroup cires_ugwp_run_mod
+!> The subroutine initializes the CIRES UGWP.
 !> \section arg_table_cires_ugwp_init Argument Table
 !! \htmlinclude cires_ugwp_init.html
 !!
-! -----------------------------------------------------------------------
-!
     subroutine cires_ugwp_init (me, master, nlunit, input_nml_file, logunit, &
                 fn_nml2, lonr, latr, levs, ak, bk, dtp, cdmbgwd, cgwf,       &
                 pa_rf_in, tau_rf_in, con_p0, do_ugwp, errmsg, errflg)
@@ -101,7 +100,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
@@ -135,18 +134,60 @@ 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).
+
+!>\defgroup cires_ugwp_run_mod CIRES Unified Gravity Wave Physics Module 
+!>@{
+!! The physics of NGWs in the UGWP framework (Yudin et al. 2018 \cite yudin_et_al_2018) 
+!! is represented by four GW-solvers, which have been 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. These GW solvers have
+!! been modified by considring the background dissipation of temperature
+!! and winds.  This feature, which is important in the mesosphere and 
+!! thermosphere for WAM applications, considers appropriate 
+!! scale-dependent dissipation of waves near the model top lid providing
+!! momentum and energy conservation in the vertical column physics 
+!! (Shaw and Shepherd 2009 \cite shaw_and_shepherd_2009). In the UGWP v0,
+!! a 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.
+!! In UGWP v0, the specification for the VMF function is adopted from 
+!! the Goddard Earth Observing System Version 5 (GEOS-5) global atmosphere
+!! model of the National Aeronautic and Space Administration (NASA) Goddard
+!! Space Flight Center (GSFC) Global Modeling and Assimilation Office (GMAO), 
+!! as described in Molod et al. (2015) \cite molod_et_al_2015 and employed 
+!! in the Modern-Era Retrospective analysis for Research and Applications
+!! (MERRA)-2 reanalysis (Gelaro et al., 2017 \cite gelaro_et_al_2017).
+!! The Fortran subroutine 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. 
 !!
-!> \section arg_table_cires_ugwp_run Argument Table
+!! The UGWP v0 code has been enhanced by scientists from NOAA's EMC to 
+!! modulate the zonal mean NGW forcing by three-dimensional distributions
+!! of the total precipitation (as a proxy for the excitation of NGWs by
+!! convection) and vertically-integrated (surface-tropopause) turbulent 
+!! kinetic energy. The vertically extented configuration of the UFS 
+!! weather model is being tuned using reanalysis products from MERRA-2 and 
+!! the European Centre for Medium-Range Weather Forecasts (ERA-5), along
+!! with temperature, ozone, and water vapor observations of middle 
+!! atmosphere satellite missions. The verification scores with updated
+!! NGW forcing, as reported elsewhere by EMC researchers, display noticeable
+!! improvements into the mesosphere.
+!!
+!! \section arg_table_cires_ugwp_run Argument Table
 !! \htmlinclude cires_ugwp_run.html
 !!
-
-! subroutines original
+!>\section gen_cires_ugwp_run General Algorithm
      subroutine cires_ugwp_run(do_ugwp, me,  master, im,  levs, ntrac, dtp, kdt, lonr, &
          oro, oro_uf, hprime, nmtvr, oc, theta, sigma, gamma, elvmax, clx, oa4,        &
          do_tofd, ldiag_ugwp, cdmbgwd, xlat, xlat_d, sinlat, coslat, area,             &
@@ -215,9 +256,8 @@ subroutine cires_ugwp_run(do_ugwp, me,  master, im,  levs, ntrac, dtp, kdt, lonr
     errmsg = ''
     errflg = 0
 
-    ! 1) ORO stationary GWs
-    !    ------------------
-    ! wrap everything in a do_ugwp 'if test' in order not to break the namelist functionality
+    !> -#  ORO stationary GWs
+    !!  - wrap everything in a do_ugwp 'if test' in order not to break the namelist functionality
     if (do_ugwp) then                       ! calling revised old GFS gravity wave drag
 
      ! topo paras
@@ -271,7 +311,7 @@ subroutine cires_ugwp_run(do_ugwp, me,  master, im,  levs, ntrac, dtp, kdt, lonr
 
     if (cdmbgwd(3) > 0.0) then
 
-      ! 2) non-stationary GW-scheme with GMAO/MERRA GW-forcing
+      !> -# Call slat_geos5_tamp(), non-stationary GW-scheme with GMAO/MERRA GW-forcing
       call slat_geos5_tamp(im, tamp_mpa, xlat_d, tau_ngw)
 
       if (abs(1.0-cdmbgwd(3)) > 1.0e-6) then
@@ -309,6 +349,10 @@ subroutine cires_ugwp_run(do_ugwp, me,  master, im,  levs, ntrac, dtp, kdt, lonr
         enddo
       endif
 
+      !>  - Call fv3_ugwp_solv2_v0(), which is the modification 
+      !! of Scinocca (2003) \cite scinocca_2003 scheme for
+      !! NGWs with non-hydrostatic and rotational effects for GW propagations
+      !! and background dissipation.
       call fv3_ugwp_solv2_v0(im, levs, dtp, tgrs, ugrs, vgrs,qgrs(:,:,1), &
            prsl, prsi, phil, xlat_d, sinlat, coslat, gw_dudt, gw_dvdt, gw_dtdt, gw_kdis, &
            tau_ngw, me, master, kdt)
@@ -366,5 +410,5 @@ subroutine cires_ugwp_run(do_ugwp, me,  master, im,  levs, ntrac, dtp, kdt, lonr
     gw_dudt = gw_dudt*(1.-pked) +  ed_dudt*pked
 
     end subroutine cires_ugwp_run
-
+!>@}
 end module cires_ugwp

physics/cires_ugwp_module.F90

@@ -1,3 +1,4 @@
+!>\file cires_ugwp_module.F90
 !
 module  cires_ugwp_module
 
@@ -106,6 +107,7 @@ module  cires_ugwp_module
 ! init  of cires_ugwp   (_init)  called from GFS_driver.F90
 !
 ! -----------------------------------------------------------------------
+!>\ingroup cires_ugwp_run_mod
    subroutine cires_ugwp_mod_init (me, master, nlunit, input_nml_file, logunit, &
               fn_nml, lonr, latr, levs, ak, bk, pref, dtp, cdmvgwd, cgwf,    &
               pa_rf_in, tau_rf_in)
@@ -289,6 +291,7 @@ end subroutine cires_ugwp_mod_init
 !       Diag%zmtb, Diag%zlwb, Diag%zogw, Diag%du3dt_mtb,             &
 !       Diag%du3dt_ogw, Diag%du3dt_tms )
 
+!>\ingroup cires_ugwp_run_mod
     subroutine cires_ugwp_driver                                     &
        (im, levs, dtp, kdt, me, lprnt,   lonr,                       & 
        pa_rf, tau_rf, cdmbgwd,  xlat, xlatd, sinlat,  coslat,        &
@@ -629,6 +632,7 @@ end subroutine cires_ugwp_driver
 !=============================================
 
 
+!>\ingroup cires_ugwp_run_mod
      subroutine cires_ugwp_advance
 !-----------------------------------------------------------------------
 !
@@ -653,6 +657,7 @@ end subroutine cires_ugwp_advance
 ! -----------------------------------------------------------------------
 
 
+!>\ingroup cires_ugwp_run_mod
   subroutine cires_ugwp_mod_finalize
 !
 ! deallocate sources/spectra & some diagnostics need to find where "deaalocate them"

physics/cires_ugwp_triggers.F90

@@ -1,3 +1,7 @@
+!>\file cires_ugwp_triggers.F90
+!!
+
+!>\ingroup cires_ugwp_run_mod
         subroutine ugwp_triggers
         implicit none
         write(6,*) ' physics-based triggers for UGWP ' 
@@ -62,7 +66,8 @@ SUBROUTINE  subs_diag_geo(nx, ny,  lat, lon, rlat, rlon, dy, dx,  &
 !
       return
       end SUBROUTINE  subs_diag_geo
-!      
+!  
+!>\ingroup cires_ugwp_run_mod
       subroutine get_xy_pt(V, Vx, Vy, nx, ny, dlam1, dlat)
 !~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 ! compute for each Vert-column: grad(V)
@@ -87,6 +92,7 @@ subroutine get_xy_pt(V, Vx, Vy, nx, ny, dlam1, dlat)
 
     end subroutine get_xy_pt
 
+!>\ingroup cires_ugwp_run_mod
     subroutine get_xyd_wind( V, Vx, Vy, Vyd, nx, ny, dlam1, dlat, divJp, divJm)
 !    
 ! compute for each Vert-column: grad(V)
@@ -119,6 +125,7 @@ subroutine get_xyd_wind( V, Vx, Vy, Vyd, nx, ny, dlam1, dlat, divJp, divJm)
 
       end  subroutine get_xyd_wind
 
+!>\ingroup cires_ugwp_run_mod
       subroutine trig3d_fjets( nx, ny, nz, U, V, T, Q, P3D, PS, delp, delz, lon, lat, pmid, trig3d_fgf)
       implicit none
       integer ::  nx, ny, nz
@@ -161,8 +168,11 @@ subroutine trig3d_fjets( nx, ny, nz, U, V, T, Q, P3D, PS, delp, delz, lon, lat,
         trig3d_fgf(:,:,k) =   -ptx*ptx*ux - pty*pty*vy -(vx+uyd)*ptx*pty
 
       enddo
+
+!>\ingroup cires_ugwp_run_mod
       end  subroutine trig3d_fjets
 
+!>\ingroup cires_ugwp_run_mod
       subroutine trig3d_okubo( nx, ny, nz, U, V, T, Q, P3d, PS, delp, delz, lon, lat, pmid, trig3d_okw)
       implicit none
       integer ::  nx, ny, nz
@@ -212,6 +222,7 @@ subroutine trig3d_okubo( nx, ny, nz, U, V, T, Q, P3d, PS, delp, delz, lon, lat,
       enddo   
       end  subroutine trig3d_okubo     
 !      
+!>\ingroup cires_ugwp_run_mod
       subroutine trig3d_dconv(nx, ny, nz, U, V, T, Q, P3d, PS, delp, delz, lon, lat, pmid, trig3d_conv, &
                               dcheat3d, precip2d, cld_klevs2d, scheat3d)
 
@@ -230,6 +241,7 @@ subroutine trig3d_dconv(nx, ny, nz, U, V, T, Q, P3d, PS, delp, delz, lon, lat, p
       integer :: k
       end subroutine trig3d_dconv
 
+!>\ingroup cires_ugwp_run_mod
       subroutine cires_3d_triggers( nx, ny, nz, lon, lat, pmid,          &
         U, V, W, T, Q, delp, delz, p3d, PS, HS, Hyam, Hybm, Hyai, Hybi,  &
         trig3d_okw, trig3d_fgf, trig3d_conv,                             &
@@ -283,6 +295,7 @@ end subroutine cires_3d_triggers
 ! specify time-dep bulk sources:   taub, klev,  if_src, nf_src
 !
 !==================================================================================
+!>\ingroup cires_ugwp_run_mod
       subroutine get_spectra_tau_convgw &
       (nw, im, levs, dcheat,  scheat, precip, icld, xlatd, sinlat, coslat,taub, klev, if_src, nf_src)
 !
@@ -352,6 +365,7 @@ subroutine get_spectra_tau_convgw &
 !      print *, '   get_spectra_tau_convgw '  
       end subroutine get_spectra_tau_convgw
 !
+!>\ingroup cires_ugwp_run_mod
       subroutine get_spectra_tau_nstgw(nw, im, levs, trig_fgf, xlatd, sinlat, coslat, taub, klev, if_src, nf_src)
       integer                      :: nw, im, levs 
       real, dimension(im, levs)    :: trig_fgf
@@ -412,6 +426,7 @@ subroutine get_spectra_tau_nstgw(nw, im, levs, trig_fgf, xlatd, sinlat, coslat,
 !                 
       end subroutine get_spectra_tau_nstgw   
 ! 
+!>\ingroup cires_ugwp_run_mod
       subroutine get_spectra_tau_okw(nw, im, levs,  trig_okw, xlatd, sinlat, coslat, taub, klev, if_src, nf_src)
       integer                      :: nw, im, levs 
       real, dimension(im, levs)    :: trig_okw
@@ -463,10 +478,13 @@ end subroutine get_spectra_tau_okw
 !
 !
 !      
-!>\ingroup cires_ugwp_run
-!> @{
-!!
-!!
+!>\ingroup cires_ugwp_run_mod
+!! This subroutine describes the latitudinal shape of the VMF-function
+!! as displayed in Figure 3 of Molod et al. (2015). The enhanced values
+!! of VMF in the equatorial region result in QBO-like oscillations
+!! in the equatorial zonal winds and more realistic simulations of 
+!! the equatorial dynamics in the GEOS-5 operational and MERRA-2
+!! reanalysis products.
       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'>
@@ -500,6 +518,7 @@ subroutine slat_geos5_tamp(im, tau_amp, xlatdeg, tau_gw)
 !      
       end subroutine slat_geos5_tamp
 
+!>\ingroup cires_ugwp_run_mod
       subroutine slat_geos5(im, xlatdeg, tau_gw)
 !=================
 ! GEOS-5 & MERRA-2 lat-dependent GW-source function  tau(z=Zlaunch) =rho*<u'w'>
@@ -538,6 +557,8 @@ subroutine slat_geos5(im, xlatdeg, tau_gw)
       enddo
 !      
       end subroutine slat_geos5
+
+!>\ingroup cires_ugwp_run_mod
       subroutine init_nazdir(naz,  xaz,  yaz)
       use ugwp_common , only : pi2
       implicit none

physics/cires_ugwp_utils.F90

@@ -1,4 +1,6 @@
-!  
+!>\file cires_ugwp_utils.F90
+
+!>\ingroup cires_ugwp_run_mod  
       subroutine um_flow(nz, klow, ktop, up, vp, tp, qp, dp, zpm, zpi, &
                          pmid, pint, bn2, uhm, vhm, bn2hm, rhohm)
 !
@@ -61,6 +63,7 @@ subroutine um_flow(nz, klow, ktop, up, vp, tp, qp, dp, zpm, zpi, &
       end subroutine um_flow
 !
 !
+!>\ingroup cires_ugwp_run_mod
       subroutine mflow_tauz(levs, up, vp, tp, qp, dp, zpm, zpi, &
         pmid, pint, rho, ui, vi, ti, bn2i, bvi, rhoi)
 
@@ -132,6 +135,7 @@ subroutine mflow_tauz(levs, up, vp, tp, qp, dp, zpm, zpi, &
       end subroutine mflow_tauz
 
 !     
+!>\ingroup cires_ugwp_run_mod
       subroutine get_unit_vector(u, v, u_n, v_n, mag)
       implicit  none
       real, intent(in) :: u, v

physics/cires_vert_lsatdis.F90

@@ -1,3 +1,6 @@
+!>\file cires_vert_lsatdis.F90
+
+!>\ingroup cires_ugwp_run_mod
    subroutine ugwp_lsatdis_naz(levs, ksrc, nw, naz, kxw, taub_spect, ch, xaz, yaz,  &                                 
               fcor, c2f2, dp, zmid, zint, pmid, pint, rho, ui, vi, ti,              &
               kvg, ktg, krad, kion, bn2i, bvi, rhoi, ax, ay, eps, ked, tau1)
@@ -101,6 +104,7 @@ subroutine ugwp_lsatdis_naz(levs, ksrc, nw, naz, kxw, taub_spect, ch, xaz, yaz,
 
     end subroutine ugwp_lsatdis_naz
 !
+!>\ingroup cires_ugwp_run_mod
     subroutine ugwp_lsatdis_az1(levs, ksrc, nw, kxw, ch, taub_sp,               &
           fcor, c2f2, zm, zi, rho, um, tm, bn2, bn, rhoi,                       &
           dzirho, dzpi, kvg, ktg, krad, kion, kmol, eps, ked, tau )
@@ -510,6 +514,7 @@ subroutine ugwp_lsatdis_az1(levs, ksrc, nw, kxw, ch, taub_sp,               &
 !
          end subroutine ugwp_lsatdis_az1
 !	 
+!>\ingroup cires_ugwp_run_mod
          subroutine ugwp_limit_1d(ax, ay,eps, ked, levs) 
            use cires_ugwp_module, only : max_kdis, max_eps, max_axyz
            implicit none