The IEEE modules
IEEE arithmetic is the floating-point model every machine this course runs on follows, and Fortran is the only mainstream language with it in the standard library. Three modules expose it: values, exception flags and rounding, plus a set of enquiries that say what the hardware supports. This lesson asks the machine what it supports, builds a NaN and an infinity, raises two real exceptions and changes the rounding mode, with the numbers that came out.
The three IEEE modules
ieee_arithmetic holds the class enquiry and the value constructor: ieee_is_nan, ieee_is_finite, ieee_value and the ieee_support_* functions. ieee_exceptions holds the flags: ieee_get_flag, ieee_set_flag and the named exceptions. ieee_features declares which features the program promises to use, which the compiler may need to know to keep an operation in a register.
They are intrinsic modules, so the statement is use, intrinsic :: ieee_arithmetic. All three are part of the compiler and no library has to be linked.
The file ieee.f90:
program ieeedemo
use, intrinsic :: ieee_arithmetic
use, intrinsic :: ieee_exceptions
implicit none
real :: x, y, a, b, one, three
logical :: flag
type(ieee_round_type) :: mode
print '(a,l1)', 'support nan = ', ieee_support_nan(x)
print '(a,l1)', 'support inf = ', ieee_support_inf(x)
print '(a,l1)', 'support denormal = ', ieee_support_denormal(x)
x = ieee_value(x, ieee_quiet_nan)
print '(a,l1)', 'x is nan = ', ieee_is_nan(x)
print '(a,l1)', 'x is finite = ', ieee_is_finite(x)
y = ieee_value(y, ieee_positive_inf)
print '(a,l1)', 'y is finite = ', ieee_is_finite(y)
call ieee_set_flag(ieee_all, .false.)
a = 0.0
b = 1.0
y = b / a
call ieee_get_flag(ieee_divide_by_zero, flag)
print '(a,l1)', 'divide_by_zero = ', flag
print '(a,f8.1)', 'y = ', y
call ieee_set_flag(ieee_all, .false.)
y = huge(b)
y = y * 2.0
call ieee_get_flag(ieee_overflow, flag)
print '(a,l1)', 'overflow = ', flag
one = 1.0
three = 3.0
call ieee_set_rounding_mode(ieee_up)
call ieee_get_rounding_mode(mode)
print '(a,l1)', 'rounding is up = ', mode == ieee_up
print '(a,es15.8)', '1/3 rounded up = ', one / three
call ieee_set_rounding_mode(ieee_nearest)
print '(a,es15.8)', '1/3 to nearest = ', one / three
end program ieeedemo
gfortran -Wall -Wextra -std=f2018 ieee.f90 -o ieee
./ieee
support nan = T
support inf = T
support denormal = T
x is nan = T
x is finite = F
y is finite = F
divide_by_zero = T
y = Infinity
overflow = T
rounding is up = T
1/3 rounded up = 3.33333344E-01
1/3 to nearest = 3.33333343E-01
What this build supports
The three ieee_support_* enquiries answer for the real kind of their argument, and this machine answers true to all of them: NaNs, infinities, denormal numbers and the IEEE square root are all available in single precision. The enquiry exists because the standard does not require them: a machine without a NaN can still compile the program, and a portable program asks before it builds one.
The argument is not decoration. ieee_support_nan(x) asks about the kind of x, so a program that uses both single and double precision asks twice, and a compiler for a machine with two different floating-point units may answer differently.
IEEEE_VALUE and the special values
ieee_value(x, ieee_quiet_nan) returns a NaN of the kind of its first argument, and the first argument is only there for the kind: its value is not used. The classes are ieee_quiet_nan, ieee_signaling_nan, ieee_positive_inf, ieee_negative_inf, ieee_positive_zero, ieee_negative_zero and the two denormals.
ieee_is_nan is the only reliable test for a NaN, and ieee_is_finite is the test for a number that is neither a NaN nor an infinity. A division by zero produced the infinity that the run prints: b / a with a zero and b one is Infinity, formatted by f8.1 as nine characters, and ieee_is_finite says it is not a number in the ordinary sense. The next lesson is about these values and the arithmetic they take part in.
The exception flags
ieee_set_flag(ieee_all, .false.) clears every sticky flag, and each operation that raises an exception sets one. The run shows two of them: the division by zero set ieee_divide_by_zero, and multiplying the largest finite real by two set ieee_overflow. The flags stay set until a program clears them, which is why the program clears them twice.
A flag is a record, not a trap: the operation completes with a defined value, an infinity or a NaN, and the program can look afterwards. Turning the flag into a stop is the job of -ffpe-trap, which is lesson 115. The two mechanisms use the same hardware state, so a program that wants to check a flag has to be built without the trap for that flag.
The rounding mode
ieee_set_rounding_mode(ieee_up) changes how every subsequent operation rounds, and the last two lines are the proof: one third rounded up ends in a four, and the same division rounded to nearest ends in a three. The difference is one unit in the last place, which is the smallest difference a single-precision value can have.
The mode is a property of the process, not of a variable, so it affects every thread and every routine called afterwards. A program that changes it has to change it back, or state that everything after that point is deliberately rounded upward, which is a legitimate technique in interval arithmetic and a bug everywhere else. ieee_get_rounding_mode is how a procedure saves and restores the mode it found.
A name without its module
An IEEE function is not an intrinsic in the sense of sqrt; it lives in a module and needs the use:
program badieee
implicit none
real :: x
logical :: f
x = 1.0
f = ieee_is_nan(x)
print *, f
end program badieee
gfortran -Wall -Wextra -std=f2018 badieee.f90 -o badieee
badieee.f90:7:6:
7 | f = ieee_is_nan(x)
| 1
Error: Function 'ieee_is_nan' at (1) has no IMPLICIT type
Without the module the name is an unknown external function, and the message is the one every unknown function gets. The fix is one line at the top of the program unit, and the same line is needed in every procedure that uses the module unless it is host associated.
What this buys
Three things a numerical program cannot get any other way. It can distinguish a NaN from a number, which a comparison cannot do because every comparison with a NaN is false. It can ask whether a computation overflowed without testing the result against a threshold that depends on the type. And it can round a single operation in a direction it chooses, which is what an interval bound needs.
The price is that every one of these is an operation the compiler must not move across, so a program that sets flags in a hot loop is slower than one that does not. The usual arrangement is to use the IEEE facilities in the places where correctness is at stake and plain arithmetic in the inner loop, with a test that checks the result once.
Exercises
- Ask ieee_support_nan for a real(real64) variable and print the answer. Is it the same?
- Raise ieee_invalid by dividing a NaN by a NaN in variables rather than a constant expression. Which flag is set?
- Set the rounding mode to ieee_down and print one third again. Which digit changes?
- Print ieee_value(x, ieee_negative_zero) and compare it with zero using ==. Are they equal, and does the print show a sign?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
Which module holds IEEE_IS_NAN?
Answer
ieee_arithmetic
The value and class enquiry live in ieee_arithmetic.
-
What does
ieee_value(x, ieee_quiet_nan)use its first argument for?Answer
Its kind; the value itself is not used
The result has the kind of the first argument.
-
What does this program print?
program p use, intrinsic :: ieee_arithmetic implicit none real :: x x = ieee_value(x, ieee_quiet_nan) print *, ieee_is_nan(x), x == x end program pAnswer
T F
A NaN is not equal to itself; only ieee_is_nan finds it.
-
What does
ieee_support_nan(x)answer?Answer
Whether the kind of x supports NaNs on this machine
It is an enquiry about the hardware, per kind.
-
What happens when a division by zero raises a flag and no trap is enabled?
Answer
The operation completes with an infinity and the flag stays set
A flag is a record; -ffpe-trap is what stops the program.
-
Why does the program clear the flags twice?
Answer
The flags are sticky and stay set until cleared
Each part of the run must be measured on its own.
-
What does changing the rounding mode affect?
Answer
Every subsequent floating-point operation in the process
It is a property of the process, so save and restore it.
-
What does the run show about 1/3 in the two rounding modes?
Answer
The last digit differs by one unit in the last place
3.33333344E-01 against 3.33333343E-01.
-
What does gfortran report for
ieee_is_nan(x)without the module?Answer
Error: function has no IMPLICIT type
Without the use the name is an unknown external function.
-
What is the price of using the IEEE facilities in a hot loop?
Answer
The compiler may not move the operations across, so the loop is slower
Use them where correctness matters, not per iteration.
The programs on this page were built with GNU Fortran (Alpine 15.2.0) 15.2.0 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev