Schedule a simulation event

Adds a new event to the simulation's event queue, updating the simulation object.

scheduleEvent(
  sim,
  eventTime,
  moduleName,
  eventType,
  eventPriority = .pkgEnv$.normalVal,
  .skipChecks = FALSE
)

Arguments

sim

A simList simulation object.

eventTime

A numeric specifying the time of the next event.

moduleName

A character string specifying the module from which to call the event. If missing, it will use currentModule(sim)

eventType

A character string specifying the type of event from within the module.

eventPriority

A numeric specifying the priority of the event. Lower number means higher priority. As a best practice, it is recommended that decimal values are conceptual grouped by their integer values (e.g., 4.0, 4.25, 4.5 are conceptually similar). See priority().

.skipChecks

Logical. If TRUE, then internal checks that arguments match expected types are skipped. Should only be used if speed is critical.

Value

Returns the modified simList object.

Details

Here, we implement a simulation in a more modular fashion so it's easier to add submodules to the simulation. We use S4 classes and methods, and use data.table instead of data.frame to implement the event queue (because it is much faster).

References

Matloff, N. (2011). The Art of R Programming (ch. 7.8.3). San Francisco, CA: No Starch Press, Inc.. Retrieved from https://nostarch.com/artofr.htm

See also

priority(), scheduleConditionalEvent()

Author

Alex Chubaty

Examples

 sim <- simInit()
#> Setting:
#>   options(
#>     reproducible.cachePath = '/tmp/RtmpmTr4Wk/myProject/cache'
#>     spades.inputPath = '/tmp/RtmpmTr4Wk/myProject/inputs'
#>     spades.outputPath = '/tmp/RtmpmTr4Wk/myProject/outputs'
#>     spades.modulePath = '/tmp/RtmpmTr4Wk/myProject/modules'
#>     spades.scratchPath = '/tmp/RtmpmTr4Wk/SpaDES/scratch'
#>   )
#> Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
 sim <- scheduleEvent(sim, time(sim) + 1.0, "fireSpread", "burn") # default priority
 sim <- scheduleEvent(sim, time(sim) + 1.0, "fireSpread", "burn", .normal()) # default priority

 sim <- scheduleEvent(sim, time(sim) + 1.0, "fireSpread", "burn", .normal()-1) # higher priority
 sim <- scheduleEvent(sim, time(sim) + 1.0, "fireSpread", "burn", .normal()+1) # lower priority

 sim <- scheduleEvent(sim, time(sim) + 1.0, "fireSpread", "burn", .highest()) # highest priority
 sim <- scheduleEvent(sim, time(sim) + 1.0, "fireSpread", "burn", .lowest()) # lowest priority
 events(sim) # shows all scheduled events, with eventTime and priority
#>     eventTime moduleName eventType eventPriority
#>  1:         0 checkpoint      init             0
#>  2:         0       save      init             0
#>  3:         0   progress      init             0
#>  4:         0       load      init             0
#>  5:         1 fireSpread      burn             1
#>  6:         1 fireSpread      burn             4
#>  7:         1 fireSpread      burn             5
#>  8:         1 fireSpread      burn             5
#>  9:         1 fireSpread      burn             6
#> 10:         1 fireSpread      burn            10