SimInf (version 11.1.0)

punchcard<-: Set a sparse recording template for simulation results

Description

Define a template (or "punchcard") specifying which data points (nodes, time-points, and compartments) should be recorded during a simulation. This feature is useful for saving memory when the model has many nodes or time-points, but only a subset of the data is needed for post-processing.

Usage

punchcard(model) <- value
# S4 method for SimInf_model
punchcard(model) <- value

Arguments

model

A SimInf_model object.

value

A data.frame defining the recording template, or NULL to reset the model to record all compartments for all nodes at all time-points in tspan.

Details

The template is specified as a data.frame with columns:

• time: The time-points to record.

• node: The node indices to record.

• CompartmentName: Logical columns (e.g., S, I, R) indicating whether to record that specific compartment for the corresponding row. If a compartment column is omitted, it defaults to FALSE (not recorded). If only time and node are provided, all compartments are recorded for those points.

Important: The specified time values, node indices, and compartment names must exist in the model. If any value in the template does not match the model's configuration (e.g., a time point not in tspan or a compartment not defined in the model), an error will be raised when the template is set.

Note that the template only affects which data is stored in the result object; it does not affect how the solver simulates the trajectory.

Examples

## For reproducibility, specify the number of threads.
set_num_threads(1)

## Create an 'SIR' model with 6 nodes
u0 <- data.frame(
  S = 100:105,
  I = 1:6,
  R = rep(0, 6)
)
model <- SIR(
  u0 = u0,
  tspan = 1:10,
  beta = 0.16,
  gamma = 0.077
)

## Run the model with default recording (all data).
## For reproducibility, specify the seed.
result_full <- run(model, seed = 22)
head(trajectory(result_full))

## Define a template to record only nodes 2 and 4 at times 3 and 5
## for all compartments.
df <- data.frame(
  time = c(3, 5, 3, 5),
  node = c(2, 2, 4, 4),
  S = TRUE, I = TRUE, R = TRUE
)
punchcard(model) <- df

result_sparse <- run(model, seed = 22)
trajectory(result_sparse)

## Record only specific compartments (e.g., S and R, but not I)
df <- data.frame(
  time = c(3, 5, 3, 5),
  node = c(2, 2, 4, 4),
  S = TRUE, I = FALSE, R = TRUE
)
punchcard(model) <- df
result_partial <- run(model, seed = 22)
trajectory(result_partial)

## Shortcut: If only 'time' and 'node' are specified, all
## compartments are recorded.
df <- data.frame(
  time = c(3, 5, 3, 5),
  node = c(2, 2, 4, 4)
)
punchcard(model) <- df

## Reset to record all data (equivalent to no template)
punchcard(model) <- NULL
result_reset <- run(model, seed = 22)
head(trajectory(result_reset))