[develop]: Add Doxygen variable definitions to modules (#965)

* rm extra '='; chg docs to doc * change docs to doc * add 5 VRBLS2D defs * describe module for 2D, 3D, and 4D vars * draft missing module definitions * add draft of module definitions * document additional modules (draft) * draft of missing values in modules * draft var/func defns for GFIP3 & grib2_module * comment out unsupported Doxyfile.in tags * update xml_perl_data.f docs * update wrf_io_flags.f docs * update VRBLS4D_mod.f docs * update several 3D vars * 3D var updates * format 2D vars module * format docs for physcons.f * format/add docs for SOIL_mod * update format in RQSTFLD, cuparm, grib2_module * Updated variables in VRBLS_mod.f files * format params.f * Updated MASKS_mod.f variables * Defined some more missing variables * update params.F * update params.f * Updated Variables in CMASSI.F and intio_tags.f * Resolved warnings in all modules listed in this commit * Fixing something dumb I did in intio_tags.f last commit * Edited and added some definitions for variables * fix Doxyfile.in @ signs * CMASSI reformat * CMASSI update * update CMASSI, CTLBLK, params * restore NFCST,NBC,LIST,IOUT,NTSTM var section in CTLBLK * misc edits * update LOOKUP.f * updates to MASKS_mod and LOOKUP * update 2d vars * update more 2D vars * RHGRD.f update * CTLBLK var updates * update more 2D vars * more 2D vars * more 2D vars * more 2D vars * more 2D vars * uncomment sections of Doxyfile for CI/CD * 4D vars update * add 3d var defs * update 3D vars and RQSTFLD * 3D vars update * 3D vars & typo in unified_vars table * misc updates * correct formatting * add missing variables * minor edits * Doxyfile updates * Doxyfile updates * doxygenize SET_LVLSXML, misc minor edits * rm old/unneeded comments from READ_xml.f; misc minor edits * misc edits * various minor doc edits * update cuparm & misc others * misc minor edits * minor edits/formatting * reformat SET_LVLSXML * minor cuparm & xml_perl_data formatting * add to xml_perl_data * rm stray xmp_perl_data comment * rm stray & in MASKS_mod * update intio_tags.f * update svptbl.f * update physcons.f * update machine.f & misc * add back commented-out code * undo removal of commented out code * update user_guide.md * format module descriptions * update CMASSI and misc others * fix secondary phys cons * minor formatting/updates throughout * formatting * fix formatting * fix field_info * fix machine variables * comment out cuparm vars that should have been commented out * fix var defns in svptbl.f * fix var defns in GFIP3 * fix typo * add hera RT log --------- Co-authored-by: Gillian Petro <gpetro@hercules-login-1.hpc.msstate.edu> Co-authored-by: Gillian Petro <gpetro@Orion-login-2.HPC.MsState.Edu> Co-authored-by: jdkublnick <47824899+jdkublnick@users.noreply.github.com> Co-authored-by: Gillian Petro <gillianpetro@Gillians-Air.fios-router.home> Co-authored-by: Gillian Petro <gillianpetro@Gillians-MBP.fios-router.home> Co-authored-by: Fernando Andrade - NOAA <121964418+FernandoAndrade-NOAA@users.noreply.github.com> Co-authored-by: FernandoAndrade-NOAA <fernando.andrade-maldonado@noaa.gov>
NOAA-EMC · Jul 8, 2024 · 60d1cbb · 60d1cbb
1 parent 6075237
commit 60d1cbb
Show file tree

Hide file tree

Showing 45 changed files with 1,849 additions and 1,236 deletions.
diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
diff --git a/doc/UserGuide/tables/UFS_unified_variables_table.csv b/doc/UserGuide/tables/UFS_unified_variables_table.csv
@@ -205,7 +205,7 @@ Particulate matter (PP10),pp10,pp10,3d,dyn,gocart_on=True
 Particulate matter (PM10),pm10,pp10,3d,dyn,nasa_on=True
 Dust emission fluxes (1-5),duem001/.../duem005,duem,2d,phy, all requested read into 3d array
 Dust sedimentation fluxes (1-5),dust1sd/.../dust5sd,dusd,2d, phy, all requested read into 3d array
-Dust dry deposition fluxes (1-5),dust1dp/.../dust5dp,dupd,2d,phy, all requested read into 3d array
+Dust dry deposition fluxes (1-5),dust1dp/.../dust5dp,dudp,2d,phy, all requested read into 3d array
 Dust wet deposition fluxes (1-5),dust1wtl/.../dust5wtl,duwt,2d,phy, all requested read into 3d array
 Dust scavenging fluxes (1-5),dust1wtc/.../dust5wtc,dusv,2d,phy, all requested read into 3d array
 Seasalt emission fluxes (1-5),ssem001/.../ssem005,ssem,2d,phy, all requested read into 3d array

diff --git a/doc/user_guide.md b/doc/user_guide.md
@@ -20,7 +20,7 @@ products. Output from the UPP is in National Weather Service (NWS) and
 World Meteorological Organization (WMO) GRIB2 format and can be used
 directly by visualization, plotting, or verification packages, or for
 further downstream post-processing, e.g. statistical post-processing
-techniques.  Examples of UPP products include:
+techniques. Examples of UPP products include:
 
 - T, Z, humidity, wind, cloud water, cloud ice, rain, and snow on pressure levels
 - SLP, shelter level T, humidity, and wind fields
@@ -33,5 +33,18 @@ techniques.  Examples of UPP products include:
 - Radar reflectivity products
 - Satellite look-alike products
 
-Support for the UFS UPP is provided through the UFS Forum by the
-Developmental Testbed Center (DTC) for FV3-based applications.
+**Prerequisites**
+The UPP requires certain NCEPLIBS packages to be installed via the spack-stack project. For instructions on installing these packages as a bundle via spack-stack, see: https://spack-stack.readthedocs.io/en/latest/. The UPP/modulefiles directory indicates which package versions are used and supported on Level 1 systems.
+
+Community support for the Unified Forecast System (UFS) UPP in FV3-based applications is provided by the
+Earth Prediction Innovation Center (EPIC). Community support for the UPP with WRF is no longer available. 
+
+* Support for the UFS UPP is provided through [GitHub Discussions](https://github.com/NOAA-EMC/UPP/discussions).
+* The UPP User's Guide for the latest standalone public release is [UPP v11.0.0](https://upp.readthedocs.io/en/upp_v11.0.0/).
+* The UPP User's Guide for develop branch is [UPP develop](https://upp.readthedocs.io/en/develop/).
+* The [UPP wiki](https://github.com/NOAA-EMC/UPP/wiki) includes relevant information and links for users and developers. 
+* Instructions on technical code documentation are available in a set of [Doxygen Documentation Slides](https://github.com/NOAA-EMC/UPP/wiki/DoxygenDocumentation.pdf).
+
+Code Managers: Wen Meng (EMC), Huiya Chuang (EMC), Fernando Andrade-Maldonado (EPIC)
+
+
diff --git a/sorc/ncep_post.fd/BNDLYR.f b/sorc/ncep_post.fd/BNDLYR.f
@@ -1,6 +1,6 @@
 !> @file
 !> @brief Subroutine that computes boundary layer fields.
-!
+!>
 !> Computes constant mass mean fields
 !>
 !> This routine computes constant mass (boundary layer)
@@ -11,11 +11,31 @@
 !> relative humidity, U and V winds, vertical velocity,
 !> and precipitable water.  Given these fundamental variables
 !> other fields may be computed.
-!>
+!> 
 !> @note If you change parameter NBND in this routine 
 !>       don't forget to change it also in the calling
 !>       subprogram, MISCLN.
 !>
+!> ### Program history log:
+!> Date | Programmer | Comments
+!> -----|------------|---------
+!> 1993-01-29 | RUSS TREADON | Original file
+!> 1993-05-07 | RUSS TREADON | ADDED DOC BLOCK AND MORE COMMENTS.
+!> 1993-06-19 | RUSS TREADON | ADDED LVLBND TO PARAMETER LIST.
+!> 1996-03-07 | MIKE BALDWIN | CHANGE PWTR CALC TO INCLUDE CLD WTR SPEED UP CODE
+!> 1998-06-16 | T BLACK      | CONVERSION FROM 1-D TO 2-D
+!> 1998-08-18 | MIKE BALDWIN | CHANGE QSBND TO RHBND IN CALL, COMPUTE RH OVER ICE
+!> 1998-12-22 | MIKE BALDWIN | BACK OUT RH OVER ICE
+!> 2000-01-04 | JIM TUCCILLO | MPI VERSION 
+!> 2002-01-15 | MIKE BALDWIN | WRF VERSION
+!> 2020-11-10 | JESSE MENG   | USE UPP_PHYSICS MODULE
+!> 2021-08-20 | Wen Meng     | Retrict computation fro undefined points.
+!> 2021-09-02 | Bo Cui       | Decompose UPP in X direction.
+!>     
+!> @author Russ Treadon W/NP2 @date 1993-01-29
+! ------------------------------------------------------------------------------------------
+!> @brief Computes boundary layer fields.
+!>
 !> @param[out] PBND - Layer mean pressure in NBND boundary layers (NBL).
 !> @param[out] TBND - Layer mean temperature in NBL.
 !> @param[out] QBND - Layer mean specific humidity in NBL.
@@ -28,23 +48,10 @@
 !> @param[out] QCNVBND - Layer moisture convergence in NBL.
 !> @param[out] LVLBND - ETA layer at midpoint of NBL.
 !>
-!> Program History
-!> - 93-01-29  RUSS TREADON
-!> - 93-05-07  RUSS TREADON - ADDED DOC BLOCK AND MORE COMMENTS.
-!> - 93-06-19  RUSS TREADON - ADDED LVLBND TO PARAMETER LIST.
-!> - 96-03-07  MIKE BALDWIN - CHANGE PWTR CALC TO INCLUDE CLD WTR
-!>                            SPEED UP CODE
-!> - 98-06-16  T BLACK      - CONVERSION FROM 1-D TO 2-D
-!> - 98-08-18  MIKE BALDWIN - CHANGE QSBND TO RHBND IN CALL,
-!>                            COMPUTE RH OVER ICE
-!> - 98-12-22  MIKE BALDWIN - BACK OUT RH OVER ICE
-!> - 00-01-04  JIM TUCCILLO - MPI VERSION 
-!> - 02-01-15  MIKE BALDWIN - WRF VERSION
-!> - 20-11-10  JESSE MENG   - USE UPP_PHYSICS MODULE
-!> - 21-08-20  Wen Meng     - Retrict computation fro undefined points.
-!> - 21-09-02  Bo Cui       - Decompose UPP in X direction.
-!>     
-!> @author Russ Treadon W/NP2 @date 1993-01-29
+!> @note If you change parameter NBND in this routine 
+!>       don't forget to change it also in the calling
+!>       subprogram, MISCLN.
+
       SUBROUTINE BNDLYR(PBND,TBND,QBND,RHBND,UBND,VBND,       &
                         WBND,OMGBND,PWTBND,QCNVBND,LVLBND)
 

diff --git a/sorc/ncep_post.fd/BOUND.f b/sorc/ncep_post.fd/BOUND.f
@@ -2,19 +2,14 @@
 !> @brief bound() clips data in passed array.
 !> 
 !> @author Russ Treadon W/NP2 @date 1993-01-18
-
-!> This routine bounds data in the passed array 
-!> FLD (im x jm elements long) and clips data values such 
-!> that on exiting the routine
+!> 
+!> This routine bounds data in the passed array FLD (im x jm elements long) 
+!> and clips data values such that on exiting the routine
 !> @code
 !>              FMIN <= FLD(I,J) <= FMAX
 !> @endcode
 !> for all points.
 !>
-!> @param[in] FMIN Lower (inclusive) bound for data.
-!> @param[in] FMAX Upper (inclusive) bound for data.
-!> @param[out] FLD Array whose elements are bounded by [FMIN,FMAX].
-!>
 !> ### Program History Log
 !> Date | Programmer | Comments
 !> -----|------------|---------
@@ -26,6 +21,13 @@
 !> 2021-09002 | Bo Cui       | Decompose UPP in X direction
 !>
 !> @author Russ Treadon W/NP2 @date 1993-01-18
+!---------------------------------------------------------------------------------------
+!> @brief Clips data in passed array.
+!> 
+!> @param[in] FMIN Lower (inclusive) bound for data.
+!> @param[in] FMAX Upper (inclusive) bound for data.
+!> @param[out] FLD Array whose elements are bounded by [FMIN,FMAX].
+!>
       SUBROUTINE BOUND(FLD,FMIN,FMAX)
 
 !     

diff --git a/sorc/ncep_post.fd/CALDWP.f b/sorc/ncep_post.fd/CALDWP.f
@@ -1,5 +1,5 @@
 !> @file
-!> @brief Subroutine related to dewpoint temperature.
+!> @brief Subroutine that calculates dewpoint temperature.
 !
 !> Computes dewpoint from P, T, and Q.
 !>     

diff --git a/sorc/ncep_post.fd/CALGUST.f b/sorc/ncep_post.fd/CALGUST.f
@@ -50,6 +50,7 @@ SUBROUTINE CALGUST(LPBL,ZPBL,GUST)
 !     
 !     
 !*****************************************************************************
+!> CALMXW computes max wind level fields.
 !     START CALMXW HERE.
 !     
 !     LOOP OVER THE GRID.

diff --git a/sorc/ncep_post.fd/CALHEL.f b/sorc/ncep_post.fd/CALHEL.f
@@ -1,6 +1,6 @@
 !> @file
-!> @brief Subroutine that computes storm relative helicity.
-!
+!> @brief Subroutine that computes storm relative helicity and storm motion.
+!>
 !> This routine computes estimated storm motion and storm-relative
 !> environmental helicity. (Davies-Jones et al 1990) the algorithm
 !> processd as follows.
@@ -12,16 +12,7 @@
 !> method (Bunkers et al. 1988) which has been found to do better in cases with
 !> 'non-classic' hodographs (such as Northwest-flow events) and do as well or 
 !> better than the old method in more classic situations.
-!>     
-!> @param[in] DEPTH Depth in meters over whcih helicity should be computed; allows one to distinguish 0-3 km and 0-1 km values.
-!> @param[out] UST Estimated U Component (m/s) Of Storm motion.
-!> @param[out] VST Estimated V Component (m/s) Of Storm motion.
-!> @param[out] HELI Storm-relative heliciry (m**2/s**2).
-!> @param[out] USHR1 U Component (m/s) Of 0-1 km shear.
-!> @param[out] VSHR1 V Component (m/s) Of 0-1 km shear.
-!> @param[out] USHR6 U Component (m/s) Of 0-0.5 to 5.5-6.0 km shear.
-!> @param[out] VSHR6 V Component (m/s) Of 0-0.5 to 5.5-6.0 km shear.
-!>     
+!>       
 !> ### Program history log:
 !> Date | Programmer | Comments
 !> -----|------------|---------
@@ -40,6 +31,18 @@
 !> 2022-10-07 | Tracy Hertneky  | Add left mover for storm motion in SH
 !>   
 !> @author Michael Baldwin W/NP2 @date 1994-08-22
+! -----------------------------------------------------------------------------------
+!> @brief Computes storm relative helicity and storm motion.
+!> 
+!> @param[in] DEPTH Depth in meters over whcih helicity should be computed; allows one to distinguish 0-3 km and 0-1 km values.
+!> @param[out] UST Estimated U Component (m/s) Of Storm motion.
+!> @param[out] VST Estimated V Component (m/s) Of Storm motion.
+!> @param[out] HELI Storm-relative heliciry (m**2/s**2).
+!> @param[out] USHR1 U Component (m/s) Of 0-1 km shear.
+!> @param[out] VSHR1 V Component (m/s) Of 0-1 km shear.
+!> @param[out] USHR6 U Component (m/s) Of 0-0.5 to 5.5-6.0 km shear.
+!> @param[out] VSHR6 V Component (m/s) Of 0-0.5 to 5.5-6.0 km shear.
+!> 
       SUBROUTINE CALHEL(DEPTH,UST,VST,HELI,USHR1,VSHR1,USHR6,VSHR6)
 
 !

diff --git a/sorc/ncep_post.fd/CMASSI.f b/sorc/ncep_post.fd/CMASSI.f
@@ -1,33 +1,55 @@
+!> @file
+!> @brief CMASSI defines variables related to mass and precipitation
+!> See CCPP Ferrier-Aligo microphysics modules for more information
   module CMASSI_mod
 !- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    implicit none
 !
 !-----------------------------------------------------------------------
-      REAL, PARAMETER :: DMImin=.05e-3, DMImax=1.e-3,      &
-     &  XMImin=1.e6*DMImin, XMImax=1.e6*DMImax
-      INTEGER, PARAMETER :: MDImin=XMImin, MDImax=XMImax
+      REAL, PARAMETER :: DMImin=.05e-3, &    !< Minimum mean mass of precipitation ice particles.
+      DMImax=1.e-3,       &                  !< Maximum mean mass of precipitation ice particles.
+      XMImin=1.e6*DMImin, &                  !< Minimum mean mass of precipitation ice particles (in microns).
+      XMImax=1.e6*DMImax                     !< Maximum mean mass of precipitation ice particles (in microns).
+
+      INTEGER, PARAMETER :: MDImin=XMImin, & !< Minimum mean diameter of precipitation ice particles.
+      MDImax=XMImax                          !< Maximum mean diameter of precipitation ice particles.
+
 !-----------------------------------------------------------------------
-!--- Mean mass of precpitation ice particles as functions of their mean
-!    size (in microns)
-!
-      REAL MASSI(MDImin:MDImax)
-!
+
+      REAL MASSI(MDImin:MDImax)        !< Mean mass of precipitation ice particles as functions of their mean size (in microns).
+
 !--- Mean rain drop diameters vary from 50 microns to 1000 microns
-! DMRmax definition is moved to microinit and has different values depending on imp_physics
-      REAL, PARAMETER :: DMRmin=.05E-3, DelDMR=1.E-6    &
-     &, XMRmin=1.E6*DMRmin, N0r0=8.E6, N0rmin=1.e4
-      REAL DMRmax,XMRmax
-      INTEGER, PARAMETER :: MDRmin=XMRmin
-      INTEGER MDRmax
-!
+!> DMRmax definition is moved to microinit and has different values depending on imp_physics
+
+      REAL, PARAMETER :: DMRmin=.05E-3, &          !< Minimum mean rain drop diameter (0.05 mm).
+      DelDMR=1.E-6,           &                    !< One-micron interval (Lookup tables store solutions at 1 micron intervals [DelDMR] of mean rain drop diameter.).
+      XMRmin=1.E6*DMRmin,     &                    !< Minimum mean rain drop diameter (in microns).
+      N0r0=8.E6,              &                    !< Assumed intercept (m**-4) of rain drops if drop diameters are between 0.2 and 1.0 mm.
+      N0rmin=1.e4                                  !< Minimum intercept (m**-4) for rain drops.
+
+      REAL DMRmax    &                             !< Maximum mean rain drop diameter.
+      ,XMRmax                                      !< Maximum mean rain drop diameter.
+
+      INTEGER, PARAMETER :: MDRmin=XMRmin          !< Minimum mean rain drop diameter (in microns).
+      INTEGER MDRmax                               !< Maximum mean rain drop diameter (in microns).
+
+! 
 !--- Various rain lookup tables
-!
-      REAL RQR_DRmin,RQR_DRmax,           &
-           CN0r0,CN0r_DMRmin,CN0r_DMRmax
-!
+! 
+
+      REAL RQR_DRmin   &                       !< Rain content (kg/m**3) for mean drop diameter of .05 mm.
+      ,RQR_DRmax       &                       !< Rain content (kg/m**3) for mean drop diameter of 1.0 mm.
+      ,CN0r0           &                       !< Constant derived from N0r0.
+      ,CN0r_DMRmin     &                       !< Minimum (starting) value for rain lookup tables for mean rain drop diameters.
+      ,CN0r_DMRmax                             !< Maximum (ending) value for rain lookup tables for mean rain drop diameters.
+
 !--- Other important parameters
-!    (NLImax, FLARGE2 are used for the older version of the microphysics)
-!
-      REAL T_ICE,NLImax,FLARGE2,TRAD_ice
-!
+!     (NLImax, FLARGE2 are used for the older version of the microphysics)
+! 
+      REAL T_ICE       &                       !< Temperature (C) threshold at which all remaining liquid water is glaciated to ice.
+      ,NLImax          &                       !< Maximum number concentrations (m**-3) of large ice (snow/graupel/sleet).
+      ,FLARGE2         &                       !< Set in MICROINIT.F (no longer used).
+      ,TRAD_ice                                !< Defined as 0.5*T_ICE+TFRZ, or 253.15K, in other routines. Possibly refers to thermal radiation of ice or ice nucleation temperature ? 
+
+
   end module  CMASSI_mod