scidoc updates

NCAR · Aug 14, 2024 · 36abac9 · 36abac9
1 parent 6d98b1e
commit 36abac9
Show file tree

Hide file tree

Showing 21 changed files with 124 additions and 30 deletions.
diff --git a/physics/MP/GFDL/gfdl_cloud_microphys.F90 b/physics/MP/GFDL/gfdl_cloud_microphys.F90
@@ -1,6 +1,9 @@
 !> \file gfdl_cloud_microphys.F90
 !! This file contains the CCPP entry point for the column GFDL cloud microphysics ( Chen and Lin (2013)
 !! \cite chen_and_lin_2013 ).
+
+!> This module contains the CCPP entry point for the column GFDL cloud microphysics ( Chen and Lin (2013)
+!! \cite chen_and_lin_2013 ).
 module gfdl_cloud_microphys
 
    use gfdl_cloud_microphys_mod, only: gfdl_cloud_microphys_mod_init,   &

diff --git a/physics/MP/GFDL/module_gfdl_cloud_microphys.F90 b/physics/MP/GFDL/module_gfdl_cloud_microphys.F90
@@ -27,7 +27,7 @@
 ! =======================================================================
 !>\defgroup mod_gfdl_cloud_mp GFDL Cloud MP modules
 !!\ingroup gfdlmp
-!! This module contains the column GFDL Cloud microphysics scheme.
+!> This module contains the column GFDL Cloud microphysics scheme.
 module gfdl_cloud_microphys_mod
 
     ! use mpp_mod, only: stdlog, mpp_pe, mpp_root_pe, mpp_clock_id, &

diff --git a/physics/MP/NSSL/module_mp_nssl_2mom.F90 b/physics/MP/NSSL/module_mp_nssl_2mom.F90
@@ -1,11 +1,5 @@
 !>  \file module_mp_nssl_2mom.F90
-
-
-
-
-
-
-
+!!
 
 !---------------------------------------------------------------------
 ! code snapshot: "Sep 22 2023" at "22:01:53"
@@ -177,7 +171,10 @@
 
 !>\defgroup mod_nsslmp NSSL 2-moment microphysics modules
 !!\ingroup nsslmp 
-!! Module for NSSL cloud physics
+
+!> This module contains 1/2/3-moment bulk microphysics scheme based on a combination of
+!! Straka and Mansell (2005, JAM) and Zeigler (1985, JAS) and modified/upgraded in
+!! in Mansell, Zeigler, and Bruning (2010, JAS).
 MODULE module_mp_nssl_2mom
   IMPLICIT NONE
 

diff --git a/physics/MP/Thompson/module_mp_thompson.F90 b/physics/MP/Thompson/module_mp_thompson.F90
@@ -3,7 +3,7 @@
 
 !>\ingroup aathompson
 
-!! This module computes the moisture tendencies of water vapor,
+!> This module computes the moisture tendencies of water vapor,
 !! cloud droplets, rain, cloud ice (pristine), snow, and graupel.
 !! Prior to WRFv2.2 this code was based on Reisner et al (1998), but
 !! few of those pieces remain.  A complete description is now found in

diff --git a/physics/MP/Thompson/module_mp_thompson_make_number_concentrations.F90 b/physics/MP/Thompson/module_mp_thompson_make_number_concentrations.F90
@@ -2,6 +2,8 @@
 !! This file contains
 
 !>\ingroup aathompson
+
+!>This module ocntains lookup tables of radiative effective radius of cloud ice, rain and water.
 module module_mp_thompson_make_number_concentrations
 
       use physcons, only: PI => con_pi

diff --git a/physics/PBL/MYNN_EDMF/module_bl_mynn.F90 b/physics/PBL/MYNN_EDMF/module_bl_mynn.F90
@@ -248,6 +248,7 @@
 ! Many of these changes are now documented in references listed above.
 !====================================================================
 
+!> This module contains the entity of MYNN-EDMF PBL scheme
 MODULE module_bl_mynn
 
   use bl_mynn_common,only: &

diff --git a/physics/PBL/SATMEDMF/mfscu.f b/physics/PBL/SATMEDMF/mfscu.f
@@ -1,6 +1,8 @@
 !>\file mfscu.f
 !! This file contains the mass flux and downdraft parcel preperties
 !! parameterization for stratocumulus-top-driven turbulence.
+
+
       module mfscu_mod
       contains
 !>\ingroup satmedmf

