Schedule a conditional simulation event

Adds a new event to the simulation's conditional event queue, updating the simulation object by creating or appending to sim$._conditionalEvents. This is very experimental. Use with caution.

scheduleConditionalEvent(
  sim,
  condition,
  moduleName,
  eventType,
  eventPriority = .normal(),
  minEventTime = start(sim),
  maxEventTime = end(sim)
)

Arguments

sim

A simList simulation object.

condition

A string, call or expression that will be assessed for TRUE after each event in the regular event queue. It can access objects in the simList by using functions of sim, e.g., "sim$age > 1"

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().

minEventTime

A numeric specifying the time before which the event should not occur, even if the condition is met. Defaults to start(sim)

maxEventTime

A numeric specifying the time after which the event should not occur, even if the condition is met. Defaults to end(sim)

Value

Returns the modified simList object, i.e., sim$._conditionalEvents.

Details

This conditional event queue will be assessed at every single event in the normal event queue. If there are no conditional events, then spades will proceed as normal. As conditional event conditions are found to be true, then it will trigger a call to scheduleEvent(...) with the current time passed to eventTime and it will remove the conditional event from the conditional queue. If the user would like the triggered conditional event to occur as the very next event, then a possible strategy would be to set eventPriority of the conditional event to very low or even negative to ensure it gets inserted at the top of the event queue.

References

Matloff, N. (2011). The Art of R Programming (ch. 7.8.3). San Francisco, CA: No Starch Press, Inc. ISBN 978-1-59327-384-2.

See also

scheduleEvent(), conditionalEvents()

Author

Eliot McIntire

Examples

  sim <- simInit(times = list(start = 0, end = 2))
#> Setting:
#>   options(
#>     reproducible.cachePath = '/tmp/RtmpmM1qrr/myProject/cache'
#>     spades.inputPath = '/tmp/RtmpmM1qrr/myProject/inputs'
#>     spades.outputPath = '/tmp/RtmpmM1qrr/myProject/outputs'
#>     spades.modulePath = '/tmp/RtmpmM1qrr/myProject/modules'
#>     spades.scratchPath = '/tmp/RtmpmM1qrr/SpaDES/scratch'
#>   )
#> Aug29 22:30:39 simInit Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
#> Elapsed time for simInit: 0.03125238 secs
  condition <- "sim$age > 1" # provide as string
  condition <- quote(sim$age > 1) # provide as a call
  condition <- expression(sim$age > 1) # provide as an expression
  sim <- scheduleConditionalEvent(sim, condition, "firemodule", "burn")
  conditionalEvents(sim)
#>      condition minEventTime maxEventTime moduleName eventType eventPriority
#>         <char>        <num>        <num>     <char>    <char>         <num>
#> 1: sim$age > 1            0            2 firemodule      burn             5
  sim <- spades(sim) # no changes to sim$age, i.e., it is absent
#> Aug29 22:30:39 simInit Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
#> Aug29 22:30:39 chckpn:init total elpsd: 0.033 secs | 0 checkpoint init 0
#> Aug29 22:30:39 save  :init total elpsd: 0.035 secs | 0 save init 0
#> Aug29 22:30:39 prgrss:init total elpsd: 0.037 secs | 0 progress init 0
#> Aug29 22:30:39 load  :init total elpsd: 0.038 secs | 0 load init 0
#> simList saved in
#> SpaDES.core:::savedSimEnv()$.sim
#> It will be deleted at next spades() call.
  events(sim) # nothing scheduled
#> Empty data.table (0 rows and 4 cols): eventTime,moduleName,eventType,eventPriority
  sim$age <- 2 # change the value
  sim <- spades(sim) # Run spades, the condition is now true, so event is
#> Aug29 22:30:39 simInit Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
#> simList saved in
#> SpaDES.core:::savedSimEnv()$.sim
#> It will be deleted at next spades() call.
                     #  scheduled at current time
  events(sim)        # now scheduled in the normal event queue
#> Empty data.table (0 rows and 4 cols): eventTime,moduleName,eventType,eventPriority