oeli (version 0.7.4)

Simulator: Simulator R6 Object

Description

Creates a simulation setup, where a function f is evaluated runs times, optionally at each combination of input values.

Provides some convenience (see below for more details):

• Simulation results can be restored from a backup if the R session crashes.

• More simulation runs can be conducted after the initial simulation, failed simulation cases can be re-run.

• Parallel computation and progress updates are supported.

Active bindings

results

[tibble, read-only]
The simulation results.

cases

[tibble, read-only]
The simulation cases.

Methods

Public methods

• Simulator$new()

• Simulator$print()

• Simulator$define()

• Simulator$go()

---

Method new()

Initialize a Simulator object, either a new one or from backup.

Usage

Simulator$new(
  use_backup = NULL,
  verbose = getOption("verbose", default = FALSE)
)

Arguments

use_backup

[NULL | character(1)]
Optionally a path to a backup folder previously used in $go().

verbose

[logical(1)]
Provide info? Does not include progress updates. For that, see details.

---

Method print()

Print method.

Usage

Simulator$print()

---

Method define()

Define function and arguments for a new Simulator object.

Usage

Simulator$define(f, ...)

Arguments

f

[function]
A function to evaluate.

...

Arguments for f. Each value must be

1. named after an argument of f, and

2. a list, where each element is a variant of that argument for f.

---

Method go()

Run simulations.

Usage

Simulator$go(
  runs = 0,
  backup = FALSE,
  path = paste0("backup_", format(Sys.time(), "%Y-%m-%d-%H-%M-%S"))
)

Arguments

runs

[integer(1)]
The number of (additional) simulation runs.

If runs = 0, only pending cases (if any) are solved.

backup

[logical(1)]
Create a backup under path?

path

[character(1)]
Only relevant, if backup = TRUE.

In this case, a path for a new folder, which does not yet exist and allows reading and writing.

Details

Backup

Simulation results can be saved to disk, allowing you to restore the results if the R session is interrupted or crashes before the simulation completes. To enable backup, set backup = TRUE in the $go() method, which will create a backup directory at the location specified by path. To restore, use Simulator$initialize(use_backup = path).

More runs and re-run

If additional simulation runs are needed, simply call the $go() method again. Any cases that were not successfully completed in previous runs will be attempted again.

Parallel computation

By default, simulations run sequentially. But since they are independent, they can be parallelized to decrease computation time. To enable parallel computation, use the {future} framework. For example, run

future::plan(future::multisession, workers = 4)

in advance for computation in 4 parallel R sessions.

Progress updates

Use the {progressr} framework to get progress updates. For example, run the following in advance:

progressr::handlers(global = TRUE)
progressr::handlers(
  progressr::handler_progress(format = ">> :percent, :eta to go :message")
)

See Also

Other simulation helpers: correlated_regressors(), ddirichlet_cpp(), dmvnorm_cpp(), dtnorm_cpp(), dwishart_cpp(), simulate_markov_chain()

Examples

# 1. Initialize a new simulation setup:
object <- Simulator$new(verbose = TRUE)

# 2. Define function `f` and arguments (if any):
f <- function(x, y = 1) {
  Sys.sleep(runif(1)) # to see progress updates
  x + y
}
x_args <- list(1, 2)
object$define(f = f, x = x_args)
print(object)

# 3. Define 'future' and 'progress' (optional):
if (FALSE) {
future::plan(future::sequential)
progressr::handlers(global = TRUE)}

# 4. Evaluate `f` `runs` times at each parameter combination (backup is optional):
path <- file.path(tempdir(), paste0("backup_", format(Sys.time(), "%Y-%m-%d-%H-%M-%S")))
object$go(runs = 2, backup = TRUE, path = path)

# 5. Access the results:
object$results

# 6. Check if cases are pending or if an error occurred:
object$cases

# 7. Restore simulation results from backup:
object_restored <- Simulator$new(use_backup = path)
print(object_restored)
if (FALSE) all.equal(object, object_restored)

# 8. Run more simulations and pending simulations (if any):
object_restored$go(runs = 2)