diff --git a/physics/PBL/mfpbl.f b/physics/PBL/mfpbl.f
@@ -1,5 +1,8 @@
 !>  \file mfpbl.f
 !!  This file contains the subroutine that calculates the updraft properties and mass flux for use in the Hybrid EDMF PBL scheme.
+
+!> This module contains the subroutine that calculates the updraft properties and mass flux 
+!! for use in the Hybrid EDMF PBL scheme.
       module mfpbl_mod
       contains
 !>  \ingroup HEDMF

diff --git a/physics/PBL/mfpblt.f b/physics/PBL/mfpblt.f
@@ -1,6 +1,10 @@
 !>\file mfpblt.f
 !! This file contains the subroutine that calculates mass flux and
 !! updraft parcel properties for thermals driven by surface heating 
+!! for use in the TKE-EDMF PBL scheme.
+
+!> This module contains the subroutine that calculates mass flux and
+!! updraft parcel properties for thermals driven by surface heating 
 !! for use in the TKE-EDMF PBL scheme.
       module mfpblt_mod
       contains

diff --git a/physics/PBL/mfpbltq.f b/physics/PBL/mfpbltq.f
@@ -1,5 +1,9 @@
 !>\file mfpbltq.f
-!! This file contains the subroutine that calculates mass flux and
+!! This file contains the subroutine that computes mass flux and 
+!! updraft parcel properties for
+!! thermals driven by surface heating
+
+!> This module contains the subroutine that calculates mass flux and
 !! updraft parcel properties for thermals driven by surface heating 
 !! for use in the TKE-EDMF PBL scheme (updated version).
       module mfpbltq_mod

diff --git a/physics/Radiation/RRTMG/iounitdef.f b/physics/Radiation/RRTMG/iounitdef.f
@@ -48,6 +48,8 @@
 !!!!!  ==========================================================  !!!!!
 
 !========================================!
+!> this module defines fortran unit numbers for input/output data 
+!! files for the ncep gfs model.
       module module_iounitdef            !
 !........................................!
 !

diff --git a/physics/Radiation/mersenne_twister.f b/physics/Radiation/mersenne_twister.f
@@ -2,10 +2,10 @@
 !! This file contains the module that calculates random numbers using the 
 !! Mersenne twister
 
-!> \defgroup mersenne_ge Mersenne Twister Module
-!! Module: mersenne_twister   Modern random number generator
-!!\author Iredell          Org: W/NX23     date: 2005-06-14
-!! Abstract: This module calculates random numbers using the Mersenne twister.
+! Module: mersenne_twister   Modern random number generator
+!\author Iredell          Org: W/NX23     date: 2005-06-14
+!> This module calculates random numbers using the Mersenne twister.
+!!
 !!   (It has been adapted to a Fortran 90 module from open source software.
 !!   The comments from the original software are given below in the remarks.)
 !!   The Mersenne twister (aka MT19937) is a state-of-the-art random number

diff --git a/physics/Radiation/radiation_aerosols.f b/physics/Radiation/radiation_aerosols.f
@@ -122,9 +122,9 @@
 !!!!!  ==========================================================  !!!!!
 
 
-!========================================!
-      module module_radiation_aerosols   !
-!........................................!
+!> This module contains climatological atmospheric aerosol schemes for
+!! radiation computations.
+      module module_radiation_aerosols
 !
       use machine,  only : kind_phys, kind_io4, kind_io8
       use module_iounitdef,        only : NIAERCM

diff --git a/physics/Radiation/radiation_cloud_overlap.F90 b/physics/Radiation/radiation_cloud_overlap.F90
@@ -1,8 +1,7 @@
 !>\file radiation_cloud_overlap.F90
 !!
 
-!>\defgroup rad_cld_ovr_mod Radiation Cloud Overlap Module
-!! This module contains the calculation of cloud overlap parameters for both RRTMG and RRTMGP. 
+!> This module contains the calculation of cloud overlap parameters for both RRTMG and RRTMGP. 
 module module_radiation_cloud_overlap
   use machine, only : kind_phys
   implicit none

diff --git a/physics/SFC_Layer/MYNN/module_sf_mynn.F90 b/physics/SFC_Layer/MYNN/module_sf_mynn.F90
@@ -3,6 +3,8 @@
 !WRF:MODEL_LAYER:PHYSICS
 !
 !>\ingroup mynn_sfc
