Uniform distribution scalar conversion functions

Functions
template<typename Ftype , typename Itype >
static Ftype	r123::u01 (Itype in)
	Return a uniform real value in (0, 1]. More...
template<typename Ftype , typename Itype >
static Ftype	r123::uneg11 (Itype in)
	Return a signed value in [-1,1]. More...
template<typename Ftype , typename Itype >
static Ftype	r123::u01fixedpt (Itype in)
	Return a value in (0,1) chosen from a set of equally spaced fixed-point values. More...
template<typename Ftype , typename CollType >
static std::array< Ftype, CollType::static_size >	r123::u01all (CollType in)
	Apply u01 to every item in an r123array, returning a std::array. More...
template<typename Ftype , typename CollType >
static std::array< Ftype, CollType::static_size >	r123::uneg11all (CollType in)
	Apply uneg11 to every item in an r123array, returning a std::array. More...
template<typename Ftype , typename CollType >
static std::array< Ftype, CollType::static_size >	r123::u01fixedptall (CollType in)
	Apply u01fixedpt to every item in an r123array, returning a std::array. More...

Detailed Description

This file provides some simple functions that can be used to convert integers of various widths to floats and doubles with various characteristics. It can be used to generate real-valued, uniformly distributed random variables from the random integers produced by the Random123 CBRNGs.

There are three templated functions:

• u01: output is as dense as possible in (0,1}, never 0.0. May return 1.0 if and only if the number of output mantissa bits is less than the width of the input.
• uneg11: output is as dense as possible in {-1,1}, never 0.0. May return 1.0 or -1.0 if and only if the number of output mantissa bits is less than the width of the input.
• u01fixedpt: output is "fixed point", equispaced, open at both ends, and is never 0.0, 0.5 nor 1.0.

The behavior of u01 and uneg11 depend on the pre-processor symbol: R123_UNIFORM_FLOAT_STORE. When #defined to a non-zero value, u01 and uneg11 declare a volatile intermediate result, with the intention of forcing architectures that have "extra bits" in their floating point registers to more closely conform to IEEE arithmetic. When compiled this way, u01 and uneg11 will be significantly slower, as they will incur a memory write and read on every call. Without it, they may fail the "known answer test" implemented in ut_uniform_IEEEkat.cpp even though they perform perfectly reasonable int to float conversions. We have used this option to get 32-bit x86 to produce the same results as 64-bit x86-64 code, but we do not recommend it for normal use.

Three additional functions are defined when C++11 or newer is in use:

• u01all
• uneg11all
• u01fixedptall

These functions apply the corresponding conversion to every element of their argument, which must be a staticly sized array, e.g., an r123array or a std::array of an integer type.

This file may not be as portable, and has not been tested as rigorously as other files in the library, e.g., the generators. Nevertheless, we hope it is useful and we encourage developers to copy it and modify it for their own use. We invite comments and improvements.

Function Documentation

template<typename Ftype , typename Itype >

static Ftype r123::u01 ( Itype  in )

inlinestatic

Return a uniform real value in (0, 1].

 Input is a W-bit integer (signed or unsigned).  It is cast to
 a W-bit unsigned integer, multiplied by Ftype(2^-W) and added to
 Ftype(2^(-W-1)).  A good compiler should optimize it down to an
 int-to-float conversion followed by a multiply and an add, which
 might be fused, depending on the architecture.

If the input is a uniformly distributed integer, and if Ftype
arithmetic follows IEEE754 round-to-nearest rules, then the
result is a uniformly distributed floating point number in (0, 1].

• The result is never exactly 0.0.
• The smallest value returned is 2^-(W-1).
• Let M be the number of mantissa bits in Ftype (typically 24 or 53).
  • If W>M then the largest value retured is 1.0.
  • If W<=M then the largest value returned is Ftype(1.0 - 2^(-W-1)).

template<typename Ftype , typename CollType >

static std::array<Ftype, CollType::static_size> r123::u01all ( CollType  in )

inlinestatic

Apply u01 to every item in an r123array, returning a std::array.

Only in C++11 and newer. The argument type may be any integer collection with a constexpr static_size member, e.g., an r123array or a std::array of an integer type.

template<typename Ftype , typename Itype >

static Ftype r123::u01fixedpt ( Itype  in )

inlinestatic

Return a value in (0,1) chosen from a set of equally spaced fixed-point values.

Let:

• W = width of Itype, e.g., 32 or 64, regardless of signedness.
• M = mantissa bits of Ftype, e.g., 24, 53 or 64
• B = min(M, W)

Then the 2^(B-1) possible output values are: 2^-B*{1, 3, 5, ..., 2^B - 1}

The smallest output is: 2^-B

The largest output is: 1 - 2^-B

The output is never exactly 0.0, nor 0.5, nor 1.0.

The 2^(B-1) possible outputs:

• are equally likely,
• are uniformly spaced by 2^-(B-1),
• are balanced around 0.5

template<typename Ftype , typename CollType >

static std::array<Ftype, CollType::static_size> r123::u01fixedptall ( CollType  in )

inlinestatic

Apply u01fixedpt to every item in an r123array, returning a std::array.

Only in C++11 and newer. The argument type may be any integer collection with a constexpr static_size member, e.g., an r123array or a std::array of an integer type.

template<typename Ftype , typename Itype >

static Ftype r123::uneg11 ( Itype  in )

inlinestatic

Return a signed value in [-1,1].

The argument is converted to a W-bit signed integer, multiplied by Ftype(2^-(W-1)) and then added to Ftype(2^-W). A good compiler should optimize it down to an int-to-float conversion followed by a multiply and an add, which might be fused, depending on the architecture.

If the input is a uniformly distributed integer, and if Ftype arithmetic follows IEEE754 round-to-nearest rules, then the output is a uniformly distributed floating point number in [-1, 1].

• The result is never exactly 0.0.
• The smallest absolute value returned is 2^-W
• Let M be the number of mantissa bits in Ftype.
  • If W>M then the largest value retured is 1.0 and the smallest is -1.0.
  • If W<=M then the largest value returned is the Ftype(1.0 - 2^-W) and the smallest value returned is -Ftype(1.0 - 2^-W).

template<typename Ftype , typename CollType >

static std::array<Ftype, CollType::static_size> r123::uneg11all ( CollType  in )

inlinestatic

Apply uneg11 to every item in an r123array, returning a std::array.

Only in C++11 and newer. The argument type may be any integer collection with a constexpr static_size member, e.g., an r123array or a std::array of an integer type.