Simulate Trajectory From a SPN Model — sim_trajectory

This function provides a unified interface to the various simulation algorithms for SPN, returning output sampled at a lattice of time points to the user, and handling various exogenous events that may occur during the simulation (such as release of adult mosquitoes).

sim_trajectory_R(
  x0,
  tmax,
  dt = 1,
  dt_stoch = 0.1,
  num_reps = 1,
  S,
  hazards,
  Sout = NULL,
  sampler = "tau",
  method = "lsoda",
  events = NULL,
  batch = NULL,
  verbose = TRUE,
  ...
)

Arguments

x0	the initial marking of the SPN (initial state, M0)
tmax	the final time to end simulation (all simulations start at 0)
dt	the time-step at which to return output (not the time-step of the sampling algorithm)
dt_stoch	time-step used for approximation of hazards
num_reps	number of repetitions to run, default is 1.
S	a stoichiometry `Matrix-class` object
hazards	list of hazard functions
Sout	an optional matrix to track event firings
sampler	determines sampling algorithm, one of; "ode", "tau", "cle", or "dm"
method	if `sampler` is "ode", the solver to use, from `deSolve`
events	a `data.frame` of events, may be set to `NULL` if not used
batch	a `list` of batch migration events, created from `batch_migration`, may be set to `NULL` if not used
verbose	print a progress bar?
...	further named arguments passed to the step function

Value

a list with 2 elements: "state" is the array of returned state values, and "events" will return events tracked with Sout if provided, otherwise is NULL

Details

dt_stoch is used by the Poisson Time-Step (step_PTS) and Chemical Langevin (step_CLE) methods to approximate the hazards. A smaller dt_stoch provides a better approximation, but will take longer to run.

The stoichiometry matrix (S) is generated in spn_S.

The list of hazards (hazards) come from spn_hazards.

Several samplers are provided. The default is a Poisson Time-Step (step_PTS) method. Other options are Gillespie's Direct Method (step_DM) and a Chemical Langevin sampler (step_CLE). Additionally, for convenience, an ODE "sampler" (step_ODE) is provided for compatibility with other samplers. This function uses methods from deSolve.

If using the ode sampler, several methods are provided in the deSolve package, see ode. For inhomogeneous systems, consider using the "rk4" method to avoid excessive integration times.

Additionally, events objects must follow the format required by deSolve. This was done for consistency, see events for more information.

This function tracks state variables by default; an optional argument Sout can be provided to track number of event firings each time step (for discrete stochastic simulations), or cumulative intensity (for continuous stochastic simulations), or the rate function of particular events for ODE simulation. The matrix must have number of columns equal to number of events in the system (the number of hazard functions), and a row for each tracking variable. The function track_hinf is provided, which builds a matrix to track human infection events.

To save output as .csv files, see sim_trajectory_CSV.