+!> This module contain routines to calculate stability parameters, kinematic siscosity
+!! in MYNN surface layer scheme
 MODULE module_sf_mynn
 
 !-------------------------------------------------------------------

diff --git a/physics/SFC_Layer/UFS/module_nst_parameters.f90 b/physics/SFC_Layer/UFS/module_nst_parameters.f90
@@ -4,11 +4,12 @@
 
 !>\defgroup nst_parameters GFS NSST Parameter Module
 !! \ingroup gfs_nst_main_mod
-!! This module contains constants and parameters used in GFS
+
+!> This module contains constants and parameters used in GFS
 !! near surface sea temperature scheme.
-!! history:
-!!  20210305: X.Li, reduce z_w_max from 30 m to 20 m
 module module_nst_parameters
+! history:
+!  20210305: X.Li, reduce z_w_max from 30 m to 20 m
 
   use machine, only :  kind_phys
   !

diff --git a/physics/SFC_Layer/UFS/module_nst_water_prop.f90 b/physics/SFC_Layer/UFS/module_nst_water_prop.f90
@@ -1,10 +1,10 @@
-
 !>\file module_nst_water_prop.f90
 !! This file contains GFS NSST water property subroutines.
 
 !>\defgroup waterprop GFS NSST Water Property
-!!This module contains GFS NSST water property subroutines.
 !!\ingroup gfs_nst_main_mod
+
+!> This module contains GFS NSST water property subroutines.
 module module_nst_water_prop
   use machine ,               only : kind_phys
   use module_nst_parameters , only : t0k, zero, one, half

diff --git a/physics/SFC_Models/Land/RUC/lsm_ruc.F90 b/physics/SFC_Models/Land/RUC/lsm_ruc.F90
@@ -1,6 +1,7 @@
 !>\file lsm_ruc.F90 
 !!  This file contains the RUC land surface scheme driver.
 
+!> This module contain the RUC land surface model driver
 module lsm_ruc
 
         use machine,           only: kind_phys, kind_dbl_prec

diff --git a/physics/docs/ccpp_doxyfile b/physics/docs/ccpp_doxyfile
@@ -1063,6 +1063,7 @@ EXCLUDE                = ../Radiation/RRTMGP/rte-rrtmgp   \
                          ../CONV/nTiedtke            \
                          ../CONV/RAS                 \
                          ../CONV/SAS                 \
+                         ../SFC_Layer/UFS/date_def.f \
                          ../GWD/cires_ugwpv1_module.F90 \
                          ../GWD/cires_ugwpv1_initialize.F90 \
                          ../GWD/cires_ugwpv1_oro.F90    \

diff --git a/physics/docs/library.bib b/physics/docs/library.bib
@@ -1,13 +1,68 @@
 %% This BibTeX bibliography file was created using BibDesk.
 %% https://bibdesk.sourceforge.io/
 
-%% Created for Man Zhang at 2024-08-06 10:37:12 -0600 
+%% Created for Man Zhang at 2024-08-09 15:31:41 -0600 
 
 
 %% Saved with string encoding Unicode (UTF-8) 
 
 
 
