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 anrpe_var
instance. If not specified then the resultingrpe_var
will use the default precision specified byRPE_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)
- x [IN] :: A real or integer value to store in the resulting
-
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 thesbits
attribute of therpe_var
instance, if this is not set then the value ofRPE_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 toapply_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 anrpe_var
instance to a particular precision level (doesn’t setrpe_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.
-
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.Note
It is recommended to set this option to
.TRUE.
. Currently the default is.FALSE.
for backwards compatibility reasons. In a future release the bahaviour of the.TRUE.
setting will become the default (and possibly only) option.
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 beRPE_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 byRPE_REAL_KIND
is changed.