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=23]¶: 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).

Default value change

The default value will change from 23 to 52 in version 5.0

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.

RPE_IEEE_ROUNDING [LOGICAL,default=.FALSE.]¶: Logical value determining if full IEEE 754 rounding rules should be used. If .TRUE. then a “round to nearest, tie to even” rounding scheme will be used, which proceeds as normal rounding to the nearest representable number, except in the special case where a number is halfway between two representations where it will be rounded so that the least significant bit of the results is a zero. If .FALSE. then then rounding scheme rounds numbers halfway between two representations to the representation with larger absolute value.

Transitioning to new behaviour

This option is provided to ease the transition to a new IEEE 754 compliant rounding mode. In version 5.0 this option will be removed and the only rounding mode will be IEEE. You can use this option to test your code with the new rounding mode prior to moving to version 5.0 when it is released.

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.

RPE API: rp_emulator.mod¶

Derived types¶

User-callable procedures¶

Variables¶

Parameters¶

RPE API: `rp_emulator.mod`¶