Basic use of the reduced-precision type¶

The rpe_var type is a simple container for a double precision floating point value. Using an rpe_var instance is as simple as declaring it and using it just as you would a real number:

TYPE(rpe_var) :: myvar

myvar = 12
myvar = myvar * 1.287   ! reduced-precision result is stored in `myvar`

Controlling the precision¶

The precision used by reduced precision types can be controlled at two different levels. Each reduced precision variable has an sbits attribute which controls the number of explicit bits in its significand. This can be set independently for different variables, and comes into effect after it is explicitly set.

TYPE(rpe_var) :: myvar1
TYPE(rpe_var) :: myvar2

! Use 16 explicit bits in the significand of myvar1, but only 12 in the
! significand of myvar2.
myvar1%sbits = 16
myvar2%sbits = 12

For variables whose sbits attribute has not been explicitly set, there is a default global precision level, set by RPE_DEFAULT_SBITS. This will stand-in for the number of explicit significand bits in any variable where sbits has not been set. Setting RPE_DEFAULT_SBITS once to define the global default precision, and setting the precision of variables that require other precision manually using the sbits attribute is generally a good strategy. However, if you change RPE_DEFAULT_SBITS during execution, the document Changing RPE_DEFAULT_SBITS during execution lists some details you should be aware of.

The emulator can also be turned off completely by setting the module variable RPE_ACTIVE to .FALSE..

Build requirements¶

Building the emulator requires:

• GCC (gfortran) >= 4.8 or Intel Fortran (ifort) >= 15.0.2
• GNU Make

The emulator has been tested with GCC 4.8.4 and GCC 4.9.2 and Intel Fortran 15.0.2 and is known to work correctly with these compilers. No testing of other compilers has been done by us, it might work with other compilers, it might not.

Building¶

The library is built using GNU Make and a Fortran compiler. The default action when invoking make is to build the static library lib/librpe.a and the Fortran module modules/rp_emulator.mod.

The code is tested with and set-up for building with GNU gfortran or Intel Fortran (ifort) compilers. Which compiler to use is determined by the value of the F90 environment variable. If this variable is not set the Makefile will use gfortran. The default build is a simple invocation of make:

make

It is also possible to build a shared library lib/librpe.so using the shared target of the Makefile:

make shared

You can optionally specify a compiler on the command line:

F90=ifort make

If you want to use a compiler other than gfortran or ifort you will need to specify both the appropriate F90 variable and the correct FFLAGS for your compiler. Compiler flags are used in the build to ensure the module rp_emulator.mod is placed in the modules/ directory in the source tree.

make source

Integration¶

Assuming you did a full build, integration with your project is fairly straightforward, requiring two files to be present, one at compile time and one at link time.

You must make sure that the module file rp_emulator.mod is available to the compiler when compiling any source file that uses the module. You can do this by specifying an include flag at compile time. Alternatively you could place the module file in the same directory as your source files, but normally you would store it separately and use an include flag.

At link time the librpe.a (or librpe.so) library will also need to be available to the linker. You can use a combination of linker path and library options to make sure this is the case. Alternatively, you can directly specify the full path to librpe.a as an object to include in linking.

For example, let’s say we have placed the module file at $HOME/rpe/modules/rp_emulator.mod and the library at $HOME/rpe/lib/librpe.a, our compilation command must tell the compiler to look in the right place for the module file:

gfortran -c -I$HOME/rpe/modules myprogram.f90

and our linker command must tell the linker which libraries to link and where to look for them:

gfortran -o myprogram.exe myprogram.o -L$HOME/rpe/lib -lrpe

The arguments are the same whether linking the static or shared library.

Using the emulator in your code¶

In any subroutine, module or program where you want to use the emulator, you need to import the emulator’s module. For example, to include the emulator in a particular subroutine:

SUBROUTINE some_routine (...)
    USE rp_emulator
    ...
END SUBROUTINE some_routine

