registerDoRNG: Registering doRNG for Persistent Reproducible Parallel...

In doRNG: Generic Reproducible Parallel Backend for 'foreach' Loops

Registering doRNG for Persistent Reproducible Parallel Foreach Loops

Description

registerDoRNG registers the doRNG foreach backend. Subsequent ' registered foreach backend, but are internally performed as [ making them fully reproducible.

Usage

registerDoRNG(seed = NULL, once = TRUE)

Arguments

seed	a numerical seed to use (as a single or 6-length numerical value)
once	a logical to indicate if the RNG sequence should be seeded at the beginning of each loop or only at the first loop.

Details

Briefly, the RNG is set, before each iteration, with seeds for L'Ecuyer's CMRG that overall generate a reproducible sequence of statistically independent random streams.

Note that (re-)registering a foreach backend other than doRNG, after a call to registerDoRNG disables doRNG – which then needs to be registered.

Value

The value returned by [foreach::setDoPar]

See Also

[

Examples

if (requireNamespace("doParallel", quietly = TRUE)) {
  cl <- parallel::makeCluster(2)
  doParallel::registerDoParallel(cl)

  tryCatch({
    # One can make reproducible loops using the %dorng% operator
    r1 <- foreach(i=1:4, .options.RNG=1234) %dorng% { runif(1) }

    # or convert %dopar% loops using registerDoRNG
    registerDoRNG(1234)
    r2 <- foreach(i=1:4) %dopar% { runif(1) }
    identical(r1, r2)

    # Registering another foreach backend disables doRNG
    doParallel::registerDoParallel(cl)
    set.seed(1234)
    s1 <- foreach(i=1:4) %dopar% { runif(1) }
    set.seed(1234)
    s2 <- foreach(i=1:4) %dopar% { runif(1) }
    identical(s1, s2)
    

    # doRNG is re-enabled by re-registering it
    registerDoRNG()
    set.seed(1234)
    r3 <- foreach(i=1:4) %dopar% { runif(1) }
    identical(r2, r3)

    # argument `once=FALSE` reseeds doRNG's seed at the beginning of each loop
    registerDoRNG(1234, once=FALSE)
    a1 <- foreach(i=1:4) %dopar% { runif(1) }
    a2 <- foreach(i=1:4) %dopar% { runif(1) }
    identical(a1, a2)

    # Once doRNG is registered the seed can also be passed as an option to %dopar%
    b1 <- foreach(i=1:4, .options.RNG=456) %dopar% { runif(1) }
    b2 <- foreach(i=1:4, .options.RNG=456) %dopar% { runif(1) }
    identical(b1, b2) && !identical(b1, r1)
    
  }, finally = {
    foreach::registerDoSEQ()
    parallel::stopCluster(cl)
  })
} else {
  message("Package 'doParallel' is not installed; skipping this example.")
}

doRNG documentation built on Feb. 5, 2026, 5:08 p.m.