Doxygen in GET_BITS.f, GPVS.f, LFMFLD.f, LFMFLD_GFS.f, MDL2P.f, MDL2S…

…TD_P.f, MDL2THANDPV.f, and MSFPS.f. (NOAA-EMC#474)

* This is part of Issue NOAA-EMC#392.

Fixes the doxygen warnings in GET_BITS.f, GPVS.f, LFMFLD.f, LFMFLD_GFS.f, MDL2P.f, MDL2STD_P.f, MDL2THANDPV.f, and MSFPS.f.

* Minor fix.

sorc/ncep_post.fd/GET_BITS.f

@@ -1,46 +1,37 @@
 !> @file
-!
-!> SUBPROGRAM:    GET_BITS      COMPUTE NUMBER OF BITS AND ROUND FIELD.
-!!   PRGMMR: IREDELL          ORG: W/NP23     DATE: 92-10-31
-!!
-!! ABSTRACT: THE NUMBER OF BITS REQUIRED TO PACK A GIVEN FIELD
-!!   AT A PARTICULAR DECIMAL SCALING IS COMPUTED USING THE FIELD RANGE.
-!!   THE FIELD IS ROUNDED OFF TO THE DECIMAL SCALING FOR PACKING.
-!!   THE MINIMUM AND MAXIMUM ROUNDED FIELD VALUES ARE ALSO RETURNED.
-!!   GRIB BITMAP MASKING FOR VALID DATA IS OPTIONALLY USED.
-!!
-!! PROGRAM HISTORY LOG:
-!!   92-10-31  IREDELL
-!!   95-04-14  BALDWIN - MODIFY FOLLOWING KEITH BRILL'S CODE
-!!                       TO USE SIG DIGITS TO COMPUTE DEC SCALE
-!!
-!! USAGE:   CALL GET_BITS(IBM,ISGDS,LEN,MG,G,ISCALE,GROUND,GMIN,GMAX,NBIT)
-!!   INPUT ARGUMENT LIST:
-!!     IBM      - INTEGER BITMAP FLAG (=0 FOR NO BITMAP)
-!!     SGDS     - MAXIMUM SIGNIFICANT DIGITS TO KEEP
-!!                (E.G. SGDS=3.0 KEEPS 3 SIGNIFICANT DIGITS)
-!!                OR BINARY PRECISION IF <0
-!!                (E.G. SGDS=-2.0 KEEPS FIELD TO NEAREST 1/4
-!!                           -3.0 "                    " 1/8
-!!                         2**SGDS PRECISION)
-!!     LEN      - INTEGER LENGTH OF THE FIELD AND BITMAP
-!!     MG       - INTEGER (LEN) BITMAP IF IBM=1 (0 TO SKIP, 1 TO KEEP)
-!!     G        - REAL (LEN) FIELD
-!!
-!!   OUTPUT ARGUMENT LIST:
-!!     ISCALE   - INTEGER DECIMAL SCALING
-!!     GROUND   - REAL (LEN) FIELD ROUNDED TO DECIMAL SCALING
-!!     GMIN     - REAL MINIMUM VALID ROUNDED FIELD VALUE
-!!     GMAX     - REAL MAXIMUM VALID ROUNDED FIELD VALUE
-!!     NBIT     - INTEGER NUMBER OF BITS TO PACK
-!!
-!! SUBPROGRAMS CALLED:
-!!   ISRCHNE  - FIND FIRST VALUE IN AN ARRAY NOT EQUAL TO TARGET VALUE
-!!
-!! ATTRIBUTES:
-!!   LANGUAGE: FORTRAN
-!!
-!!
+!> @brief get_bits() computes number of bits and round field.
+!>
+!> The number of bits requited to pack a given field
+!> at a particular decimal scaling is computed using the field range.
+!> The field is rounded off to the decimal scaling for packing.
+!> The minimum and maximum rounded field values are also returned.
+!> Grib bitmap masking for valid data is optionally used.
+!>
+!> @param[in] IBM Integer bitmap flag (=0 for no bitmap).
+!> @param[in] SGDS Maximum significant digits to keep.
+!><pre>
+!> (E.G. SGDS=3.0 keeps 3 significant digits)
+!>  or binary precision if <0
+!> (E.G. SGDS=-2.0 keeps field to nearest 1/4
+!>            -3.0 keeps field to nearest 1/8
+!>            2**SGDS precision)
+!></pre>
+!> @param[in] LEN Integer length of the field and bitmap.
+!> @param[in] MG Integet (LEN) bitmap if IBM=1 (0 to skip, 1 tp keep).
+!> @param[in] G Real (LEN) field.
+!> @param[out] ISCALE Integer decimal scaling.
+!> @param[out] GROUND Real (LEN) field rounded to decimal scaling.
+!> @param[out] GMIN Real minimum valid rounded field value.
+!> @param[out] GMAX Real maximum valid rounded field value.
+!> @param[out] NBIT Integer number of bits to pack.
+!>
+!> ### Program History Log
+!> Date | Programmer | Comments
+!> -----|------------|---------
+!> 1992-10-31 | Iredell | Initial
+!> 1995-04-14 | Baldwin | Modify following Keith Brill's code to use sig digits to compute DEC scale
+!>
+!> @author Iredell W/NP23 @date 1992-10-31
       SUBROUTINE GET_BITS(IBM,SGDS,LEN,MG,G,ISCALE,GROUND,           &
                           GMIN,GMAX,NBIT)
 
@@ -91,43 +82,36 @@ SUBROUTINE GET_BITS(IBM,SGDS,LEN,MG,G,ISCALE,GROUND,           &
 ! - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
       RETURN
       END
-	SUBROUTINE FNDBIT  ( rmin, rmax, rdb, nmbts, iscale, iret )
-!************************************************************************
-!* FNDBIT								*
-!*									*
-!* This subroutine computes the number of packing bits given the	*
-!* maximum number of significant digits to preserve or the binary	*
-!* precision to store the data.  The binary precision is given as a	*
-!* negative integer, ISCALE will always be zero in this case.		*
-!*									*
-!* The binary precision translates as follows:				*
-!*     -1  =>  store data to nearest 1/2				*
-!*     -2  =>  store data to nearest 1/4				*
-!*     -3  =>  store data to nearest 1/8				*
-!*									*
-!* Note that a fractional number of significant digits is allowed.	*
-!*									*
-!* FNDBIT ( AMIN, AMAX, RDB, NBITS, ISCALE, IRET )			*
-!*									*
-!* Input parameters:							*
-!*	AMIN 		REAL		Minimum value			*
-!*	AMAX		REAL		Maximum value			*
-!*	RDB		REAL		Maximum # of significant digits	*
-!*					  OR binary precision if < 0	*
-!*									*
-!* Output parameters:							*
-!*	NBITS		INTEGER		Number of bits for packing	*
-!*	ISCALE		INTEGER		Power of 10 scaling to use	*
-!*	IRET		INTEGER		Return code			*
-!*					  0 = normal return		*
-!**									*
-!* Log:									*
-!* K. Brill/NMC		06/92						*
-!* K. Brill/EMC		12/95	Added binary precision			*
-!* M. Baldwin           10/96   Added fix for negative nmbts
-!************************************************************************
-!*
-!
+!> fndbit() computes the number of packing bits given the
+!> maximum number of significant digits to preserve or the binary
+!> precision to store the data.  The binary precision is given as a
+!> negative integer, ISCALE will always be zero in this case.
+!>
+!> The binary precision translates as follows:
+!> <pre>
+!>     -1  =>  store data to nearest 1/2
+!>     -2  =>  store data to nearest 1/4
+!>     -3  =>  store data to nearest 1/8
+!> </pre>
+!>
+!> Note that a fractional number of significant digits is allowed.
+!>
+!> @param[in] AMIN Real Minimum value.
+!> @param[in] AMAX Real Maximum value.
+!> @param[in] RDB Real Maximum # of significant digits OR binary precision if < 0.
+!> @param[out] NBITS Integer Number of bits for packing.
+!> @param[out] ISCALE Integer Power of 10 scaling to use.
+!> @param[out] IRET Integer Return code. 0 = normal return.
+!>
+!> ### Program History Log
+!> Date | Programmer | Comments
+!> -----|------------|---------
+!> 1992-06-?? | K Brill   | Initial
+!> 1995-12-?? | K Brill   | Added binary precision
+!> 1996-10-?? | M Baldwin | Added fix for negative nmbts
+!>
+!> @author K. Brill NMC @date 1992-06-??
+    SUBROUTINE FNDBIT  ( rmin, rmax, rdb, nmbts, iscale, iret )
     implicit none
 !
     integer,intent(inout) ::  iscale,nmbts

sorc/ncep_post.fd/GPVS.f

@@ -1,36 +1,24 @@
 !> @file
-!                .      .    .
-!> SUBPROGRAM:    GPVS        COMPUTE SATURATION VAPOR PRESSURE TABLE
-!!   AUTHOR: N PHILLIPS       W/NP2      DATE: 30 DEC 82
-!!
-!! ABSTRACT: COMPUTE SATURATION VAPOR PRESSURE TABLE AS A FUNCTION OF
-!!   TEMPERATURE FOR THE TABLE LOOKUP FUNCTION FPVS.
-!!   EXACT SATURATION VAPOR PRESSURES ARE CALCULATED IN SUBPROGRAM FPVSX.
-!!   THE CURRENT IMPLEMENTATION COMPUTES A TABLE WITH A LENGTH
-!!   OF 7501 FOR TEMPERATURES RANGING FROM 180.0 TO 330.0 KELVIN.
-!!
-!! PROGRAM HISTORY LOG:
-!!   91-05-07  IREDELL
-!!   94-12-30  IREDELL             EXPAND TABLE
-!!   96-02-19  HONG                ICE EFFECT
-!!
-!! USAGE:  CALL GPVS
-!!
-!! SUBPROGRAMS CALLED:
-!!   (FPVSX)  - INLINABLE FUNCTION TO COMPUTE SATURATION VAPOR PRESSURE
-!!
-!! COMMON BLOCKS:
-!!   COMPVS   - SCALING PARAMETERS AND TABLE FOR FUNCTION FPVS.
-!!
-!! ATTRIBUTES:
-!!   LANGUAGE: FORTRAN 90
-!!   MACHINE:  IBM SP
-!!
-!!
-!#######################################################################
-!-- Lookup tables for the saturation vapor pressure w/r/t water & ice --
-!#######################################################################
-!
+!> @brief gpvs() computes saturation vapor pressure table.
+!>
+!> Compute saturation vapor pressure table as a function of
+!> temperature for the table lookup function FPVS.
+!> Exact saturation vapor pressures are calculated in subprogram FPVSX.
+!> The current implementation computes a table with a length
+!> of 7501 for temperatures ranging from 180.0 to 330.0 Kelvin.
+!>
+!> @param[out] pvu real (km) potential vorticity (10**-6*K*m**2/kg/s).
+!>
+!> ### Program History Log
+!> Date | Programmer | Comments
+!> -----|------------|---------
+!> 1982-12-30 | N Phillips   | Initial
+!> 1991-05-07 | Mark Iredell | Made into inlinable function
+!> 1994-12-30 | Mark Iredell | Expand table
+!> 1996-02-19 | Hong         | Ice effect
+!>
+!> @note Lookup tables for the saturation vapor pressure w/r/t water & ice.
+!> @author N Phillips W/NP2 @date 1982-12-30
       SUBROUTINE GPVS
 !     ******************************************************************
 
@@ -65,40 +53,28 @@ SUBROUTINE GPVS
 !-----------------------------------------------------------------------
                            FUNCTION FPVS(T)
 !-----------------------------------------------------------------------
-!$$$  SUBPROGRAM DOCUMENTATION BLOCK
-!                .      .    .
-! SUBPROGRAM:    FPVS        COMPUTE SATURATION VAPOR PRESSURE
-!   AUTHOR: N PHILLIPS            W/NP2      DATE: 30 DEC 82
-!
-! ABSTRACT: COMPUTE SATURATION VAPOR PRESSURE FROM THE TEMPERATURE.
-!   A LINEAR INTERPOLATION IS DONE BETWEEN VALUES IN A LOOKUP TABLE
-!   COMPUTED IN GPVS. SEE DOCUMENTATION FOR FPVSX FOR DETAILS.
-!   INPUT VALUES OUTSIDE TABLE RANGE ARE RESET TO TABLE EXTREMA.
-!   THE INTERPOLATION ACCURACY IS ALMOST 6 DECIMAL PLACES.
-!   ON THE CRAY, FPVS IS ABOUT 4 TIMES FASTER THAN EXACT CALCULATION.
-!   THIS FUNCTION SHOULD BE EXPANDED INLINE IN THE CALLING ROUTINE.
-!
-! PROGRAM HISTORY LOG:
-!   91-05-07  IREDELL             MADE INTO INLINABLE FUNCTION
-!   94-12-30  IREDELL             EXPAND TABLE
-!   96-02-19  HONG                ICE EFFECT
-!
-! USAGE:   PVS=FPVS(T)
-!
-!   INPUT ARGUMENT LIST:
-!     T        - REAL TEMPERATURE IN KELVIN
-!
-!   OUTPUT ARGUMENT LIST:
-!     FPVS     - REAL SATURATION VAPOR PRESSURE IN KILOPASCALS (CB)
-!
-! COMMON BLOCKS:
-!   COMPVS   - SCALING PARAMETERS AND TABLE COMPUTED IN GPVS.
-!
-! ATTRIBUTES:
-!   LANGUAGE: FORTRAN 90
-!   MACHINE:  IBM SP
-!
-!$$$
+!> fpvs() computes saturation vapor pressure.
+!>
+!> Compute saturation vapor pressure from the temperature.
+!> A linear interpolation is done between values in a lookup table
+!> computed in GPVS. See documentation for FPVSX for details.
+!> Input values outside table range are reset to table extrema.
+!> The interpolation accuracy is almost 6 decimal places.
+!> On the CRAY, FPVS is about 4 times faster than exact calculation.
+!> This function should be expanded inline in the calling routine.
+!>
+!> @param[in] T real temperature in Kelvin.
+!> @param[out] FPVS real saturation vapor pressure in kilopascals (CB).
+!>
+!> ### Program History Log
+!> Date | Programmer | Comments
+!> -----|------------|---------
+!> 1982-12-30 | N Phillips   | Initial
+!> 1991-05-07 | Mark Iredell | Made into inlinable function
+!> 1994-12-30 | Mark Iredell | Expand table
+!> 1996-02-19 | Hong         | Ice effect
+!>
+!> @author N Phillips W/NP2 @date 1982-12-30
 !-----------------------------------------------------------------------
       use svptbl_mod, only : NX,C1XPVS,C2XPVS,TBPVS
 !
@@ -144,41 +120,33 @@ FUNCTION FPVS0(T,NX,C1XPVS0,C2XPVS0,TBPVS0)
 !-----------------------------------------------------------------------
                          FUNCTION FPVSX(T)
 !-----------------------------------------------------------------------
-!$$$  SUBPROGRAM DOCUMENTATION BLOCK
-!                .      .    .
-! SUBPROGRAM:    FPVSX       COMPUTE SATURATION VAPOR PRESSURE
-!   AUTHOR: N PHILLIPS            W/NP2      DATE: 30 DEC 82
-!
-! ABSTRACT: EXACTLY COMPUTE SATURATION VAPOR PRESSURE FROM TEMPERATURE.
-!   THE WATER MODEL ASSUMES A PERFECT GAS, CONSTANT SPECIFIC HEATS
-!   FOR GAS AND LIQUID, AND NEGLECTS THE VOLUME OF THE LIQUID.
-!   THE MODEL DOES ACCOUNT FOR THE VARIATION OF THE LATENT HEAT
-!   OF CONDENSATION WITH TEMPERATURE.  THE ICE OPTION IS NOT INCLUDED.
-!   THE CLAUSIUS-CLAPEYRON EQUATION IS INTEGRATED FROM THE TRIPLE POINT
-!   TO GET THE FORMULA
-!       PVS=PSATK*(TR**XA)*EXP(XB*(1.-TR))
-!   WHERE TR IS TTP/T AND OTHER VALUES ARE PHYSICAL CONSTANTS
-!   THIS FUNCTION SHOULD BE EXPANDED INLINE IN THE CALLING ROUTINE.
-!
-! PROGRAM HISTORY LOG:
-!   91-05-07  IREDELL             MADE INTO INLINABLE FUNCTION
-!   94-12-30  IREDELL             EXACT COMPUTATION
-!   96-02-19  HONG                ICE EFFECT 
-!
-! USAGE:   PVS=FPVSX(T)
-! REFERENCE:   EMANUEL(1994),116-117
-!
-!   INPUT ARGUMENT LIST:
-!     T        - REAL TEMPERATURE IN KELVIN
-!
-!   OUTPUT ARGUMENT LIST:
-!     FPVSX    - REAL SATURATION VAPOR PRESSURE IN KILOPASCALS (CB)
-!
-! ATTRIBUTES:
-!   LANGUAGE: FORTRAN 90
-!   MACHINE:  IBM SP
-!
-!$$$
+!> fpvsx() computes saturation vapor pressure.
+!>
+!> Exactly compute saturation vapor pressure from temperature.
+!> The water model assumes a perfect gas, constant specific heats
+!> for gas and liquid, and neglects the volume of the liquid.
+!> The model does account for the variation of the latent heat
+!> of condensation with temperature.  The ice option is not included.
+!> The Clausius-Clapeyron equation is integrated from the triple point
+!> To get the formula
+!> @code
+!>     PVS=PSATK*(TR**XA)*exp(XB*(1.-TR))
+!> @endcode
+!> where TR is TTP/T and other values are physical constants
+!> This function should be expanded inline in the calling routine.
+!>
+!> @param[in] T real temperature in Kelvin.
+!> @param[out] FPVSX real saturation vapor pressure in kilopascals (CB).
+!>
+!> ### Program History Log
+!> Date | Programmer | Comments
+!> -----|------------|---------
+!> 1982-12-30 | N Phillips   | Initial
+!> 1991-05-07 | Mark Iredell | Made into inlinable function
+!> 1994-12-30 | Mark Iredell | Exact computation
+!> 1996-02-19 | Hong         | Ice effect
+!>
+!> @author N Phillips W/NP2 @date 1982-12-30
 !-----------------------------------------------------------------------
     implicit none
 !

sorc/ncep_post.fd/LFMFLD.f

@@ -1,71 +1,45 @@
 !> @file
-!                .      .    .     
-!> SUBPROGRAM:    LFMFLD      COMPUTES LAYER MEAN LFM FIELDS
-!!   PRGRMMR: TREADON         ORG: W/NP2      DATE: 92-12-22
-!!     
-!! ABSTRACT:
-!!     THIS ROUTINE COMPUTES THREE LAYER MEAN RELATIVE HUMIDITIES
-!!     AND A PRECIPITABLE WATER FIELD FROM ETA LEVEL DATA.  THE
-!!     COMPUTED FIELDS ARE INTENDED TO MIMIC SIMILAR FIELDS COM-
-!!     PUTED BY THE LFM.  THE ALGORITHM USED HERE IS FAIRLY PRI-
-!!     MATIVE.  IN EACH COLUMN ABOVE A MASS POINT ON THE ETA GRID
-!!     WE SET THE FOLLOWING TARGET PRESSURES:
-!!         SIGMA LAYER 1.00 PRESSURE:  SURFACE PRESSURE
-!!         SIGMA LAYER 0.66 PRESSURE:  0.50 * SURFACE PRESSURE
-!!         SIGMA LAYER 0.33 PRESSURE:  0.4356 * SURFACE PRESSURE
-!!     GIVEN THESE PRESSURES A SURFACE UP SUMMATION IS MADE OF 
-!!     RELATIVE HUMIDITY AND/OR PRECIPITABLE WATER BETWEEN THESE
-!!     TARGET PRESSURES.  EACH TERM IN THE SUMMATION IS WEIGHTED
-!!     BY THE THICKNESS OF THE ETA LAYER.  THE FINAL LAYER MEAN
-!!     IS THIS SUM NORMALIZED BY THE TOTAL DEPTH OF THE LAYER.  
-!!     THERE IS, OBVIOUSLY, NO NORMALIZATION FOR PRECIPITABLE WATER.
-!!
-!!     
-!! PROGRAM HISTORY LOG:
-!!   92-12-22  RUSS TREADON
-!!   93-07-27  RUSS TREADON - MODIFIED SUMMATION LIMITS FROM
-!!                            0.66*PSFC TO 0.75*PSFC AND 0.33*PSFC 
-!!                            TO 0.50*PSFC, WHERE PSFC IS THE
-!!                            SURFACES PRESSURE.  THE REASON FOR
-!!                            THIS CHANGE WAS RECOGNITION THAT IN 
-!!                            THE LFM 0.33 AND 0.66 WERE MEASURED
-!!                            FROM THE SURFACE TO THE TROPOPAUSE,
-!!                            NOT THE TOP OF THE MODEL.
-!!   93-09-13  RUSS TREADON - RH CALCULATIONS WERE MADE INTERNAL
-!!                            TO THE ROUTINE.
-!!   96-03-04  MIKE BALDWIN - CHANGE PW CALC TO INCLUDE CLD WTR 
-!!   98-06-16  T BLACK      - CONVERSION FROM 1-D TO 2-D
-!!   98-08-17  MIKE BALDWIN - COMPUTE RH OVER ICE
-!!   98-12-22  MIKE BALDWIN - BACK OUT RH OVER ICE
-!!   00-01-04  JIM TUCCILLO - MPI VERSION
-!!   02-04-24  MIKE BALDWIN - WRF VERSION
-!!   19-10-30  Bo CUI - REMOVE "GOTO" STATEMENT
-!!   20-11-10  JESSE MENG - USE UPP_PHYSICS MODULE
-!!     
-!!     
-!! USAGE:    CALL LFMFLD(RH3310,RH6610,RH3366,PW3310)
-!!   INPUT ARGUMENT LIST:
-!!     NONE
-!!
-!!   OUTPUT ARGUMENT LIST: 
-!!     RH3310   - SIGMA LAYER 0.33-1.00 MEAN RELATIVE HUMIDITY.
-!!     RH6610   - SIGMA LAYER 0.66-1.00 MEAN RELATIVE HUMIDITY.
-!!     RH3366   - SIGMA LAYER 0.33-0.66 MEAN RELATIVE HUMIDITY.
-!!     PW3310   - SIGMA LAYER 0.33-1.00 PRECIPITABLE WATER.
-!!     
-!!   OUTPUT FILES:
-!!     NONE
-!!     
-!!   LIBRARY:
-!!     COMMON   - 
-!!                MAPOT
-!!                LOOPS
-!!                OPTIONS
-!!
-!!   ATTRIBUTES:
-!!     LANGUAGE: FORTRAN
-!!     MACHINE : CRAY C-90
-!!
+!> @brief lfmfld() computes layer mean LFM fields.
+!>
+!> This routine computes three layer mean relative humidities
+!> and a precipitable water field from ETA level data.  The
+!> computed fields are intended to mimic similar fields com-
+!> puted by the LFM.  The algorithm used here is fairly pri-
+!> mative.
+!> <pre>
+!> In each column above a mass point on the ETA grid we set the following target pressures:
+!>     Sigma layer 1.00 pressure:  Surface pressure
+!>     Sigma layer 0.66 pressure:  0.50 * Surface pressure
+!>     Sigma layer 0.33 pressure:  0.4356 * Surface pressure
+!> </pre>
+!> Given there pressures a surface up summation is made of
+!> relative humidity and/or precipitable water between these
+!> target pressures.  Each term in the summation is weighted
+!> By the thickness of the ETA layer.  The final layer mean
+!> is this sum normalized by the total depth of the layer. 
+!> There is, obviously, no normalization for precipitable water.
+!>
+!> @param[out] RH3310 Sigma layer 0.33-1.00 mean relative humidity.
+!> @param[out] RH6610 Sigma layer 0.66-1.00 mean relative humidity.
+!> @param[out] RH3366 Sigma layer 0.33-0.66 mean relative humidity.
+!> @param[out] PW3310 Sigma layer 0.33-1.00 precipitable water.
+!>
+!> ### Program History Log
+!> Date | Programmer | Comments
+!> -----|------------|---------
+!> 1992-12-22 | Russ Treadon | Initial
+!> 1993-07-27 | Russ Treadon | Modified summation limits from 0.66*PSFC to 0.75*PSFC and 0.33*PSFC to 0.50*PSFC, where PSFC is the surfaces pressure.  The reason for this change was recognition that in the LFM 0.33 and 0.66 were measured from the surface to the tropopause not the top of the model.
+!> 1993-09-13 | Russ Treadon | RH calculations were made internal to the routine.
+!> 1996-03-04 | Mike Baldwin | Change PW CALC to include CLD WTR
+!> 1998-06-16 | T Black      | Conversion from 1-D to 2-D
+!> 1998-08-17 | Mike Baldwin | Compute RH over ice
+!> 1998-12-22 | Mike Baldwin | Back out RH over ice
+!> 2000-01-04 | Jim Tuccillo | MPI Version
+!> 2002-04-24 | Mike Baldwin | WRF Version
+!> 2019-10-30 | Bo Cui       | Remove "GOTO" statement
+!> 2020-11-10 | Jesse Meng   | Use UPP_PHYSICS Module
+!>
+!> @author Russ Treadon W/NP2 @date 1992-12-22
       SUBROUTINE LFMFLD(RH3310,RH6610,RH3366,PW3310)
 
 !     

sorc/ncep_post.fd/LFMFLD_GFS.f

@@ -1,74 +1,46 @@
 !> @file
-!                .      .    .     
-!> SUBPROGRAM:    LFMFLD      COMPUTES LAYER MEAN LFM FIELDS
-!!   PRGRMMR: TREADON         ORG: W/NP2      DATE: 92-12-22
-!!     
-!! ABSTRACT:
-!!     THIS ROUTINE COMPUTES THREE LAYER MEAN RELATIVE HUMIDITIES
-!!     AND A PRECIPITABLE WATER FIELD FROM ETA LEVEL DATA.  THE
-!!     COMPUTED FIELDS ARE INTENDED TO MIMIC SIMILAR FIELDS COM-
-!!     PUTED BY THE LFM.  THE ALGORITHM USED HERE IS FAIRLY PRI-
-!!     MATIVE.  IN EACH COLUMN ABOVE A MASS POINT ON THE ETA GRID
-!!     WE SET THE FOLLOWING TARGET PRESSURES:
-!!         SIGMA LAYER 1.00 PRESSURE:  SURFACE PRESSURE
-!!         SIGMA LAYER 0.66 PRESSURE:  0.50 * SURFACE PRESSURE
-!!         SIGMA LAYER 0.33 PRESSURE:  0.4356 * SURFACE PRESSURE
-!!     GIVEN THESE PRESSURES A SURFACE UP SUMMATION IS MADE OF 
-!!     RELATIVE HUMIDITY AND/OR PRECIPITABLE WATER BETWEEN THESE
-!!     TARGET PRESSURES.  EACH TERM IN THE SUMMATION IS WEIGHTED
-!!     BY THE THICKNESS OF THE ETA LAYER.  THE FINAL LAYER MEAN
-!!     IS THIS SUM NORMALIZED BY THE TOTAL DEPTH OF THE LAYER.  
-!!     THERE IS, OBVIOUSLY, NO NORMALIZATION FOR PRECIPITABLE WATER.
-!!
-!!     
-!! PROGRAM HISTORY LOG:
-!!   92-12-22  RUSS TREADON
-!!   93-07-27  RUSS TREADON - MODIFIED SUMMATION LIMITS FROM
-!!                            0.66*PSFC TO 0.75*PSFC AND 0.33*PSFC 
-!!                            TO 0.50*PSFC, WHERE PSFC IS THE
-!!                            SURFACES PRESSURE.  THE REASON FOR
-!!                            THIS CHANGE WAS RECOGNITION THAT IN 
-!!                            THE LFM 0.33 AND 0.66 WERE MEASURED
-!!                            FROM THE SURFACE TO THE TROPOPAUSE,
-!!                            NOT THE TOP OF THE MODEL.
-!!   93-09-13  RUSS TREADON - RH CALCULATIONS WERE MADE INTERNAL
-!!                            TO THE ROUTINE.
-!!   96-03-04  MIKE BALDWIN - CHANGE PW CALC TO INCLUDE CLD WTR 
-!!   98-06-16  T BLACK      - CONVERSION FROM 1-D TO 2-D
-!!   98-08-17  MIKE BALDWIN - COMPUTE RH OVER ICE
-!!   98-12-22  MIKE BALDWIN - BACK OUT RH OVER ICE
-!!   00-01-04  JIM TUCCILLO - MPI VERSION
-!!   02-04-24  MIKE BALDWIN - WRF VERSION
-!!   06-11-06 H CHUANG      - MODIFY TO OUTPUT GFS LFM FIELDS WHICH 
-!!                            HAVE DIFFERENT THICKNESS AS MESO AND USE DP
-!!                            RATHER THAN DZ 
-!!   19-10-30  Bo CUI - REMOVE "GOTO" STATEMENT
-!!   20-11-10  JESSE MENG   - USE UPP_PHYSICS MODULE
-!!     
-!!     
-!! USAGE:    CALL LFMFLD(RH3310,RH6610,RH3366,PW3310)
-!!   INPUT ARGUMENT LIST:
-!!     NONE
-!!
-!!   OUTPUT ARGUMENT LIST: 
-!!     RH3310   - SIGMA LAYER 0.33-1.00 MEAN RELATIVE HUMIDITY.
-!!     RH6610   - SIGMA LAYER 0.66-1.00 MEAN RELATIVE HUMIDITY.
-!!     RH3366   - SIGMA LAYER 0.33-0.66 MEAN RELATIVE HUMIDITY.
-!!     PW3310   - SIGMA LAYER 0.33-1.00 PRECIPITABLE WATER.
-!!     
-!!   OUTPUT FILES:
-!!     NONE
-!!     
-!!   LIBRARY:
-!!     COMMON   - 
-!!                MAPOT
-!!                LOOPS
-!!                OPTIONS
-!!
-!!   ATTRIBUTES:
-!!     LANGUAGE: FORTRAN
-!!     MACHINE : CRAY C-90
-!!
+!> @brief lfmfld_gfs() computes layer mean LFM fields.
+!>
+!> This routine computes three layer mean relative humidities
+!> and a precipitable water field from ETA level data.  The
+!> computed fields are intended to mimic similar fields com-
+!> puted by the LFM.  The algorithm used here is fairly pri-
+!> mative.
+!> <pre>
+!> In each column above a mass point on the ETA grid we set the following target pressures:
+!>     Sigma layer 1.00 pressure:  Surface pressure
+!>     Sigma layer 0.66 pressure:  0.50 * Surface pressure
+!>     Sigma layer 0.33 pressure:  0.4356 * Surface pressure
+!> </pre>
+!> Given there pressures a surface up summation is made of
+!> relative humidity and/or precipitable water between these
+!> target pressures.  Each term in the summation is weighted
+!> By the thickness of the ETA layer.  The final layer mean
+!> is this sum normalized by the total depth of the layer. 
+!> There is, obviously, no normalization for precipitable water.
+!>
+!> @param[out] RH3310 Sigma layer 0.33-1.00 mean relative humidity.
+!> @param[out] RH6610 Sigma layer 0.66-1.00 mean relative humidity.
+!> @param[out] RH3366 Sigma layer 0.33-0.66 mean relative humidity.
+!> @param[out] PW3310 Sigma layer 0.33-1.00 precipitable water.
+!>
+!> ### Program History Log
+!> Date | Programmer | Comments
+!> -----|------------|---------
+!> 1992-12-22 | Russ Treadon | Initial
+!> 1993-07-27 | Russ Treadon | Modified summation limits from 0.66*PSFC to 0.75*PSFC and 0.33*PSFC to 0.50*PSFC, where PSFC is the surfaces pressure.  The reason for this change was recognition that in the LFM 0.33 and 0.66 were measured from the surface to the tropopause not the top of the model.
+!> 1993-09-13 | Russ Treadon | RH calculations were made internal to the routine.
+!> 1996-03-04 | Mike Baldwin | Change PW CALC to include CLD WTR
+!> 1998-06-16 | T Black      | Conversion from 1-D to 2-D
+!> 1998-08-17 | Mike Baldwin | Compute RH over ice
+!> 1998-12-22 | Mike Baldwin | Back out RH over ice
+!> 2000-01-04 | Jim Tuccillo | MPI Version
+!> 2002-04-24 | Mike Baldwin | WRF Version
+!> 2006-11-06 | H CHUANG     | Modify to output GFS LFM fields which have different thickness as MESO and use DP rather than DZ
+!> 2019-10-30 | Bo Cui       | Remove "GOTO" statement
+!> 2020-11-10 | Jesse Meng   | Use UPP_PHYSICS Module
+!>
+!> @author Russ Treadon W/NP2 @date 1992-12-22
       SUBROUTINE LFMFLD_GFS(RH4410,RH7294,RH4472,RH3310)
 
 !     

sorc/ncep_post.fd/MDL2P.f

@@ -1,64 +1,36 @@
 !> @file
-!                .      .    .     
-!> SUBPROGRAM:    MDL2P       VERT INTRP OF MODEL LVLS TO PRESSURE
-!!   PRGRMMR: BLACK           ORG: W/NP22     DATE: 99-09-23       
-!!     
-!! ABSTRACT:
-!!     FOR MOST APPLICATIONS THIS ROUTINE IS THE WORKHORSE OF THE POST PROCESSOR.
-!!     IN A NUTSHELL IT INTERPOLATES DATA FROM MODEL TO PRESSURE SURFACES.
-!!     IT ORIGINATED FROM THE VERTICAL INTERPOLATION CODE IN THE OLD ETA
-!!     POST PROCESSOR SUBROUTINE OUTMAP AND IS A REVISION OF SUBROUTINE ETA2P.
-!!     
-!! PROGRAM HISTORY LOG:
-!!   99-09-23  T BLACK       - REWRITTEN FROM ETA2P
-!!   01-10-25  H CHUANG - MODIFIED TO PROCESS HYBRID MODEL OUTPUT
-!!   02-06-12  MIKE BALDWIN - WRF VERSION
-!!   02-07-29  H CHUANG - ADD UNDERGROUND FIELDS AND MEMBRANE SLP FOR WRF
-!!   04-11-24  H CHUANG - ADD FERRIER'S HYDROMETEOR FIELD
-!!   05-07-07  B ZHOU   - ADD RSM MODEL for SLP  
-!!   05--8-30  B ZHOU   - ADD AVIATION PRODUCTS: ICING, CAT, LLWS COMPUTATION
-!!   08-01-01  H CHUANG - ADD GFS D3D FIELDS TO VERTICAL INTERPOLATION
-!!   10-07-01  SMIRNOVA AND HU - ADD RR CHANGES
-!!   10-12-30  H CHUANG - ADD HAINES INDEX TO SUPPORT FIRE WEATHER
-!!   11-02-06  J Wang   - ADD grib2 option TO SUPPORT FIRE WEATHER
-!!   12-01-11  S LU     - ADD GOCART AEROSOLS
-!!   13-08-01  S Moorthi - some optimization
-!!   14-02-26  S Moorthi - threading datapd assignment
-!!   19-10-30  B CUI - REMOVE "GOTO" STATEMENT
-!!   20-03-25  J MENG   - remove grib1
-!!   20-05-20  J MENG   - CALRH unification with NAM scheme
-!!   20-11-10  J MENG   - USE UPP_PHYSICS MODULE
-!!   21-03-11  B Cui - change local arrays to dimension (im,jsta:jend)
-!!   21-04-01  J MENG   - COMPUTATION ON DEFINED POINTS ONLY
-!!
-!! USAGE:    CALL MDL2P
-!!   INPUT ARGUMENT LIST:
-!!
-!!   OUTPUT ARGUMENT LIST: 
-!!     NONE       
-!!     
-!!   OUTPUT FILES:
-!!     NONE
-!!     
-!!   SUBPROGRAMS CALLED:
-!!     UTILITIES:
-!!       SCLFLD   - SCALE ARRAY ELEMENTS BY CONSTANT.
-!!       CALPOT   - COMPUTE POTENTIAL TEMPERATURE.
-!!       CALRH    - COMPUTE RELATIVE HUMIDITY.
-!!       CALDWP   - COMPUTE DEWPOINT TEMPERATURE.
-!!       BOUND    - BOUND ARRAY ELEMENTS BETWEEN LOWER AND UPPER LIMITS.
-!!       CALMCVG  - COMPUTE MOISTURE CONVERGENCE.
-!!       CALVOR   - COMPUTE ABSOLUTE VORTICITY.
-!!       CALSTRM  - COMPUTE GEOSTROPHIC STREAMFUNCTION.
-!!
-!!     LIBRARY:
-!!       COMMON   - CTLBLK
-!!                  RQSTFLD
-!!     
-!!   ATTRIBUTES:
-!!     LANGUAGE: FORTRAN 90
-!!     MACHINE : IBM SP
-!!
+!> @brief mdl2p() computes vert intrp of model lvls to pressure.
+!>
+!> For most applications this routine is the workhorse of the post processor.
+!> In a nutshell it interpolates data from model to pressure surfaces.
+!> It origiaated from the vertical interpolation code in the old ETA
+!> post processor subroutine outmap() and is a revision of subroutine eta2p().
+!>
+!> ### Program History Log
+!> Date | Programmer | Comments
+!> -----|------------|---------
+!> 1999-09-23 | T Black         | Rewritten from eta2p()
+!> 2001-10-25 | H Chuang        | Modified to process hybrid model output
+!> 2002-06-12 | Mike Baldwin    | WRF Version
+!> 2002-07-29 | H Chuang        | Add underground fields and membrane SLP for WRF
+!> 2004-11-24 | H Chuang        | Add FERRIER's hydrometeor field
+!> 2005-07-07 | B Zhou          | Add RSM model for SLP
+!> 2005--8-30 | B Zhou          | Add aviation products: ICING, CAT, LLWS computation
+!> 2008-01-01 | H Chuang        | Add GFS D3D fields to vertical interpolation
+!> 2010-07-01 | Smirnova and Hu | Add RR changes
+!> 2010-12-30 | H Chuang        | Add Haines index to support fire weather
+!> 2011-02-06 | J Wang          | Add grib2 option to support fire weather
+!> 2012-01-11 | S Lu            | Add GOCART aerosols
+!> 2013-08-01 | S Moorthi       | Some optimization
+!> 2014-02-26 | S Moorthi       | Threading datapd assignment
+!> 2019-10-30 | B Cui           | Remove "GOTO" statement
+!> 2020-03-25 | J Meng          | Remove grib1
+!> 2020-05-20 | J Meng          | CALRH unification with NAM scheme
+!> 2020-11-10 | J Meng          | Use UPP_PHYSICS module
+!> 2021-03-11 | B Cui           | Change local arrays to dimension (im,jsta:jend)
+!> 2021-04-01 | J Meng          | Computation on defined points only
+!>
+!> @author T Black W/NP2 @date 1999-09-23
       SUBROUTINE MDL2P(iostatusD3D)
 
 !

sorc/ncep_post.fd/MDL2STD_P.f

@@ -1,40 +1,18 @@
 !> @file
-!                .      .    .     
-!> SUBPROGRAM:    MDL2STD_P       VERT INTRP OF MODEL LVLS TO STANDARD ATMOSPEHRIC PRESSURE
-!!   PRGRMMR: Y Mao           ORG: W/NP22     DATE: Sep 2019
-!!     
-!! ABSTRACT:
-!!     ORIGINATED FROM MISCLN.f. THIS ROUTINE INTERPOLATE TO STANDARD
-!!     ATMOSPHERIC PRESSURE, INSTEAD OF MODEL PRESSURE
-!!     
-!! PROGRAM HISTORY LOG:
-!!   19-09-24  Y Mao       - REWRITTEN FROM MISCLN.f
-!!   20-05-20  J MENG      - CALRH unification with NAM scheme
-!!   20-11-10  J MENG      - USE UPP_PHYSICS MODULE
-!!   21-03-11  B Cui - change local arrays to dimension (im,jsta:jend)
-!!
-!! USAGE:    CALL MDL2STD_P
-!!   INPUT ARGUMENT LIST:
-!!
-!!   OUTPUT ARGUMENT LIST: 
-!!     NONE       
-!!     
-!!   OUTPUT FILES:
-!!     NONE
-!!     
-!!   SUBPROGRAMS CALLED:
-!!     UTILITIES:
-!!       FDLVL_UV   - COMPUTE FD LEVEL WIND (AGL OR MSL).
-!!       FDLVL_MASS - COMPUTE FD LEVEL MASS (AGL OR MSL).
-!!
-!!     LIBRARY:
-!!       COMMON   - CTLBLK
-!!                  RQSTFLD
-!!     
-!!   ATTRIBUTES:
-!!     LANGUAGE: FORTRAN 90
-!!     MACHINE : IBM SP
-!!
+!> @brief  mdl2std_p() vert intrp of model lvls to standard atmospheric pressure.
+!>
+!> Originated from MISCLN.f. This routine interpolate to standard
+!> atmospheric pressure, instead of model pressure.
+!>
+!> ### Program History Log
+!> Date | Programmer | Comments
+!> -----|------------|---------
+!> 2019-09-24 | Y Mao  | Rewritten from MISCLN.f
+!> 2020-05-20 | J Meng | CALRH unification with NAM scheme
+!> 2020-11-10 | J Meng | Use UPP_PHYSICS Module
+!> 2021-03-11 | B Cui  | Change local arrays to dimension (im,jsta:jend)
+!>
+!> @author Y Mao W/NP22 @date 2019-09-24
       SUBROUTINE MDL2STD_P()
 
 !

sorc/ncep_post.fd/MDL2THANDPV.f

@@ -1,44 +1,23 @@
 !> @file
-!
-!> SUBPROGRAM:    MDL2THANDPV       VERT INTRP OF MODEL LVLS TO ISENTROPIC AND PV
-!!   PRGRMMR: CHUANG           ORG: W/NP22     DATE: 07-03-26       
-!!     
-!! ABSTRACT:
-!!     FOR MOST APPLICATIONS THIS ROUTINE IS THE WORKHORSE
-!!     OF THE POST PROCESSOR.  IN A NUTSHELL IT INTERPOLATES
-!!     DATA FROM MODEL TO THETA AND PV SURFACES.  
-!!
-!!   PROGRAM HISTORY
-!!     11-02-06  J. WANG ADD GRIB2 OPTION
-!!     14-03-06  S. Moorthi - updated for threading and some optimization
-!!     16-12-19  G.P. Lou - Added A-grid regional models
-!!     20-03-25  J MENG - remove grib1
-!!     20-03-25  J MENG - remove grib1
-!!     20-11-10  J MENG - USE UPP_MATH and UPP_PHYSICS MODULES
-!!     21-03-11  B Cui - change local arrays to dimension (im,jsta:jend)
-!!     
-!!
-!! USAGE:    CALL MDL2THANDPV
-!!   INPUT ARGUMENT LIST:
-!!
-!!   OUTPUT ARGUMENT LIST: 
-!!     NONE       
-!!     
-!!   OUTPUT FILES:
-!!     NONE
-!!     
-!!   SUBPROGRAMS CALLED:
-!!     UTILITIES:
-!!       PVETC   - 
-!!       P2TH   - 
-!!       P2PV    - 
-!!       COMMON   - CTLBLK
-!!                  RQSTFLD
-!!     
-!!   ATTRIBUTES:
-!!     LANGUAGE: FORTRAN 90
-!!     MACHINE : IBM SP
-!!
+!> @brief mdl2thandpv() vert intrp of model lvls to isentropic and PV.
+!>
+!> For most applications this routine is the workhorse
+!> of the post processor.  In a nutshell it interpolates
+!> data from model to THETA and PV surfaces.
+!>
+!> ### Program History Log
+!> Date | Programmer | Comments
+!> -----|------------|---------
+!> 2007-03-26 | Chuang     | Initial
+!> 2011-02-06 | J. Wang    | Add GRIB2 Option
+!> 2014-03-06 | S. Moorthi | Updated for threading and some optimization
+!> 2016-12-19 | G.P. Lou   | Added A-grid regional models
+!> 2020-03-25 | J Meng     | Remove grib1
+!> 2020-03-25 | J Meng     | Remove grib1
+!> 2020-11-10 | J Meng     | Use UPP_MATH and UPP_PHYSICS Modules
+!> 2021-03-11 | B Cui      | Change local arrays to dimension (im,jsta:jend)
+!>
+!> @author Chuang W/NP22 @date 2007-03-26
       SUBROUTINE MDL2THANDPV(kth,kpv,th,pv)
 
 !

sorc/ncep_post.fd/MSFPS.f

@@ -1,25 +1,18 @@
 !> @file
-!                .      .    .
-!> SUBPROGRAM:    MSFPS Computes the map scale factor for a Polar
-!!                      Stereographic grid at a give latitude.
-!!
-!! ABSTRACT:
-!!     Computes the map scale factor for a Polar Stereographic
-!!     grid at a give latitude.
-!!
-!! PROGRAM HISTORY LOG:
-!!   06-11-01 SWIPED FROM WRF SI PACKAGE BY ROZUMALSKI
-!!
-!!   INPUT ARGUMENT LIST:
-!!     LAT     - LATITUDE AT WHICH MAP FACTOR IS VALID
-!!     TRUELAT1 - TRUELAT 1
-!!
-!!   OUTPUT ARGUMENT LIST:
-!!     MSF - MAP SCALE FACTOR
-!!
-!!   ATTRIBUTES:
-!!     LANGUAGE: FORTRAN
-!!
+!> @brief msfps() computes the map scale factor for a polar stereographic grid at a give latitude.
+!>
+!> This subroutine computes the map scale factor for a polar stereographic grid at a give latitude.
+!>
+!> @param[in] LAT Latitude at which map factor is valid.
+!> @param[in] TRUELAT1 TRUELAT 1.
+!> @param[out] MSF Map scale factor.
+!>
+!> ### Program History Log
+!> Date | Programmer | Comments
+!> -----|------------|---------
+!> 2006-11-01 | Rozumalski | Swiped from WRF si package
+!>
+!> @author Rozumalski @date 2006-11-01
       SUBROUTINE MSFPS(LAT,TRUELAT1,MSF)