saveSimList: Save a whole 'simList' object to disk

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

Save a whole simList object to disk

Description

Saving a simList may not work using the standard approaches (e.g., save, saveRDS, and qs::qsave). There are 2 primary reasons why this doesn't work as expected: the activeBindings that are in place within modules (these allow the mod and Par to exist), and file-backed objects, such as SpatRaster and ⁠Raster*⁠. Because of these, a user should use saveSimList and loadSimList. These will save the object and recover the object using the filename supplied, if there are no file-backed objects. If there are file-backed objects, then it will save an archive (default is .tar.gz using the archive package for non-Windows and zip() if using Windows, as there is currently an unidentified bug in ⁠archive*⁠ on Windows). The user does not need to specify the filename any differently, as the code will search based on the filename without the file extension.

Usage

saveSimList(
  sim,
  filename,
  projectPath = getwd(),
  outputs = TRUE,
  inputs = TRUE,
  cache = FALSE,
  envir,
  ...
)

Arguments

sim	Either a simList or a character string of the name of a simList that can be found in envir. Using a character string will assign that object name to the saved simList, so when it is recovered it will be given that name.
filename	Character string with the path for saving simList to or reading the simList from. Currently, only .rds and .qs file types are supported.
projectPath	Should be the "top level" or project path for the simList. Defaults to getwd(). All other paths will be made relative with respect to this if nested within this.
outputs	Logical. If TRUE, all files identified in outputs(sim) will be included in the zip.
inputs	Logical. If TRUE, all files identified in inputs(sim) will be included in the zip.
cache	Logical. Not yet implemented. If TRUE, all files in cachePath(sim) will be included in the archive. Defaults to FALSE as this could be large, and may include many out of date elements. See Details.
envir	If sim is a character string, then this must be provided. It is the environment where the object named sim can be found.
...	Additional arguments. See Details.

Details

There is a family of 2 functions that are mutually useful for saving and loading simList objects and their associated files (e.g., file-backed ⁠Raster*⁠, inputs, outputs, cache) saveSimList(), loadSimList().

Additional arguments may be passed via ..., including:

• files: logical indicating whether files should be included in the archive. if FALSE, will override cache, inputs, outputs, setting them to FALSE.

• symlinks: a named list of paths corresponding to symlinks, which will be used to substitute normalized absolute paths of files. Names should correspond to the names in paths(); values should be project-relative paths. E.g., list(cachePath = "cache", inputPath = "inputs", outputPath = "outputs").

Value

Invoked for side effects of saving both a .qs (or .rds) file, and a compressed archive (one of .tar.gz if using non-Windows OS or .zip on Windows).

See Also

loadSimList()

SpaDES.core documentation built on Sept. 9, 2025, 5:40 p.m.