Doxygen in CALVOR.f, CALWXT_BOURG.f, CLDRAD.f, COLLECT.f, COLLECT_LOC…

….f, DEALLOCATE.f, and DEALLOCATE.f (#469) * This is part of Issue #392. Fixes the doxygen warnings in CALVOR.f, CALWXT_BOURG.f, CLDRAD.f, COLLECT.f, COLLECT_LOC.f, DEALLOCATE.f, and DEALLOCATE.f. * Fixed minor bug in CALVOR.f. * Update to PR#453. * More updates.
NOAA-EMC · Apr 4, 2022 · 40fbb3f · 40fbb3f
1 parent 394917e
commit 40fbb3f
Show file tree

Hide file tree

Showing 7 changed files with 253 additions and 416 deletions.
diff --git a/sorc/ncep_post.fd/CALVOR.f b/sorc/ncep_post.fd/CALVOR.f
@@ -1,47 +1,28 @@
 !> @file
-!
-!> SUBPROGRAM:    CALVOR      COMPUTES ABSOLUTE VORTICITY
-!!   PRGRMMR: TREADON         ORG: W/NP2      DATE: 92-12-22       
-!!     
-!! ABSTRACT:  
-!!     THIS ROUTINE COMPUTES THE ABSOLUTE VORTICITY.
-!!     
-!! PROGRAM HISTORY LOG:
-!!   92-12-22  RUSS TREADON
-!!   98-06-08  T BLACK - CONVERSION FROM 1-D TO 2-D
-!!   00-01-04  JIM TUCCILLO - MPI VERSION
-!!   02-01-15  MIKE BALDWIN - WRF VERSION C-GRID
-!!   05-03-01  H CHUANG - ADD NMM E GRID
-!!   05-05-17  H CHUANG - ADD POTENTIAL VORTICITY CALCULATION
-!!   05-07-07  B ZHOU   - ADD RSM IN COMPUTING DVDX, DUDY AND UAVG
-!!   13-08-09  S MOORTHI - Optimize the vorticity loop including threading
-!!   16-08-05  S Moorthi - add zonal filetering
-!!   2019-10-17 Y Mao - Skip calculation when U/V is SPVAL
-!!   2020-11-06 J Meng - USE UPP_MATH MODULE
-
-
-!!     
-!! USAGE:    CALL CALVOR(UWND,VWND,ABSV)
-!!   INPUT ARGUMENT LIST:
-!!     UWND     - U WIND (M/S) MASS-POINTS
-!!     VWND     - V WIND (M/S) MASS-POINTS
-!!
-!!   OUTPUT ARGUMENT LIST: 
-!!     ABSV     - ABSOLUTE VORTICITY (1/S) MASS-POINTS
-!!     
-!!   OUTPUT FILES:
-!!     NONE
-!!     
-!!   SUBPROGRAMS CALLED:
-!!     UTILITIES:
-!!       NONE
-!!     LIBRARY:
-!!       COMMON   - CTLBLK
-!!     
-!!   ATTRIBUTES:
-!!     LANGUAGE: FORTRAN
-!!     MACHINE : WCOSS
-!!
+!> @brief Subroutine that computes absolute vorticity.
+!>
+!> This routine computes the absolute vorticity.
+!>
+!> @param[in] UWND U wind (m/s) mass-points.
+!> @param[in] VWND V wind (m/s) mass-points.
+!> @param[out] ABSV absolute vorticity (1/s) mass-points.
+!>
+!> ### Program history log:
+!> Date | Programmer | Comments
+!> -----|------------|---------
+!> 1992-12-22 | Russ Treadon | Initial
+!> 1998-06-08 | T Black      | Convesion from 1-D to 2-D
+!> 2000-01-04 | Jim Tuccillo | MPI Version            
+!> 2002-01-15 | Mike Baldwin | WRF Version C-grid
+!> 2005-03-01 | H Chuang     | Add NMM E grid
+!> 2005-05-17 | H Chuang     | Add Potential vorticity calculation
+!> 2005-07-07 | B Zhou       | Add RSM in computing DVDX, DUDY and UAVG
+!> 2013-08-09 | S Moorthi    | Optimize the vorticity loop including threading
+!> 2016-08-05 | S Moorthi    | add zonal filetering
+!> 2019-10-17 | Y Mao        | Skip calculation when U/V is SPVAL
+!> 2020-11-06 | J Meng       | Use UPP_MATH Module
+!>
+!> @author Russ Treadon W/NP2 @date 1992-12-22
       SUBROUTINE CALVOR(UWND,VWND,ABSV)
 
 !     
@@ -410,44 +391,23 @@ SUBROUTINE CALVOR(UWND,VWND,ABSV)
       RETURN
       END
 
+!> CALDIV computes divergence.
+!>    
+!> For GFS, this routine copmutes the horizontal divergence
+!> using 2nd-order centered scheme on a lat-lon grid     
+!>
+!> @param[in] UWND U wind (m/s) mass-points.
+!> @param[in] VWND V wind (m/s) mass-points.
+!> @param[out] DIV divergence (1/s) mass-points.
+!>
+!> ### Program history log:
+!> Date | Programmer | Comments
+!> -----|------------|---------
+!> 2016-05-05 | Sajal Kar | Modified CALVORT to compute divergence from wind components
+!> 2016-07-22 | S Moorthi | Modified polar divergence calculation
+!>
+!> @author Sajal Kar W/NP2 @date 2016-05-05
       SUBROUTINE CALDIV(UWND,VWND,DIV)
-!$$$  SUBPROGRAM DOCUMENTATION BLOCK
-!                .      .    .     
-! SUBPROGRAM:    CALDIV      COMPUTES DIVERGENCE
-!   PRGRMMR: SAJAL KAR         ORG: W/NP2      DATE: 16-05-05
-!     
-! ABSTRACT:  
-!     FOR GFS, THIS ROUTINE COMPUTES THE HORIZONTAL DIVERGENCE
-!     USING 2ND-ORDER CENTERED SCHEME ON A LAT-LON GRID     
-!
-! PROGRAM HISTORY LOG:
-!   16-05-05  SAJAL KAR MODIFIED CALVORT TO COMPUTE DIVERGENCE FROM
-!             WIND COMPONENTS
-!   16-07-22  S Moorthi modifying polar divergence calculation
-!     
-! USAGE:    CALL CALDIV(UWND,VWND,DIV)
-!   INPUT ARGUMENT LIST:
-!     UWND     - U WIND (M/S) MASS-POINTS
-!     VWND     - V WIND (M/S) MASS-POINTS
-!
-!   OUTPUT ARGUMENT LIST: 
-!     DIV     - DIVERGENCE (1/S) MASS-POINTS
-!     
-!   OUTPUT FILES:
-!     NONE
-!     
-!   SUBPROGRAMS CALLED:
-!     UTILITIES:
-!       NONE
-!     LIBRARY:
-!       COMMON   - CTLBLK
-!     
-!   ATTRIBUTES:
-!     LANGUAGE: FORTRAN
-!     MACHINE : WCOSS
-!$$$  
-!     
-!
       use masks,        only: gdlat, gdlon
       use params_mod,   only: d00, dtr, small, erad
       use ctlblk_mod,   only: jsta_2l, jend_2u, spval, modelname, global, &
@@ -683,41 +643,21 @@ SUBROUTINE CALDIV(UWND,VWND,DIV)
       END SUBROUTINE CALDIV
 
       SUBROUTINE CALGRADPS(PS,PSX,PSY)
-!$$$  SUBPROGRAM DOCUMENTATION BLOCK
-!                .      .    .     
-! SUBPROGRAM: CALGRADPS COMPUTES GRADIENTS OF A SCALAR FIELD PS OR LNPS
-!   PRGRMMR: SAJAL KAR         ORG: W/NP2      DATE: 16-05-05
-!     
-! ABSTRACT:  
-!     FOR GFS, THIS ROUTINE COMPUTES  HRIZONTAL GRADIENTS OF PS OR LNPS
-!     USING 2ND-ORDER CENTERED SCHEME ON A LAT-LON GRID
-!     
-! PROGRAM HISTORY LOG:
-!   16-05-05  SAJAL KAR REDUCED FROM CALVORT TO ZONAL AND MERIDIONAL
-!             GRADIENTS OF GIVEN SURFACE PRESSURE PS, OR LNPS
-!     
-! USAGE:    CALL CALGRADPS(PS,PSX,PSY)
-!   INPUT ARGUMENT LIST:
-!     PS       - SURFACE PRESSURE (PA) MASS-POINTS
-!
-!   OUTPUT ARGUMENT LIST: 
-!     PSX     - ZONAL GRADIENT OF PS AT MASS-POINTS
-!     PSY     - MERIDIONAL GRADIENT OF PS AT MASS-POINTS
-!     
-!   OUTPUT FILES:
-!     NONE
-!     
-!   SUBPROGRAMS CALLED:
-!     UTILITIES:
-!       NONE
-!     LIBRARY:
-!       COMMON   - CTLBLK
-!     
-!   ATTRIBUTES:
-!     LANGUAGE: FORTRAN
-!     MACHINE : WCOSS
-!$$$  
-!     
+!> CALGRADPS computes gardients of a scalar field PS or LNPS.
+!>
+!> For GFS, this routine computes horizontal gradients of PS or LNPS.
+!> Using 2nd-order centered scheme on a lat-lon grid.
+!>
+!> @param[in] PS Surface pressure (Pa) mass-points.
+!> @param[out] PSX Zonal gradient of PS at mass-points.
+!> @param[out] PSY Meridional gradient of PS at mass-points.
+!>
+!> ### Program history log:
+!> Date | Programmer | Comments
+!> -----|------------|---------
+!> 2016-05-05 | Sajal Kar | Reduced from CALVORT to zonal and meridional gradients of given surface pressure PS, or LNPS
+!>
+!> @author Sajal Kar W/NP2 @date 2016-05-05
       use masks,        only: gdlat, gdlon
       use params_mod,   only: dtr, d00, small, erad
       use ctlblk_mod,   only: jsta_2l, jend_2u, spval, modelname, global, &

diff --git a/sorc/ncep_post.fd/CALWXT_BOURG.f b/sorc/ncep_post.fd/CALWXT_BOURG.f
@@ -1,68 +1,54 @@
 !> @file
-!
-!> Subprogram: calwxt_bourg    Calculate precipitation type (Bourgouin)
-!!   Prgmmr: Baldwin      Org: np22        Date: 1999-07-06
-!!
-!! Abstract: This routine computes precipitation type
-!!    using a decision tree approach that uses the so-called
-!!    "energy method" of Bourgouin of AES (Canada) 1992
-!!
-!! Program history log:
-!!   1999-07-06  M Baldwin
-!!   1999-09-20  M Baldwin  make more consistent with bourgouin (1992)
-!!   2005-08-24  G Manikin  added to wrf post
-!!   2007-06-19  M Iredell  mersenne twister, best practices
-!!   2015-00-00  S Moorthi  changed random number call and optimization and cleanup
-!!
-!! Usage:    call calwxt_bourg(im,jm,jsta_2l,jend_2u,jsta,jend,lm,lp1,   &
-!!    &                        iseed,g,pthresh,                          &
-!!    &                        t,q,pmid,pint,lmh,prec,zint,ptype)
-!!   Input argument list:
-!!     im       integer i dimension
-!!     jm       integer j dimension
-!!     jsta_2l  integer j dimension start point (including haloes)
-!!     jend_2u  integer j dimension end point (including haloes)
-!!     jsta     integer j dimension start point (excluding haloes)
-!!     jend     integer j dimension end point (excluding haloes)
-!!     lm       integer k dimension
-!!     lp1      integer k dimension plus 1
-!!     iseed    integer random number seed
-!!     g        real gravity (m/s**2)
-!!     pthresh  real precipitation threshold (m)
-!!     t        real(im,jsta_2l:jend_2u,lm) mid layer temp (K)
-!!     q        real(im,jsta_2l:jend_2u,lm) specific humidity (kg/kg)
-!!     pmid     real(im,jsta_2l:jend_2u,lm) mid layer pressure (Pa)
-!!     pint     real(im,jsta_2l:jend_2u,lp1) interface pressure (Pa)
-!!     lmh      real(im,jsta_2l:jend_2u) max number of layers
-!!     prec     real(im,jsta_2l:jend_2u) precipitation (m)
-!!     zint     real(im,jsta_2l:jend_2u,lp1) interface height (m)
-!!   Output argument list:
-!!     ptype    integer(im,jm) instantaneous weather type ()
-!!              acts like a 4 bit binary
-!!                1111 = rain/freezing rain/ice pellets/snow
-!!                where the one's digit is for snow
-!!                      the two's digit is for ice pellets
-!!                      the four's digit is for freezing rain
-!!                  and the eight's digit is for rain
-!!              in other words...
-!!                ptype=1 snow
-!!                ptype=2 ice pellets/mix with ice pellets
-!!                ptype=4 freezing rain/mix with freezing rain
-!!                ptype=8 rain
-!!
-!! Modules used:
-!!   mersenne_twister pseudo-random number generator
-!!
-!! Subprograms called:
-!!   random_number    pseudo-random number generator
-!!
-!! Attributes:
-!!   Language: Fortran 90
-!!
-!! Remarks: vertical order of arrays must be layer   1 = top
-!!                                       and layer lmh = bottom
-!!
-!!
+!> @brief Subroutine that calculate precipitation type (Bourgouin).
+!>
+!> This routine computes precipitation type.
+!> using a decision tree approach that uses the so-called
+!> "energy method" of Bourgouin of AES (Canada) 1992.
+!>
+!> @param[in] im integer i dimension.
+!> @param[in] jm integer j dimension.
+!> @param[in] jsta_2l integer j dimension start point (including haloes).
+!> @param[in] jend_2u integer j dimension end point (including haloes).
+!> @param[in] jsta integer j dimension start point (excluding haloes).
+!> @param[in] jend integer j dimension end point (excluding haloes).
+!> @param[in] lm integer k dimension.
+!> @param[in] lp1 integer k dimension plus 1.
+!> @param[in] iseed integer random number seed.
+!> @param[in] g real gravity (m/s**2).
+!> @param[in] pthresh real precipitation threshold (m).
+!> @param[in] t real(im,jsta_2l:jend_2u,lm) mid layer temp (K).
+!> @param[in] q real(im,jsta_2l:jend_2u,lm) specific humidity (kg/kg).
+!> @param[in] pmid real(im,jsta_2l:jend_2u,lm) mid layer pressure (Pa).
+!> @param[in] pint real(im,jsta_2l:jend_2u,lp1) interface pressure (Pa).
+!> @param[in] lmh real(im,jsta_2l:jend_2u) max number of layers.
+!> @param[in] prec real(im,jsta_2l:jend_2u) precipitation (m).
+!> @param[in] zint real(im,jsta_2l:jend_2u,lp1) interface height (m).
+!> @param[out] ptype integer(im,jm) instantaneous weather type () acts like a 4 bit binary 1111 = rain/freezing rain/ice pellets/snow.
+!><pre>
+!>                   where the one's digit is for snow
+!>                         the two's digit is for ice pellets
+!>                         the four's digit is for freezing rain
+!>                         and the eight's digit is for rain
+!>                         in other words...
+!>                         ptype=1 snow
+!>                         ptype=2 ice pellets/mix with ice pellets
+!>                         ptype=4 freezing rain/mix with freezing rain
+!>                         ptype=8 rain
+!></pre>
+!>
+!> ### Program history log:
+!> Date | Programmer | Comments
+!> -----|------------|---------
+!> 1999-07-06 | M Baldwin | Initial
+!> 1999-09-20 | M Baldwin | make more consistent with bourgouin (1992)
+!> 2005-08-24 | G Manikin | added to wrf post
+!> 2007-06-19 | M Iredell | mersenne twister, best practices
+!> 2015-??-?? | S Moorthi | changed random number call and optimization and cleanup
+!>
+!> Remarks: vertical order of arrays must be layer   1 = top
+!>          and layer lmh = bottom
+!>
+!> @author M Baldwin np22 @date 1999-07-06
 
       subroutine calwxt_bourg_post(im,jm,jsta_2l,jend_2u,jsta,jend,lm,lp1,   &
      &                             iseed,g,pthresh,                          &