Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Doxygen in GET_BITS.f, GPVS.f, LFMFLD.f, LFMFLD_GFS.f, MDL2P.f, MDL2STD_P.f, MDL2THANDPV.f, and MSFPS.f. #474

Merged
merged 3 commits into from
Apr 7, 2022
Merged

Doxygen in GET_BITS.f, GPVS.f, LFMFLD.f, LFMFLD_GFS.f, MDL2P.f, MDL2STD_P.f, MDL2THANDPV.f, and MSFPS.f. #474

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a159ccf
This is part of Issue #392.
kayeekayee Apr 6, 2022
fdaaa86
Minor fix.
kayeekayee Apr 6, 2022
5bcae40
Merge branch 'NOAA-EMC:develop' into doxygen_GET_BITS_GPVS_LFMFLD_LFM…
kayeekayee Apr 7, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
142 changes: 63 additions & 79 deletions sorc/ncep_post.fd/GET_BITS.f
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)

Expand Down Expand Up @@ -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>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably just a numbered list here would work better than the pre tag.

!>
!> 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
Expand Down
170 changes: 69 additions & 101 deletions sorc/ncep_post.fd/GPVS.f
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
! ******************************************************************

Expand Down Expand Up @@ -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).
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is CB?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@WenMeng-NOAA @HuiyaChuang-NOAA
Do you know what are the (CB) stand for?
line 67: FPVS real saturation vapor pressure in kilopascals (CB).
line 139: FPVSX real saturation vapor pressure in kilopascals (CB).

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@kayeekayee I would defer this question to @HuiyaChuang-NOAA.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This kind of confusion is exactly the reason that we should be very cautious using abbreviations in documentation!

!>
!> ### 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
!
Expand Down Expand Up @@ -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
!
Expand Down
Loading