Primitive random number generation functions¶

Uniform¶

The workhorse random number generating function is random_real:

template<typename T, typename U> __host__ __device__ T dust::random::random_real(U &state)¶

Generate a real number U(0, 1)

Template Parameters:

T – The real type to return, typically double or float; because this affects the return value only it must be provided.
U – The random number generator state type; this will be inferred based on the argument

Parameters:

state – The random number state, will be updated as a side effect

Returns:

A real-valued random number on (0, 1]

Integer¶

There is also a low-level function for generating integers of a given width:

template<typename T, typename U> __host__ __device__ T dust::random::random_int(U &state)¶

Generate a random integer of a given width

Template Parameters:

T – The integer type to generate, such as uint64_t. Both signed and unsigned integers can be provided here. Because this affects the return value only it must be provided.
U – The random number generator state type; this will be inferred based on the argument

Parameters:

state – The random number state, will be updated as a side effect

Returns:

An integer valued number, uniformly distributed anywhere within the range of the given integer type.

Note that this does not generate an arbitrary integer within some specified range; you are limited to C++ integer types.

Normal¶

The standard normal distribution also gets special treatment.

template<typename real_type, algorithm::normal algorithm = algorithm::normal::box_muller, typename rng_state_type> __nv_exec_check_disable__ __host__ __device__ real_type dust::random::random_normal(rng_state_type &rng_state)¶

Draw a standard normally distributed random number (with mean 0 and standard deviation 1)

Template Parameters:

T – The real type to return, typically double or float; because this affects the return value only it must be provided.
The – algorithm to use; the default is Box-Muller which is slowest on CPU but simple. Other alternatives are ziggurat (fast) or polar (medium).
U – The random number generator state type; this will be inferred based on the argument

Parameters:

state – The random number state, will be updated as a side effect

Returns:

A real-valued random number on (-inf, inf)

Example¶

#include <iostream>
#include <dust/random/random.hpp>

int main() {
  using rng_state_type = dust::random::generator<double>;
  auto state = dust::random::seed<rng_state_type>(42);

  std::cout << "uniform: " <<
    dust::random::random_real<double>(state) << std::endl;
  std::cout << "normal: " <<
    dust::random::random_normal<double>(state) << std::endl;
  std::cout << "unsigned integer: " <<
    dust::random::random_int<uint32_t>(state) << std::endl;
  std::cout << "signed integer: " <<
    dust::random::random_int<int16_t>(state) << std::endl;
}

uniform: 0.496954
normal: -0.578048
unsigned integer: 2064508910
signed integer: -13454