dust_rng: Dust Random Number Generator

In mrc-ide/dust: Iterate Multiple Realisations of Stochastic Models

Dust Random Number Generator

Description

Create an object that can be used to generate random numbers with the same RNG as dust uses internally. This is primarily meant for debugging and testing the underlying C++ rather than a source of random numbers from R.

Value

A dust_rng object, which can be used to drawn random numbers from dust's distributions.

Running multiple streams, perhaps in parallel

The underlying random number generators are designed to work in parallel, and with random access to parameters (see vignette("rng") for more details). However, this is usually done within the context of running a model where each particle sees its own stream of numbers. We provide some support for running random number generators in parallel, but any speed gains from parallelisation are likely to be somewhat eroded by the overhead of copying around a large number of random numbers.

All the random distribution functions support an argument n_threads which controls the number of threads used. This argument will silently have no effect if your installation does not support OpenMP (see dust_openmp_support).

Parallelisation will be performed at the level of the stream, where we draw n numbers from each stream for a total of n * n_streams random numbers using n_threads threads to do this. Setting n_threads to be higher than n_streams will therefore have no effect. If running on somebody else's system (e.g., an HPC, CRAN) you must respect the various environment variables that control the maximum allowable number of threads; consider using dust_openmp_threads to select a safe number.

With the exception of random_real, each random number distribution accepts parameters; the interpretations of these will depend on n, n_streams and their rank.

• If a scalar then we will use the same parameter value for every draw from every stream

• If a vector with length n then we will draw n random numbers per stream, and every stream will use the same parameter value for every stream for each draw (but a different, shared, parameter value for subsequent draws).

• If a matrix is provided with one row and n_streams columns then we use different parameters for each stream, but the same parameter for each draw.

• If a matrix is provided with n rows and n_streams columns then we use a parameter value ⁠[i, j]⁠ for the ith draw on the jth stream.

The rules are slightly different for the prob argument to multinomial as for that prob is a vector of values. As such we shift all dimensions by one:

• If a vector we use same prob every draw from every stream and there are length(prob) possible outcomes.

