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