COMPARE_FLOAT_NUMBERS.F90 Subprograms

Last modified: Fri Feb 11 14:23:42 2005.


List of Subprograms


Subprogram Descriptions

.EQUALTO.

[Next Subprogram] [List of Subprograms]
 NAME:
       .EqualTo.

 PURPOSE:
       Relational operator to test the equality of floating point numbers.

 CATEGORY:
       Utility

 LANGUAGE:
       Fortran-95

 CALLING SEQUENCE:
       IF ( x .EqualTo. y ) THEN
         .....
       END IF

 OPERANDS:
       x, y:        Two congruent floating point data objects to compare.
                    UNITS:      N/A
                    TYPE:       REAL( Single )   [ == default real]
                                  OR
                                REAL( Double )
                    DIMENSION:  Scalar, or any allowed rank array.

 OPERATOR RESULT:
       (x .EqualTo. y)    The result is a logical value indicating whether
                          the operands are equal to within numerical precision
                          UNITS:      N/A
                          TYPE:       LOGICAL
                          DIMENSION:  Same as operands.

 PROCEDURE:
       The test performed is

         ABS( x - y ) < SPACING( MAX(ABS(x),ABS(y)) )

       If the result is .TRUE., the numbers are considered equal.

 CREATION HISTORY:
       Written by:     Paul van Delst, CIMSS/SSEC 30-Aug-2003
                       paul.vandelst@ssec.wisc.edu

(See Compare_Float_Numbers.f90)


.GREATERTHAN.

[Previous Subprogram] [Next Subprogram] [List of Subprograms]
 NAME:
       .GreaterThan.

 PURPOSE:
       Relational operator to test if one operand is greater than another.

 CATEGORY:
       Utility

 LANGUAGE:
       Fortran-95

 CALLING SEQUENCE:
       IF ( x .GreaterThan. y ) THEN
         .....
       END IF

 OPERANDS:
       x, y:        Two congruent floating point data objects to compare.
                    UNITS:      N/A
                    TYPE:       REAL( Single )   [ == default real]
                                  OR
                                REAL( Double )
                    DIMENSION:  Scalar, or any allowed rank array.

 OPERATOR RESULT:
       (x .GreaterThan. y)    The result is a logical value indicating whether
                              the operand x is greater than y by more than
                              the spacing between representable floating point
                              numbers.
                              UNITS:      N/A
                              TYPE:       LOGICAL
                              DIMENSION:  Same as operands.

 PROCEDURE:
       The test performed is

         ( x - y ) >= SPACING( MAX(ABS(x),ABS(y)) )

       If the result is .TRUE., x is considered greater than y.

 CREATION HISTORY:
       Written by:     Paul van Delst, CIMSS/SSEC 30-Aug-2003
                       paul.vandelst@ssec.wisc.edu

(See Compare_Float_Numbers.f90)


.LESSTHAN.

[Previous Subprogram] [Next Subprogram] [List of Subprograms]
 NAME:
       .LessThan.

 PURPOSE:
       Relational operator to test if one operand is less than another.

 CATEGORY:
       Utility

 LANGUAGE:
       Fortran-95

 CALLING SEQUENCE:
       IF ( x .LessThan. y ) THEN
         .....
       END IF

 OPERANDS:
       x, y:        Two congruent floating point data objects to compare.
                    UNITS:      N/A
                    TYPE:       REAL( Single )   [ == default real]
                                  OR
                                REAL( Double )
                    DIMENSION:  Scalar, or any allowed rank array.

 OPERATOR RESULT:
       (x .LessThan. y)    The result is a logical value indicating whether
                           the operand x is less than y by more than the
                           spacing between representable floating point
                           numbers.
                           UNITS:      N/A
                           TYPE:       LOGICAL
                           DIMENSION:  Same as operands.

 PROCEDURE:
       The test performed is

         ( y - x ) >= SPACING( MAX(ABS(x),ABS(y)) )

       If the result is .TRUE., x is considered less than y.

 CREATION HISTORY:
       Written by:     Paul van Delst, CIMSS/SSEC 30-Aug-2003
                       paul.vandelst@ssec.wisc.edu

(See Compare_Float_Numbers.f90)


COMPARE_FLOAT

[Previous Subprogram] [List of Subprograms]
 NAME:
       Compare_Float

 PURPOSE:
       Function to compare floating point scalars and arrays with adjustible
       precision tolerance.

 CATEGORY:
       Utility

 LANGUAGE:
       Fortran-95

 CALLING SEQUENCE:
       Result = Compare_Float( x, y,     &  ! Input
                               ULP = ULP )  ! Optional input

 INPUT ARGUMENTS:
       x, y:        Two congruent floating point data objects to compare.
                    UNITS:      N/A
                    TYPE:       REAL( Single )   [ == default real]
                                  OR
                                REAL( Double )
                    DIMENSION:  Scalar, or any allowed rank array.
                    ATTRIBUTES: INTENT( IN )

 OPTIONAL INPUT ARGUMENTS:
       ULP:         Unit of data precision. The acronym stands for "unit in
                    the last place," the smallest possible increment or decrement
                    that can be made using a machine's floating point arithmetic.
                    A 0.5 ulp maximum error is the best you could hope for, since
                    this corresponds to always rounding to the nearest representable
                    floating-point number. Value must be positive - if a negative
                    value is supplied, the absolute value is used.
                    If not specified, the default value is 1.
                    UNITS:      N/A
                    TYPE:       INTEGER
                    DIMENSION:  Scalar
                    ATTRIBUTES: OPTIONAL, INTENT( IN )
                  
 OUTPUT ARGUMENTS:
       None.

 OPTIONAL OUTPUT ARGUMENTS:
       None.

 FUNCTION RESULT:
       Result:      The return value is a logical value indicating whether
                    the inputs are equal (to within the required precision)
                    .TRUE.  - if the floating point numbers are equal to
                              within the specified tolerance. 
                    .FALSE. - if the floating point numbers are different.
                    UNITS:      N/A
                    TYPE:       LOGICAL
                    DIMENSION:  Scalar

 CALLS:
       None.

 SIDE EFFECTS:
       None.

 RESTRICTIONS:
       None.

 PROCEDURE:
       The test performed is

         ABS( x - y ) < ( ULP * SPACING( MAX(ABS(x),ABS(y)) ) )

       If the result is .TRUE., the numbers are considered equal.

       The intrinsic function SPACING(x) returns the absolute spacing of numbers
       near the value of x,

                      {     EXPONENT(x)-DIGITS(x)
                      {  2.0                        for x /= 0
         SPACING(x) = {
                      {  
                      {  TINY(x)                    for x == 0

       The ULP optional argument scales the comparison.

       James Van Buskirk and James Giles suggested this method for floating
       point comparisons in the comp.lang.fortran newsgroup.

 CREATION HISTORY:
       Written by:     Paul van Delst, CIMSS/SSEC 01-Apr-2003
                       paul.vandelst@ssec.wisc.edu

(See Compare_Float_Numbers.f90)