You can then use any of the emulator features within the subroutine.

Initialization on assignment¶

The emulator overloads the assignment operator allowing you to assign integers, real numbers, and other rpe_var instances to any rpe_var instance:

PROGRAM assign_other_types

    USE rp_emulator
    IMPLICIT NONE

    TYPE(rpe_var) :: x

    ! Assign an integer value to x.
    x = 4

    ! Assign a single-precision real value to x.
    x = 4.0

    ! Assign a double-precision real value to x.
    x = 4.0d0

END PROGRAM

However, you cannot perform the same assignments at the time the rpe_var is defined. This is not allowed:

PROGRAM assign_other_types

    USE rp_emulator
    IMPLICIT NONE

    TYPE(rpe_var) :: x = 4

END PROGRAM

Compiling this code with gfortran will give the following compilation error:

    TYPE(rpe_var) :: x = 4
                        1
Error: Can't convert INTEGER(4) to TYPE(rpe_var) at (1)

This is because this form of assignment does not actually call the overloaded assignment operator defined for rpe_var instances, instead it calls the default constructor for the derived type, which only allows the right-hand-side of the assignment to be another rpe_var instance.

Changing RPE_DEFAULT_SBITS during execution¶

You are able to change the value of the module variable RPE_DEFAULT_SBITS to anything you like at any time you like. However, you need to be aware of the potential inconsistencies you might introduce by doing so.

PROGRAM change_default_bits1

    USE rp_emulator
    IMPLICIT NONE

    TYPE(rpe_var) :: pi

    RPE_DEFAULT_SBITS = 16

    ! This value of Pi will be stored with only 16 bits in the mantissa.
    pi = 3.1415926535897932d0
    WRITE (*, '("RPE_DEFAULT_SBITS=16, pi=", F20.18)') pi%get_value()

    ! Doing this means that whilst any operations on Pi following will assume
    ! 4 bits of significand precision, the value currently stored still has 16
    ! bits of significand precision
    RPE_DEFAULT_SBITS = 4
    WRITE (*, '("RPE_DEFAULT_SBITS=4,  pi=", F20.18)') pi%get_value()

END PROGRAM

Output:

RPE_DEFAULT_SBITS=16, pi=3.141601562500000000
RPE_DEFAULT_SBITS=4,  pi=3.141601562500000000

To avoid any issues you may want to insert manual calls to apply_truncation() to ensure every variable used within the scope of the changed default is represented at the required precision.

In other circumstances this may not be a problem at all, for example around encapsulated subroutine calls. In the example below the procedure some_routine() takes no reduced precision types as arguments, but does work with reduced precision types internally, and in this case setting the default number of bits around the subroutine call is a useful way to set the default precision of all reduced precision variables within the subroutine (and within any routines it calls):

RPE_DEFAULT_SBITS = 4
CALL some_routine (a, b, c)
RPE_DEFAULT_SBITS = 16

Whatever you choose to do, you need to make sure you have considered this potential issue before you change the value of RPE_DEFAULT_SBITS at run-time.

Parallel and thread safety¶

The default number of bits for any reduced precision type is controlled by a module variable RPE_DEFAULT_SBITS. This is a mutable variable that can be changed dynamically during program execution if desired. If the application using the emulator is parallelised then the behaviour of the default bits setting needs to be considered.

For MPI parallelism, each MPI task will get its own separate instance of the RPE_DEFAULT_SBITS variable, and modifying it within a task will only affect the default precision within that task (unless programmed otherwise using message passing).

For threaded parallelism (e.g. OpenMP) the behaviour is less clear. Depending on the threading type used, the variable may be shared by threads, or each may have its own copy.

For parallel applications, care must be taken when changing the value of RPE_DEFAULT_SBITS at run time to make sure the implementation is safe.

Non-equivalence of single and compound operations¶

One would normally expect the following operations to yield identical results:

a * a * a

and

a ** 3

