Kind parameters

Fortran does not have a double keyword and it does not have a real*8 declaration that the standard knows about. It has kinds: a type is what a value is, a kind is how much of it there is. This lesson shows how to ask the compiler for a kind, how to attach one to a literal, and how to find out what a kind actually gives you.

What a kind is

A kind is an integer value that selects one of the representations a type has. On this compiler the default real has kind 4 and the double precision real has kind 8, but the numbers are not sizes in bytes that the language promises: they are labels the compiler chose, and another compiler may use different ones. The portable way to a kind is therefore not to write 8 but to ask for it.

Two functions do the asking. selected_real_kind(p, r) takes a number of decimal digits and a decimal exponent range, and returns the kind that provides both. selected_int_kind(r) takes a decimal exponent range and returns an integer kind. Both return -1 when no kind on the machine qualifies, which is a test a portable program can make.

The file kinds.f90:

program kinds use iso_fortran_env, only: int32, int64, real32, real64 implicit none integer, parameter :: sp = selected_real_kind(6, 37) integer, parameter :: dp = selected_real_kind(15, 307) integer, parameter :: ik = selected_int_kind(9) integer, parameter :: lk = selected_int_kind(18) print *, "selected_real_kind(6, 37) :", sp print *, "selected_real_kind(15, 307):", dp print *, "selected_int_kind(9) :", ik print *, "selected_int_kind(18) :", lk print *, "real64 named kind :", real64, " same:", dp == real64 print *, "int64 named kind :", int64, " same:", lk == int64 print *, "real32 named kind :", real32, " same:", sp == real32 print *, "int32 named kind :", int32, " same:", ik == int32 end program kinds

gfortran -Wall -Wextra -std=f2018 kinds.f90 -o kinds
./kinds

selected_real_kind(6, 37) : 4
selected_real_kind(15, 307): 8
selected_int_kind(9) : 4
selected_int_kind(18) : 8
real64 named kind : 8 same: T
int64 named kind : 8 same: T
real32 named kind : 4 same: T
int32 named kind : 4 same: T

The last four lines are the point of the exercise: the two requests give the same kinds as the named constants from iso_fortran_env, and the comparisons say so with T. Both routes are correct, and the next lesson is about when to prefer the named one.

selected_real_kind and selected_int_kind

The arguments are requirements, not a measurement. selected_real_kind(15, 307) means "at least fifteen decimal digits and at least a range of ten to the 307", which is the classic double precision; selected_real_kind(6, 37) is the classic single, which is also the default. Ask for 33 digits and 4931 and gfortran 15 answers with 16, the quadruple precision kind; the arithmetic then runs in software on most x86 machines and is considerably slower than the 8-byte kind.

selected_int_kind(9) asks for nine decimal digits, which is the 4-byte integer; selected_int_kind(18) asks for eighteen and gets the 8-byte one. A program that counts bytes of a large file should ask for the second, because the first overflows at two gigabytes, and the overflow is silent.

The two functions are pure and their arguments are constants, so the results can be parameters. That is the standard idiom: one name per precision at the top of a module, and every declaration in the project written in terms of those names.

The literal suffix

A literal has the default kind unless it says otherwise, and it says so with an underscore: 1.0_dp, 0_int64. The suffix may be a literal kind value (1.0_8) or, better, a named parameter (1.0_dp), because the number 8 is the compiler's choice and the name is the program's.

The suffix matters in expressions. 1.0 / 3.0 is computed in single precision and then converted if it is assigned to a double, which loses the digits the double was bought for. 1.0_dp / 3.0_dp computes in double from the first bit. The conversion is silent and the result is close enough to look right in a print statement.

One constant per precision

A module that holds the two names is the smallest reusable piece a numerical project has, and every later lesson in this course can use it:

The file precision_mod.f90:

module precision_mod use iso_fortran_env, only: real64 implicit none private public :: dp integer, parameter :: dp = real64 end module precision_mod program use_precision use precision_mod, only: dp implicit none real(dp) :: x x = 1.0_dp / 3.0_dp print *, "one third:", x end program use_precision

