Skip to contents

Create a SimInf_model object

Source: R/SimInf_model.R
SimInf_model.Rd

Construct a low-level SimInf_model object. This function is typically used internally by model constructors (e.g., SIR(), mparse()) or for advanced usage where custom model definitions (e.g., user-provided C code or non-standard matrices) are required.

Usage

SimInf_model(
  G,
  S,
  tspan,
  events = NULL,
  ldata = NULL,
  gdata = NULL,
  U = NULL,
  u0 = NULL,
  v0 = NULL,
  V = NULL,
  E = NULL,
  N = NULL,
  replicates = NULL,
  C_code = NULL
)

Arguments

G

Dependency Graph. Indicates which transition rates need updating after a state transition. Can be provided as a sparse matrix (class dgCMatrix) or a dense matrix. If a dense matrix is provided, it is automatically converted to a sparse format internally. See SimInf_model for detailed matrix layout.

S

State Transition Matrix. Defines the change in the state vector for each transition. Can be provided as a sparse matrix (class dgCMatrix) or a dense matrix. If a dense matrix is provided, it is automatically converted to a sparse format internally. See SimInf_model for detailed matrix layout.

tspan

Time Span (numeric or Date vector). Increasing time points for output. If Date, converted to days with names, where tspan[1] becomes the day of the year of the first year of tspan. The dates are added as names to the numeric vector.

events

Scheduled Events. A data.frame defining the event schedule (see SimInf_events).

ldata

Local Data. Parameters specific to each node. Can be:

  • A data.frame with one row per node.

  • A matrix where each column ldata[, j] is the data vector for node j.

Passed to transition rate and post-step functions.

gdata

Global Data (numeric vector). Parameters common to all nodes. Passed to transition rate and post-step functions.

U

Result Matrix (integer matrix). Usually empty at creation. See SimInf_model for detailed matrix layout.

u0

Initial State. Initial number of individuals per compartment/node. Can be:

  • A matrix (\(N_c \times N_n\)).

  • A data.frame with columns corresponding to compartments.

  • Any object coercible to a data.frame (e.g., a named numeric vector will be coerced to a one-row data.frame).

v0

Initial Continuous State (numeric matrix). Initial values for continuous states per node.

V

Continuous State Result Matrix (numeric matrix). Usually empty at creation. See SimInf_model for layout.

E

Select Matrix (matrix or data.frame). Defines which compartments are affected by events and their sampling weights.

  • Matrix: Standard sparse matrix.

  • data.frame: Must have columns compartment and select. Optional column value (default 1) sets the weight.

See SimInf_events for usage details.

N

Shift Matrix (matrix or data.frame). Defines how individuals are moved between compartments during events.

  • Matrix: Standard integer matrix.

  • data.frame: Must have columns compartment, shift, and value (integer offset).

See SimInf_events for usage details.

replicates

Number of model replicates to simulate (default NULL, treated as 1L). When replicates > 1L, each replicate is simulated independently using its own initial state (from u0), but shares the same parameters (gdata, ldata), scheduled events, and structure (transitions, compartments).

The u0 argument must contain initial states for all replicates. Each replicate requires n nodes, where n is the number of nodes in the model. Thus, u0 must have replicates * n nodes total. Nodes are grouped by replicate: the first n nodes belong to replicate 1, the next n to replicate 2, and so on. This allows different starting conditions per replicate if desired.

ldata remains unchanged: its data per node is shared across all replicates. Scheduled events are also shared—the same event schedule applies to each replicate.

Use this when you need multiple independent stochastic trajectories from the same model in a single simulation run. For identical starting conditions across replicates, simply repeat the same node pattern in u0.

C_code

C Source Code (character vector). Optional C code for custom transition rates. If provided, it is compiled and loaded when run() is called.

Value

A SimInf_model object.

See also

SIR, SEIR, SIS, SISe for examples of compartment model constructors that handle argument validation and matrix setup. mparse for creating custom models using a simple string syntax. SimInf_model for details on the class structure and slots. SimInf_events for details on the event schedule format.