However, due to the way the emulator works by doing individual computations in full precision and reducing the precision of the result, these two would not necessarily yield the same result if a were a reduced precision variable. In the first example the compound multiplication would be done in two parts, the first part computes a * a and the precision of the temporary result is reduced, then the second part multiplies this reduced precision result by a and once again reduces the precision of the final result. However, in the second example a single operation is used to express the computation, this computation will be performed in full precision and the result will have its precision reduced. Whereas the first example uses reduced precision to store intermediate results, the second does not.

This is true for any operator that can be expressed as multiple invocations of other operators.

Requirements¶

In addition to the user requirements, there are extra dependencies for developers:

Get the source code¶

Follow the instructions in Working with rpe source code to set up your source code repository and version control tools.

The core library¶

The core of the emulator is written in Fortran, and is found in the file src/rp_emulator.F90. The emulator library provides two core derived types used to represent reduced precision floating point numbers. These types have accompanying overloaded operator definitions, allowing them to be used in the same way as the builtin real number type. For maximum ease of use, many of the builtin Fortran intrinsic functions are also overloaded to accept these reduced precision types.

The src/rp_emulator.F90 file contains the module definition, the definition of the derived types, and the core functions and subroutines that control the emulator’s functionality. However, it does not contain most of the overloaded operator and intrinsic function definitions. Instead there are a handful of C preprocessor directives in the file that pull in these definitions from external files in src/include/. The way in which these external file are generated is described below.

The code generator¶

A lot of the code required to complete the full emulator is repetetive boiler-plate code; code which is largely the same for a whole group of functions/subroutines. Because of the repetetive nature of the required Fortran implementations for all overloaded operators and intrinsic functions, it is more efficient to provide only a template of what the code should look like, and let the computer actually write the code. The code generator for the emulator is written in Python and is included in the generator/ subdirectory.

Using a generator is a big time saver, if you need to change 1 line of every intrinsic function implementation, you only need to modify that line in a few templates and let the code generator write all the actual Fortran code for you. Not only does this approach save time, it also has positive implications for code correctness. For example if 50 function implementations are produced by the generator, it is not possible for one of them to contain an error that the others don’t, as would often be the case when hand-writing sucha a large number of essentially similar routines. You write the implementation carefully once, and the boring stuff is done automatically.

Due to its relative complexity, the Code Generator is documented separately.

Extra definitions¶

As well as code that is produced by the code generator, there are two more files in src/include/ that can be edited manually: interface_extras.i and implementation_extras.f90. You can add arbitrary functions/subroutines to the implementation_extras.i file, with any required interface definitions in interface_extras.i, and they will be included in the main library source file automatically. Just make sure you make your interface public, as the default is private.

Tests¶

The emulator is provided with a suite of basic tests, in the tests/ subdirectory. It is expected that any change you make will not cause any of the existing tests to fail, and ideally new features should be accompanied with new tests to make sure they work, and continue to work in the future.

The tests are split into two categories, units tests and integration tests. Unit tests should be relatively self-contained tests of the functionality of a particular small element of the code (code unit). Ideally these tests are for a single component in isolation from the rest of the system, although the nature of the library means this sometimes is not possible. Integration tests are more like realistic tests of the software in use, and should tests multiple aspects of the library together (in integration).

Derived types¶

type rpe_var¶

A type representing a reduced-precision floating-point number. This type stores the number it represents internally.

Type fields:	% sbits [INTEGER] :: Number of bits in the significand of the floating-point number % val [REAL,KIND=RPE_REAL_KIND] :: The real value stored within the instance.

User-callable procedures¶

function rpe_literal(x, n)¶

Construct an rpe_var instance from a value. Optionally a number of significand bits used to store the value may be given. The value will be truncated before storage. A typical usage of this constructor is to support reduced precision literal values without having to declare extra variables:

type(rpe_var) :: a, b, c, d, e

RPE_DEFAULT_SBITS = 10

! variables a, b and c have a 10-bit significands:
a = 5.00
b = 7.23
c = 21.12