gfortran -Wall -Wextra -std=f2018 precision_mod.f90 -o use_precision
./use_precision

one third: 0.33333333333333331

Sixteen digits after the conversion are the sign that the division happened in double: a single precision result printed at double precision ends in zeros or in a value that does not match one third beyond the seventh digit.

digits, precision, range and epsilon

Four inquiry intrinsics answer what a kind actually gives. digits(x) is the number of binary digits of the mantissa; precision(x) is the number of decimal digits; range(x) is the decimal exponent range; and epsilon(x) is the difference between 1 and the next representable value.

The file limits.f90:

program limits use iso_fortran_env, only: int64, real64 implicit none print *, "digits(1.0) :", digits(1.0) print *, "digits(1.0_real64) :", digits(1.0_real64) print *, "precision(1.0) :", precision(1.0) print *, "precision(1.0_real64):", precision(1.0_real64) print *, "range(0) :", range(0) print *, "range(0_int64) :", range(0_int64) print *, "epsilon(1.0) :", epsilon(1.0) print *, "huge(1.0_real64) :", huge(1.0_real64) end program limits

gfortran -Wall -Wextra -std=f2018 limits.f90 -o limits
./limits

digits(1.0) : 24
digits(1.0_real64) : 53
precision(1.0) : 6
precision(1.0_real64): 15
range(0) : 9
range(0_int64) : 18
epsilon(1.0) : 1.19209290E-07
huge(1.0_real64) : 1.7976931348623157E+308

24 and 53 are the bits of the mantissa, 6 and 15 are the decimal digits a reader can trust. The epsilon of a single is about 1.2e-7, which is why a single precision program that compares two computed values for equality usually compares them within a tolerance instead, and why a double precision one uses a smaller tolerance and still does not compare for equality.

Exercises

  1. Ask for selected_real_kind(33, 4931). Which kind do you get, and what is the cost?
  2. Print selected_real_kind(50, 5000). What does the function return when no kind qualifies?
  3. Compute 1.0 / 3.0 and 1.0_dp / 3.0_dp and print both with sixteen digits.
  4. Print epsilon(1.0_dp) and compare it with the single precision value above.

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What is a kind in Fortran?

    Answer

    An integer label that selects a representation of a type

    The label is the compiler's choice, which is why the selection functions exist.

  2. What does selected_real_kind(15, 307) ask for?

    Answer

    At least 15 decimal digits and an exponent range of at least 307

    The arguments are a minimum digit count and a minimum decimal exponent range.

  3. What does selected_real_kind return when no kind qualifies?

    Answer

    -1

    A negative result is the standard signal that the request cannot be met.

  4. What does the suffix in 1.0_dp do?

    Answer

    It gives the literal the kind named dp

    The underscore suffix attaches a kind to a literal.

  5. What does digits(1.0) return on this compiler?

    Answer

    24, the binary digits of the mantissa

    digits counts bits; precision counts decimal digits and gives 6 here.

  6. What does precision(1.0_real64) return?

    Answer

    15

    Double precision guarantees about fifteen decimal digits.

  7. What does this program print? program p use iso_fortran_env, only: real64 implicit none print *, kind(1.0_real64) end program p

    Answer

    8

    The literal carries the kind real64, which is 8 on this compiler.

  8. Why is real*8 not the recommended declaration?

    Answer

    It is a vendor extension; a kind parameter is standard Fortran

    The starred form is not in the standard, so it does not port.

  9. What does epsilon(1.0) measure?

    Answer

    The difference between 1 and the next representable value

    It is the machine epsilon of that kind, about 1.2e-7 for a single.

  10. Why does a program count bytes in an 8-byte integer?

    Answer

    A 4-byte counter overflows at about two gigabytes, silently

    Integer overflow wraps without a message, so the width must fit the count.

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