Random number interface from R

We provide several functions for use from within R packages, all of which are in the namespace dust::random::r. These are further described in the package vignette

To access these functions you must have the cpp11 package available and include <dust/r/random.hpp>.

Seeding the generator

As a slightly more convienient interace for seeding generators

template<typename rng_state_type>
std::vector<typename rng_state_type::int_type> dust::random::r::as_rng_seed(cpp11::sexp r_seed)

Create a seed vector from an R object

Template Parameters:

rng_state_type – The random number state type to use; this is used to work out what type of integer is required and how many of them.

Parameters:

r_seed – An R object to use as a seed. Valid options are:

  • a scalar integer (or integer-like number) which we pass to dust::random::seed

  • a vector of raw values, which we take as a serialised vector of integers of appropriate width.

  • the R value NULL (i.e., R_NilValue, not a C++ nullptr), in which case we draw a random integer from R’s random number generator and pass that to dust::random::seed

Once you have a seed, there’s no direct interaction with the dust R API any further - you have a seed and can draw numbers as described elsewhere in this manual.

Persistent streams

To provide access to persistent streams (see also the reference documentation)

template<typename rng_state_type>
prng<rng_state_type> *dust::random::r::rng_pointer_get(cpp11::environment obj, int n_streams = 0)

Recieve and check the pointer to rng state. This checks that the object is valid, is of the correct state type, has sufficient streams and has not been invalidated by serialisation.

Template Parameters:

rng_state_type – The random number state type to use

Parameters:

  • obj – An dust_rng_pointer object, created in R with dust::dust_rng_pointer

  • n_streams – The number of required streams. Set this to 0 to disable the check. If you are going to use 100 streams pass 100 here, and a runtime error will be thrown if the object does not contain enough streams, which is nicer than a crash when prng::state fails.