! The literals 7.29e-5, 3.14 and 18.17 have full precision
! (a 23-bit significand):
d = 7.29e-5 * a + 3.14 * b + 18.17 * c  ! d = 406.5

! The literals are replaced by rpe_var instances with 10-bit significands:
e = rpe_literal(7.29e-5) * a + rpe_literal(3.14) * b + rpe_literal(18.17) * c  ! e = 406.75

Parameters:	x [IN] :: A real or integer value to store in the resulting rpe_var instance. n [integer,IN,OPTIONAL] :: An optional number of significand bits used to represent the number, equivalent of setting the sbits attribute of an rpe_var instance. If not specified then the resulting rpe_var will use the default precision specified by RPE_DEFAULT_SBITS.

Note

If you use this to create an rpe_var instance and then assign the result to another instance, only the value will be copied:

! An rpe_var instance with a 13 bit significand:
type(rpe_var) :: a
a%sbits = 13

! Construct an rpe_type instance with a 15-bit significand and assign to a,
! the value will be truncated to 13 bits and the variable a will continue
! to store only 13 significand bits.
a = rpe_literal(1.23456789, 15)

subroutine apply_truncation(rpe) [elemental]¶

Apply the required truncation to the value stored within an rpe_var instance. Operates on the input in-place, modifying its value. The truncation is determined by the sbits attribute of the rpe_var instance, if this is not set then the value of RPE_DEFAULT_SBITS.

Parameters:	rpe [rpe_var,INOUT] :: The rpe_var instance to alter the precision of.

function significand_bits(x) [elemental]¶

Determine the number of significand bits being used by the input types. For inputs that are rpe_var instances this function returns the number of significand bits in use by the reduced-precision number. For real numbers it will return either 23 for single-precision inputs or 52 for double-precision inputs. For all other input types the result will be zero.

Parameters:	x [IN] :: Any Fortran type.

Variables¶

RPE_ACTIVE [LOGICAL,default=.TRUE.]¶

Logical value determining whether emulation is on or off. If set to .FALSE. then calls to apply_truncation() will have no effect and all operations will be carried out at full precision.

RPE_DEFAULT_SBITS [INTEGER,default=52]¶

The default number of bits used in the significand of an rpe_var instance when not explicitly specified. This takes effect internally when determining precision levels, but does not bind an rpe_var instance to a particular precision level (doesn’t set rpe_var%sbits).

RPE_IEEE_HALF [LOGICAL,default=.FALSE.]¶

Logical value determining if IEEE half-precision emulation is turned on. If set to .TRUE. and a 10-bit significand is being emulated the emulator will additionally impose range constraints when applying truncation:

• Values that overflow IEEE half-precision will lead to real overflows with a corresponding floating-point overflow exception.
• Values out of the lower range of IEEE half-precision will be denormalised.

This option only affects the emulation when emulating a 10-bit significand.

Parameters¶

RPE_DOUBLE_KIND [INTEGER]¶

The kind number for double precision real types.

RPE_SINGLE_KIND [INTEGER]¶

The kind number for single precision real types.

RPE_REAL_KIND [INTEGER]¶

The kind number of the real-values held by reduced precision types. This is a reference to RPE_DOUBLE_KIND, but could be changed (in source) to be RPE_SINGLE_KIND.

RPE_ALTERNATE_KIND [INTEGER]¶

The kind number of an alternate type of real-value. This is a reference to RPE_SINGLE_KIND, but can be changed (in source) if the value referenced by RPE_REAL_KIND is changed.

v5.0.x¶

