[develop]: Add Doxygen variable definitions to modules

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

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)
+
+

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)
 

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)
 
 !     

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.
 !>     

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.

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)
 
 !

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