Local/With dqrng State

local_dqrng_state() installs a per-task (seed, primer) starting point as the running dqrng RNG state via dqrng::dqset.seed(), restoring the previous state when .local_envir exits. with_dqrng_state() evaluates code with that state installed, then restores the previous state. The primer argument is the per-task primer (the value handed to dqrng's stream argument, per TARGETS-DESIGN.md §2 and the GLOSSARY); the _state suffix marks that the wrapper installs that primer as the running RNG state.

Usage

local_dqrng_state(seed, primer, .local_envir = parent.frame())

with_dqrng_state(seed, primer, code)

Arguments

seed

[whole number]
A scalar seed passed to dqrng::dqset.seed().

primer

[integer(2)]
A length-2 integer primer passed as the stream argument of dqrng::dqset.seed(). NA_integer_ is permitted (the reserved INT_MIN encoding of TARGETS-DESIGN.md §2).

.local_envir

[environment]
The environment to use for scoping.

code

[any]
Code to execute in the temporary environment

Value

local_dqrng_state() invisibly returns primer; with_dqrng_state() returns the value of code.

Details

These are the dqrng-path analogues of local_lecuyer_cmrg_state() / with_lecuyer_cmrg_state(). Like those helpers they snapshot the RNG state on entry (via dqrng::dqrng_get_state()) and withr::defer() a restore (via dqrng::dqrng_set_state()), so a call leaves the surrounding RNG stream undisturbed, including on error.

Both require an active dqrng backend: they abort unless a local_dqrng_backend() scope is open. This fails fast rather than silently seeding base R's Mersenne-Twister.

See also

withr::local_seed(), local_dqrng_backend(), local_lecuyer_cmrg_state().

Examples

local_dqrng_backend()
local_dqrng_state(42, c(1L, 2L))
#> Error in local_dqrng_state(42, c(1L, 2L)): The dqrng backend is not active. Open a `local_dqrng_backend()` scope first.
runif(3)
#> [1] 0.2926078 0.8011529 0.1608404

with_dqrng_state(42, c(1L, 2L), runif(3))
#> Error in local_dqrng_state(seed, primer): The dqrng backend is not active. Open a `local_dqrng_backend()` scope first.