RPE API: rp_emulator.mod

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.