restartSpades: Restart an interrupted simulation

In SpaDES.core: Core Utilities for Developing and Running Spatially Explicit Discrete Event Models

Restart an interrupted simulation

Description

This is experimental and has not been thoroughly tested. Use with caution. If there is an error during an event, this function will rewind the simulation to a state numEvents prior to the event that led to the error. The developer may then modify the source code of the module that caused the break and resume the simulation.

Usage

restartSpades(
  sim = NULL,
  module = NULL,
  numEvents = Inf,
  restart = TRUE,
  verbose = getOption("reproducible.verbose", 1L),
  ...
)

saveState(filename, ...)

restartOrSimInitAndSpades(ll, file, reset = getOption("spades.resetRestart"))

Arguments

sim	A simList or a filename that will load a simList, e.g., from saveState or saveSimList. If not supplied (the default), this will take the sim from savedSimEnv()$.sim, i.e., the one that was interrupted
module	A character string length one naming the module that caused the error and whose source code was fixed. This module will be re-parsed and placed into the simList
numEvents	Numeric. Default is Inf (i.e., all available). The number of events to be rewound. In the simList, if options('spades.recoveryMode') is set to TRUE or a numeric, then there will be a list in the simList called .recoverableObjs. These will be replayed backwards in time to reproduce the initial state of the simList before the event that is numEvents prior to the first event in events(sim).
restart	Logical. If TRUE, then the call to spades will be made, i.e., restarting the simulation. If FALSE, then it will return a new simList with the module code parsed into the simList
verbose	Logical or Numeric, follows reproducible.verbose value by default.
...	Passed to spades, e.g., debug, .plotInitialTime
filename	The filename to save the sim state. saveState is a wrapper around restartSpades and saveSimList. You can pass arguments to the ... that will be passed to saveSimList, such as modules, inputs, outputs.
ll	A list of elements that would be passed to simInit, such as modules.
file	An optional file that has a saved simList, e.g., from saveSimList or saveState.
reset	Logical. If TRUE, then it will force simInitAndSpades to be called even if there is saved sim available.

Details

If options('spades.recoveryMode') is set to TRUE or a numeric (default 1), then there will be a list in the simList called .recoverableObjs. These record the elements of simList that have changed over a number of events equal to the number chosen for options('spades.recoveryMode'). The restartSpades function then uses this list to rewind numEvents backwards from the first event in events(sim) (likely the one that caused the error).

The random number seed will be reset to the state it was at the start of the earliest event recovered, thereby returning to the exact stochastic simulation trajectory.

Value

A simList as if spades had been called on a simList.

A simList, that has been "executed" until end(sim), if it does not hit an error.

Note

The simList will be in the state it was numEvents prior to the event that led to the error (although some objects, e.g., on disk, may have already been modified).

Examples

# options("spades.recoveryMode" = 1) # now the default
s <- simInit()
s <- spades(s) # if this is interrupted or fails
## the following line will not work if the previous line didn't fail:

## don't need to specify `sim` if previous line fails;
## will take from savedSimEnv()$.sim automatically
s <- restartSpades(s)

SpaDES.core documentation built on Jan. 11, 2026, 9:06 a.m.