+@article{Yang_2008,
+	author = {Yang, Kun and Koike, Toshio and Ishikawa, Hirohiko and Kim, Joon and Li, Xin and Liu, Huizhi and Liu, Shaomin and Ma, Yaoming and Wang, Jieming},
+	date-added = {2024-08-09 15:31:11 -0600},
+	date-modified = {2024-08-09 15:31:11 -0600},
+	doi = {10.1175/2007jamc1547.1},
+	issn = {1558-8424},
+	journal = {Journal of Applied Meteorology and Climatology},
+	month = jan,
+	number = {1},
+	pages = {276{\^a}290},
+	publisher = {American Meteorological Society},
+	title = {Turbulent Flux Transfer over Bare-Soil Surfaces: Characteristics and Parameterization},
+	url = {http://dx.doi.org/10.1175/2007JAMC1547.1},
+	volume = {47},
+	year = {2008},
+	bdsk-url-1 = {http://dx.doi.org/10.1175/2007JAMC1547.1}}
+
+@article{yang_et_al_2002,
+	abstract = {Abstract In surface flux parametrizations, aerodynamic roughness length zm0, and thermal roughness length zh0, are used to account for different resistances for momentum transfer and heat transfer. This paper introduces a turbulence-related length hT and parametrizes the quantity kA−1=ln(hT/zh0) in order to estimate zh0. Based on data at three sites on the Tibetan Plateau, a general formula for kA−1 is obtained for the surfaces covered by bare soil or partially covered by very short vegetation. A surface flux parametrization with this formula provides better estimates of heat flux than either profile flux parametrization or surface flux parametrization with kB−1 (i.e. ln(zm0/zh0)). Therefore, the use of a reasonable length to scale zh0 can contribute to the improvement of surface flux parametrizations. Copyright {\copyright} 2002 Royal Meteorological Society},
+	author = {Yang, K. and Koike, T. and Fujii, H. and Tamagawa, K. and Hirose, N.},
+	doi = {https://doi.org/10.1256/003590002320603548},
+	eprint = {https://rmets.onlinelibrary.wiley.com/doi/pdf/10.1256/003590002320603548},
+	journal = {Quarterly Journal of the Royal Meteorological Society},
+	keywords = {Heat transfer, Surface temperature, Thermal roughness length, Turbulence},
+	number = {584},
+	pages = {2073-2087},
+	title = {Improvement of surface flux parametrizations with a turbulence-related length},
+	url = {https://rmets.onlinelibrary.wiley.com/doi/abs/10.1256/003590002320603548},
+	volume = {128},
+	year = {2002},
+	bdsk-url-1 = {https://rmets.onlinelibrary.wiley.com/doi/abs/10.1256/003590002320603548},
+	bdsk-url-2 = {https://doi.org/10.1256/003590002320603548}}
+
+@article{chen_and_zhang_2009,
+	abstract = {This study addresses the land-atmospheric coupling strength by using long-term AmeriFlux data from a wide range of land covers and climate regimes to reconstitute the surface exchange coefficient, Ch, which governs the total surface heat fluxes. For spring and summer, results show stronger coupling for tall canopy with Ch values ten times larger than for shorter vegetation. Observed Ch are then compared to values from the Noah land model. Results indicate that Noah underestimated (overestimated) Ch for forest (grass and crops), implying an insufficient (too efficient) coupling for tall canopy (short canopy). This discrepancy is attributed to the treatment of the roughness length for heat. With modest adjustments, the Noah model can reproduce the observed Ch. This study highlights the crucial role of treating the surface exchange processes in coupled land/weather/climate models and the need to use long-term flux data for different vegetation types and climate regimes to assess and mitigate their deficiencies.},
+	author = {Chen, Fei and Zhang, Ying},
+	doi = {https://doi.org/10.1029/2009GL037980},
+	eprint = {https://agupubs.onlinelibrary.wiley.com/doi/pdf/10.1029/2009GL037980},
+	journal = {Geophysical Research Letters},
+	keywords = {land-atmospheric coupling strength, land-atmospheric interactions, surface exchange coefficients},
+	number = {10},
+	title = {On the coupling strength between the land surface and the atmosphere: From viewpoint of surface exchange coefficients},
+	url = {https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1029/2009GL037980},
+	volume = {36},
+	year = {2009},
+	bdsk-url-1 = {https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1029/2009GL037980},
+	bdsk-url-2 = {https://doi.org/10.1029/2009GL037980}}
+
+@inproceedings{Zilitinkevich_1995,
+	author = {Sergej Zilitinkevich},
+	title = {Non-local turbulent transport pollution dispersion aspects of coherent structure of convective flows},
+	url = {https://api.semanticscholar.org/CorpusID:119885197},
+	year = {1995},
+	bdsk-url-1 = {https://api.semanticscholar.org/CorpusID:119885197}}
+
 @article{Dowell_2022,
 	author = {Dowell, David C. and Alexander, Curtis R. and James, Eric P. and Weygandt, Stephen S. and Benjamin, Stanley G. and Manikin, Geoffrey S. and Blake, Benjamin T. and Brown, John M. and Olson, Joseph B. and Hu, Ming and Smirnova, Tatiana G. and Ladwig, Terra and Kenyon, Jaymes S. and Ahmadov, Ravan and Turner, David D. and Duda, Jeffrey D. and Alcott, Trevor I.},
 	date-added = {2024-08-01 13:13:04 -0600},
@@ -132,7 +187,7 @@ @article{Bengtsson_et_al_2020
 	bdsk-url-2 = {https://doi.org/10.1029/2020MS002260}}
 
 @article{Han_et_al_2022,
-	author = {Han, J. and F. Yang and  R. Montuoro and W. Li and R. Sun},
+	author = {Han, J. and F. Yang and R. Montuoro and W. Li and R. Sun},
 	date-added = {2024-07-02 11:17:39 -0600},
 	date-modified = {2024-08-06 10:35:59 -0600},
 	institution = {NCEP Office Note 506},

diff --git a/physics/docs/pdftxt/suite_input.nml.txt b/physics/docs/pdftxt/suite_input.nml.txt
@@ -536,7 +536,7 @@ show some variables in the namelist that must match the SDF.
                                                       </ul>
                                                       <td>1
 <tr><td>lsoil           <td> lsm_noah              <td>number of soil layers           <td>4
-lsoil_lsm
+<tr><td>lsoil_lsm       <td> GFS_phys_time_vary.scm.F90   <td>number of soil layers internal to land surface model; -1 use lsoil    <td>-1
 <tr><td>rdlai           <td> lsm_ruc               <td>flag to read leaf area index from input files    <td>.false.
 <tr><td>ivegsrc         <td> lsm_noah, lsm_ruc,  noahmpdrv, sfc_diff          <td>flag for vegetation type dataset choice: \n 
                                                       <ul>
@@ -723,8 +723,24 @@ lsoil_lsm
 <tr><td>lheatstrg       <td>gfs_surface_generic_post          <td>flag for canopy heat storage parameterization    <td>.false.
 <tr><td>z0fac           <td>gfs_surface_generic_post          <td>surface roughness fraction factor          <td>0.3  
 <tr><td>e0fac           <td>gfs_surface_generic_post          <td>latent heat flux fraction factor relative to sensible heat flux,e.g., e0fac=0.5 indicates that canopy heat storage for latent heat flux is 50% of that for sensible heat flux  <td>0.5
-<tr><td>isftcflx        <td>mynnsfc_wrapper          <td>flag for thermal roughness lengths over water in MYNN-SFCLAY          <td>0
-<tr><td>iz0tlnd         <td>mynnsfc_wrapper          <td>flag for thermal roughness lengths over land in MYNN-SFCLAY          <td>0
+<tr><td>isftcflx        <td>mynnsfc_wrapper          <td>flag for thermal roughness lengths over water in MYNN-SFCLAY          
+                                                     <ul>
+                                                     <li>0: z0,zt, and zq from the COARE algorithm. 
+                                                     <li>1: z0 from Davis et al.(2008), zt&zq from COARE 3.0/3.5
+                                                     <li>2: z0 from Davis et al.(2008), zt&zq from Garratt (1992)
+                                                     <li>3: z0 from Taylor and Yelland (2004), zt and zq from COARE 3.0/3.5
+                                                     <li>4: GFS -taken from sfc_diff.f, for comparison/testing
+                                                     </ul>
+                                                     <td>0
+<tr><td>iz0tlnd         <td>mynnsfc_wrapper          <td>flag for thermal roughness lengths over land in MYNN-SFCLAY          
+                                                     <ul>
+                                                     <li>0: Zilitinkevich (1995) \cite Zilitinkevich_1995; Czil now set to 0.095
+                                                     <li>1: Czil_new (modified according to Chen and Zhang (2009) \cite chen_and_zhang_2009)
+                                                     <li>2: Modified Yang et al.(2002, 2008)\cite yang_et_al_2002 \cite Yang_2008 - generalized for all landuse
+                                                     <li>3: constant zt = z0/7.4 (original form; Garratt 1992)
+                                                     <li>4: GFS - taken from sfc_diff.f, for comparison/testing
+                                                     </ul>
+                                                     <td>0
 <tr><td>sfclay_compute_flux         <td>mynnsfc_wrapper          <td>flag for computing surface scalar fluxes in MYNN-SFCLAY          <td>.false.
 <tr><td>sfclay_compute_diag         <td>mynnsfc_wrapper          <td>flag for computing surface diagnostics in MYNN-SFCLAY          <td>.false.
 <tr><td>thsfc_loc       <td>GFS_surface_composites_post, sfc_diff, sfc_diag, sfc_nst, noahmpdrv, sfc_sice   <td>flag for local .vs. standard potential temperature <td>.true.
@@ -747,5 +763,6 @@ iccn
 <tr><td>kice       <td>sfc_sice    <td>number of layers in ice      <td>2
 <tr><td>lrefres      <td>      <td>flag for radar reflectivity in restart file     <td>.false.
 </table>
+</div>
 
 */