Uniform distribution scalar conversion functions

Functions
template<typename Ftype , typename Itype >
R123_CUDA_DEVICE R123_STATIC_INLINE Ftype	r123::u01fixedpt (Itype in)
	Return a value in (0,1) chosen from a set of equally spaced fixed-point values. 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

u01fixedpt()

template<typename Ftype , typename Itype >

R123_CUDA_DEVICE R123_STATIC_INLINE Ftype r123::u01fixedpt

(

Itype

in

)

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

Definition at line 255 of file uniform.hpp.