Class providing the simulation functionality.

Source: R/simulator.R

Provides methods for initializing the synthetic population, parallel simulation, calibration and monitoring.

Methods

Public methods

Method new()

Create a new Simulator object.

Usage

Simulator$new(
  initializer = NULL,
  acc_events = list(),
  man_events = list(),
  seeds = 123,
  keep_init = FALSE,
  ...
)

Arguments

initializer

A function that generates the initial population.

acc_events

A list of AccumulationEvent objects.

man_events

A list of ManipulationEvent objects.

seeds

Seed values for random number generation.

keep_init

A logical value indicating whether the initial status should be stored. If TRUE the initial population can be retrieved with the method get_init.

...

Additional arguments to initializer,

Returns

A new Simulator object.

Method start_cluster()

Start a parallel computation cluster.

Usage

Simulator$start_cluster(
  cl,
  nc,
  export,
  packages,
  interface = c("doParallel", "doMPI")
)

Arguments

cl

A cluster object.

nc

Size of the cluster (available computing cores).

export

A character vector giving the names of objects from the global environment that should be exported to the workers.

packages

A character vector giving the names of packages that should be loaded on the workers.

interface

Interface to "foreach", must match the cluster type ("doParallel" and "doMPI" are currently supported).

Method stop_cluster()

Stop a parallel computation cluster.

Usage

Simulator$stop_cluster()

Method run()

Progress the simulation.

Usage

Simulator$run(N, show_progress = TRUE)

Arguments

N

An integer indicating the length of the simulation.

show_progress

A logical value. If TRUE shows a progress bar that tracks the completion of the simulation (for non-parallel computations only)

unit

A character string giving the time unit that t_sim corresponds to.

Method run_scenarios()

Run various scenarios with the same initial population using different interventions with replications.

Usage

Simulator$run_scenarios(
  interventions,
  replications,
  N,
  seeds_override = NULL,
  output,
  ...
)

Arguments

interventions

A list of interventions corresponding to the scenarios to run, see 'details'.

replications

An integer describing how many times each scenario should be replicated.

N

A single integer or an integer vector describing the simulation runtime for each scenario.

seeds_override

If NULL, a different seed is automatically used for each scenario. If provided, should be an integer matrix with replications rows and length(interventions) columns.

output

A function to apply to the population after each scenario.

...

Additional arguments passed to output.

Details

Each element of interventions should be a named list with the following elements: acc_events, acc_pars, man_events, man_pars and pars. The element acc_events should be a list of objects of class AccumulationEvent and acc_pars should be a list of the same length of numeric vectors giving the parameter values for these events. Similarly, man_events should be a list of object of class ManipulationEvent with man_pars being a list of the same length of numeric vectors giving the parameter values. Finally, pars should be a list of parameter values (see configure). For additional details, see intervene.

Method reconfigure()

Configure the parameters of Event objects.

Usage

Simulator$reconfigure(pars)

Arguments

pars

A named list of parameters, see 'details'.

Details

The parameter list pars should be structured as follows: Each element should have a name of an Event object and each element should be a named list where the names correspond to the names of the parameters of whose values are to be configured.

Method configure()

Configure events, run a simulation and compute a summary statistic for calibration. The original status is restored after completion.

Usage

Simulator$configure(N, pars, output, seeds = 123, ...)

Arguments

N

A numeric value indicating the length of the simulation

pars

A list of parameter values, see 'details'.

output

A function that computes a summary statistic from the simulation.

seeds

Seed values for random number generation.

...

Additional arguments passed to output.

Details

The parameter list pars should be structured as follows: Each element should have a name of an Event object and each element should be a named list where the names correspond to the names of the parameters of whose values are to be configured.

Returns

The output of output_function evaluated for the resulting population.

Method intervene()

Carry out an intervention that applies a set of accumulation events and manipulation events, and changes the values of specific parameters. By default, the events are applied first, then the parameters are changed.

Usage

Simulator$intervene(
  acc_events = list(),
  man_events = list(),
  pars = list(),
  events_first = TRUE
)

Arguments

acc_events

A list of accumulation events to apply.

man_events

A list of manipulation events to apply.

pars

A list of parameter values to set, see 'details'.

events_first

A logical value. If TRUE (the default) then the events are applied before any changes to the parameters. If FALSE the parameter values are changed first.

Details

The parameter list pars should be structured as follows: Each element should have a name of an Event object and each element should be a named list where the names correspond to the names of the parameters of whose values are to be configured.

Method get_status()

Get the status of the current population.

Usage

Simulator$get_status()

Returns

A data.table of the current status.

Method get_init()

Get the initial status of the population, if available.

Usage

Simulator$get_init()

Returns

A data.table of the initial status if it was recorded, otherwise NULL.

Method get_sample()

. Get a sample of the current population

Usage

Simulator$get_sample(sampler, ...)

Arguments

sampler

A function that constructs the output sample.

...

Additional arguments passed to sampler.

Returns

The sample generated by sampler.

Method get_history()

Get the simulation history as recorded by the monitor.

Usage

Simulator$get_history()

Returns

If the monitor is enabled, A list with an element for each evaluation of the monitor aggregators at their specified intervals These elements are lists as well, where the first element is the time index, and the remaining elements correspond to the values returned by the evaluated aggregators of the monitor. If no monitor is specified, returns NULL (invisibly).

Method initialize_monitor()

Initialize monitors to track specific status variables throughout the simulation at certain intervals.

Usage

Simulator$initialize_monitor(aggregators, intervals, combiners = NULL)

Arguments

aggregators

A list of functions to compute aggregate summary statistics from the simulated population.

intervals

A numeric vector giving the time interval after which each aggregator should be evaluated.

combiners

If parallel computation is used, this is a list of functions that combine the aggregator results from each parallel worker.

Method reset()

Reset the simulated population to the initial state (if initial status was kept). Note that any changes to event parameters are kept as is and have to be configured manually, if so desired.

Usage

Simulator$reset(force = FALSE, seeds = NULL)

Arguments

force

If TRUE, reset the simulator even if the initial status is not available.

seeds

An integer vector. If given, sets the pseudo-RNG seeds. This will then reset the seed numbers, and the simulation time.

Method clone()

The objects of this class are cloneable with this method.

Usage

Simulator$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.