• Change summary
  • The default value for RPE_DEFAULT_SBITS has changed to 52, previously it was 23. This change means that by default all rpe_var types behave like double precision real types.
  • The upper limit for the value of an IEEE half-precision number has been corrected to 65504. This value was previously too small (32768) resulting in an over-conservative representation of IEEE half-precision values. This change only affects code running with the RPE_IEEE_HALF option turned on.
  • The huge intrinsic has been reimplemented for rpe_var types. It now returns the largest value with an 11-bit exponent and the number of significand bits in its input. It also behaves correctly when using a 10-bit significand and RPE_IEEE_HALF = .true., returning the largest number with a 5-bit exponent and 10-bit significand (65504).
• Incompatibilities
  • The rounding mode has changed to be compliant with IEEE 754. The new mode will likely give different (but more realistic) results. The new behaviour is the same as that obtained in v4.1 with the option RPE_IEEE_ROUNDING = .true..
  • The option RPE_IEEE_ROUNDING has been removed, the new rounding behaviour is equivalent to RPE_IEEE_ROUNDING = .true.. There is no option to change to the behaviour of RPE_IEEE_ROUNDING = .false..

v4.1.x¶

Add deprecation notices to API documentation. There are no changes to the source code and no need to upgrade from v4.1.0.

Adds an IEEE 754 compliant rounding scheme and new functionality for explicit handling of literal floating-point values.

• Features
  • A new (currently opt-in) IEEE 754 compliant rounding mode, activated by setting the module variable RPE_IEEE_ROUNDING = .true.. This option is provided to help manage a transition to IEEE 754 compliant rounding in a future release. Eventually this option will be removed and IEEE 754 compliant rounding will become the default and only rounding mode.
  • A new helper function rpe_literal is provided to help write correct reduced-precision code that contains numeric literals.
• Deprecations
  • The current rounding mode (round to nearest) is deprecated. Future releases will use the IEEE 754 compliant rounding mode. Users should set RPE_IEEE_ROUNDING = .true. to get the new rounding behaviour. We recommend the IEEE 754 rounding mode to ensure best results.

v4.0.x¶

This release is a major overhaul of the code with the aim of making it more portable and reliable.

• Features
  • Compatible with Intel Fortran compilers. The code may work with other compilers too, but only Intel and GNU are tested currently.
• Incompatibilities: This release is not compatible with version 3 or below.
  • Removed the rpe_shadow derived type.
  • Removed abstract base class rpe_type, the only user type is now rpe_var.
  • Removed getter and setter methods, the value of an rpe_var instance is now accessed directly using the %val attribute.

v3.1.x¶

• License code under the Apache 2.0 license.

• Support for IEEE half-precision emulation via the RPE_IEEE_HALF module variable.

v3.0.x¶

• License code under the Apache 2.0 license.

• Features
  • Support for different precision levels in different variables:
    • You can set the %sbits attribute of any rpe_type instance to define the number of significand bits used by that variable.
  • A set of unit tests is included to help us ensure the emulator core is robust.
  • HTML documentation is included with the source (requires Sphinx to build).
• Incompatibilities
  • This version is incompatible with the v2.0.x series.
  • The public API is now smaller, including only the required parts of the library.
  • Module variables renamed: RPE_BITS -> RPE_DEFAULT_SBITS
  • Reduction of precision subroutine renamed: reduce_precision -> apply_truncation
  • Internal differences to support mixed precision may cause different results to previous versions.

v2.0.x¶

• License code under the Apache 2.0 license.

• Features
  • Reduce precision on assignment:
    • The precision of the value held within an rpe_type instance is reduced whenever a value is assigned, meaning an rpe_var instance cannot ever store a full precision value, and an rpe_shadow type will always store a reduced precision value when it has been assigned to directly (but one can of course assign a full precision value to the variable it is shadowing and have that value retained).
    • Explicit calls to reduce_precision are no longer required in any overloaded operators or intrinsic routines, as the reduction of precision will be performed implicitly on assignment of the result.
• Incompatibilities
  • The change from explicit reduction of precision within overloaded operators and intrinsics will likely cause the emulator to return different results than the v1.0.x series.

v1.0.x¶

• License code under the Apache 2.0 license.

• Features
  • Initial version used operationally for experiments.