-
Notifications
You must be signed in to change notification settings - Fork 10
Simulation
Simulation is an R6 class Create and represent a C++ Simulation object. It inherits the Population class. So a simulation manages agents and their contact. Thus, the class also inherits the Agent class. So a simulation can have its own state, and events attached (scheduled) to it.
In addition, it also manages all the transitions, using its addTransition method. ASt last, it maintains loggers, which record (or count) the state changes, and report their values at specified times.
initialize = function(simulation = 0, initializer=NULL)
- simulation: can be either an external pointer pointing to a population object returned from newSimulation, or an integer specifying the population size, or a list
- initializer: a function or NULL
If simulation is a number (the population size), then initializer can be a function that take the index of an agent and return its initial state. If it is a list, the length is the population size, and each element corresponds to the initial state of an agent (with the same index), and in this case, the initializer is ignored.
run = function(time)
- time: the time points to return the logger values.
a list of numeric vectors, with time and values reported by all logger.
The returned list can be coerced into a data.frame object which first column is time, and other columns are logger results, each row corresponds to a time point.
The Simulation object first collect and log the states from all agents in the simulation, then set the current time to the time of the first event, then call the resume method to actually run it.
Continue running the simulation after a call to $run or $resume method.
resume = function(time)
The parameters and the return value are the same as the $run method above. See also the details sections above.
addTransition = function(rule, waiting.time, to_change_callback = NULL, changed_callback = NULL)
- rule: a formula that gives the transition rule. See the details below
- waiting.time: an external pointer to a WaitingTime object such as one returned by newExpWaitingTime or newGammaWaitingTime, or a function (see the details section)
- to_change_callback: the R callback function to determine if the change should occur. See the details below.
- changed_callback: the R callback function after the change happened. See the details section.
If waiting.time is a function then it should take exactly one argument time, which is a numeric value holding the current value, and return a single numeric value for the waiting time (i.e., should not add time).
Formula can be used to specify either a spontaneous transition change, or a transition caused by a contact.
A spontaneous transition has the form from -> to, where from and to are state specifications. It is either a variable name holding a state (R list) or the list itself. The list can also be specified by state(...) instead of list(...)
For a spontaneous transition, the callback functions take the following two arguments
- time: the current time in the simulation
- agent: the agent who initiate the contact, an external pointer
A transition caused by contact, the formula needs to specify the states of both the agent who initiate the contact and the contact agent. The two states are connected by a + sign, the one before the
- sign is the initiator, anbd the one after the sign is the contact. The transition must be associated with a Contact object, using a ~ operator. The Contact object must be specified by a variable name that hold the external pointer to the object (created by e.g., the newRandomMixing function) For example, suppose S=list("S"), I=list("I"), and m=newRandomMixing(sim), then a possible rule specifying an infectious agent contacting a susceptible agent causing it to become exposed can be specified by
I + S -> I + list("E") ~ m
For a transition caused by a contact, the callback functions take the third argument:
- contact: the contact agent, an external pointer
addLogger = function(logger)
- logger: an external pointer returned by functions like newCounter or newStateLogger.
The object itself to chain actions.
Without adding a logger, there will be no observation of the simulation, and so no useful results.