• If a matrix with n columns then vary over each draw (the ith draw using vector prob[, i] but shared across all streams. There are nrow(prob) possible outcomes.

• If a 3d array is provided with 1 column and n_streams "layers" (the third dimension) then we use then we use different parameters for each stream, but the same parameter for each draw.

• If a 3d array is provided with n columns and n_streams "layers" then we vary over both draws and streams so that with use vector prob[, i, j] for the ith draw on the jth stream.

The output will not differ based on the number of threads used, only on the number of streams.

Public fields

info

Information about the generator (read-only)

Methods

Public methods

• dust_rng$new()

• dust_rng$size()

• dust_rng$jump()

• dust_rng$long_jump()

• dust_rng$random_real()

• dust_rng$random_normal()

• dust_rng$uniform()

• dust_rng$normal()

• dust_rng$binomial()

• dust_rng$nbinomial()

• dust_rng$hypergeometric()

• dust_rng$gamma()

• dust_rng$poisson()

• dust_rng$exponential()

• dust_rng$cauchy()

• dust_rng$multinomial()

• dust_rng$state()

---

Method new()

Create a dust_rng object

Usage

dust_rng$new(
  seed = NULL,
  n_streams = 1L,
  real_type = "double",
  deterministic = FALSE
)

Arguments

seed

The seed, as an integer, a raw vector or NULL. If an integer we will create a suitable seed via the "splitmix64" algorithm, if a raw vector it must the correct length (a multiple of either 32 or 16 for float = FALSE or float = TRUE respectively). If NULL then we create a seed using R's random number generator.

n_streams

The number of streams to use (see Details)

real_type

The type of floating point number to use. Currently only float and double are supported (with double being the default). This will have no (or negligible) impact on speed, but exists to test the low-precision generators.

deterministic

Logical, indicating if we should use "deterministic" mode where distributions return their expectations and the state is never changed.

---

Method size()

Number of streams available

Usage

dust_rng$size()

---

Method jump()

The jump function updates the random number state for each stream by advancing it to a state equivalent to 2^128 numbers drawn from each stream.

Usage

dust_rng$jump()

---

Method long_jump()

Longer than ⁠$jump⁠, the ⁠$long_jump⁠ method is equivalent to 2^192 numbers drawn from each stream.

Usage

dust_rng$long_jump()

---

Method random_real()

Generate n numbers from a standard uniform distribution

Usage

dust_rng$random_real(n, n_threads = 1L)

Arguments

n

Number of samples to draw (per stream)

n_threads

Number of threads to use; see Details

---

Method random_normal()

Generate n numbers from a standard normal distribution

Usage

dust_rng$random_normal(n, n_threads = 1L, algorithm = "box_muller")

Arguments

n

Number of samples to draw (per stream)

n_threads

Number of threads to use; see Details

algorithm

Name of the algorithm to use; currently box_muller and ziggurat are supported, with the latter being considerably faster.

---

Method uniform()

Generate n numbers from a uniform distribution

Usage

dust_rng$uniform(n, min, max, n_threads = 1L)

Arguments

n

Number of samples to draw (per stream)

min

The minimum of the distribution (length 1 or n)

max

The maximum of the distribution (length 1 or n)

n_threads

Number of threads to use; see Details

---

Method normal()

Generate n numbers from a normal distribution

Usage

dust_rng$normal(n, mean, sd, n_threads = 1L, algorithm = "box_muller")

Arguments

n

Number of samples to draw (per stream)

mean

The mean of the distribution (length 1 or n)

sd

The standard deviation of the distribution (length 1 or n)

n_threads

Number of threads to use; see Details

algorithm

Name of the algorithm to use; currently box_muller and ziggurat are supported, with the latter being considerably faster.

---

Method binomial()

Generate n numbers from a binomial distribution

Usage

dust_rng$binomial(n, size, prob, n_threads = 1L)

Arguments

n

Number of samples to draw (per stream)

size

The number of trials (zero or more, length 1 or n)

prob

The probability of success on each trial (between 0 and 1, length 1 or n)

n_threads

Number of threads to use; see Details

---

Method nbinomial()

Generate n numbers from a negative binomial distribution

Usage

dust_rng$nbinomial(n, size, prob, n_threads = 1L)

Arguments

n

Number of samples to draw (per stream)

size

The target number of successful trials (zero or more, length 1 or n)

prob

The probability of success on each trial (between 0 and 1, length 1 or n)

n_threads

Number of threads to use; see Details

---

Method hypergeometric()

Generate n numbers from a hypergeometric distribution

Usage

dust_rng$hypergeometric(n, n1, n2, k, n_threads = 1L)

Arguments

n

Number of samples to draw (per stream)

n1

The number of white balls in the urn (called n in R's rhyper)

n2

The number of black balls in the urn (called m in R's rhyper)

k

The number of balls to draw

n_threads

Number of threads to use; see Details

---

Method gamma()

Generate n numbers from a gamma distribution

Usage

dust_rng$gamma(n, shape, scale, n_threads = 1L)

Arguments

n

Number of samples to draw (per stream)

shape

Shape

scale

Scale '

n_threads

Number of threads to use; see Details

---

Method poisson()

Generate n numbers from a Poisson distribution

Usage

dust_rng$poisson(n, lambda, n_threads = 1L)

Arguments

n

Number of samples to draw (per stream)

lambda

The mean (zero or more, length 1 or n). Only valid for lambda <= 10^7

n_threads

Number of threads to use; see Details

---

Method exponential()

Generate n numbers from a exponential distribution

Usage

dust_rng$exponential(n, rate, n_threads = 1L)

Arguments

n

Number of samples to draw (per stream)

rate

The rate of the exponential

n_threads

Number of threads to use; see Details

---

Method cauchy()

Generate n draws from a Cauchy distribution.

Usage

dust_rng$cauchy(n, location, scale, n_threads = 1L)

Arguments

n

Number of samples to draw (per stream)

location

The location of the peak of the distribution (also its median)

scale

A scale parameter, which specifies the distribution's "half-width at half-maximum"

n_threads

Number of threads to use; see Details

---

Method multinomial()

Generate n draws from a multinomial distribution. In contrast with most of the distributions here, each draw is a vector with the same length as prob.

Usage

dust_rng$multinomial(n, size, prob, n_threads = 1L)

Arguments

n

The number of samples to draw (per stream)

size

The number of trials (zero or more, length 1 or n)

prob

A vector of probabilities for the success of each trial. This does not need to sum to 1 (though all elements must be non-negative), in which case we interpret prob as weights and normalise so that they equal 1 before sampling.

n_threads

Number of threads to use; see Details

---

Method state()

Returns the state of the random number stream. This returns a raw vector of length 32 * n_streams. It is primarily intended for debugging as one cannot (yet) initialise a dust_rng object with this state.

Usage

dust_rng$state()

Examples

rng <- dust::dust_rng$new(42)

# Shorthand for Uniform(0, 1)
rng$random_real(5)

# Shorthand for Normal(0, 1)
rng$random_normal(5)

# Uniform random numbers between min and max
rng$uniform(5, -2, 6)

# Normally distributed random numbers with mean and sd
rng$normal(5, 4, 2)

# Binomially distributed random numbers with size and prob
rng$binomial(5, 10, 0.3)

# Negative binomially distributed random numbers with size and prob
rng$nbinomial(5, 10, 0.3)

# Hypergeometric distributed random numbers with parameters n1, n2 and k
rng$hypergeometric(5, 6, 10, 4)

# Gamma distributed random numbers with parameters a and b
rng$gamma(5, 0.5, 2)

# Poisson distributed random numbers with mean lambda
rng$poisson(5, 2)

# Exponentially distributed random numbers with rate
rng$exponential(5, 2)

# Multinomial distributed random numbers with size and vector of
# probabiltiies prob
rng$multinomial(5, 10, c(0.1, 0.3, 0.5, 0.1))

mrc-ide/dust documentation built on Oct. 14, 2024, 12:57 a.m.