SpaDES.core (version 3.2.1)

saveSimList: Save a whole simList object to disk

Description

Saving a simList may not work using the standard approaches (e.g., save, saveRDS, and qs2::qs_save). 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,
  files = TRUE,
  ...,
  lazy = FALSE
)

Value

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

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 .qs2 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.

files

Logical. Should all the files in the optional outputs, inputs, cache be saved. If this is TRUE, then the resulting filename will be silently converted to an archive file with the appropriate extension e.g., .zip or .tar.gz. This will automatically be TRUE if any of the outputs, inputs or cache are TRUE. Setting this to FALSE will turn off the saving of files specified in inputs(sim), outputs(sim) or the cache.

...

Additional arguments. See Details.

lazy

Logical. If TRUE, the user objects in sim@.xData are saved into a sibling lazy-load DB (a <filename>_xData.rdx/.rdb pair built by tools:::makeLazyLoadDB()) alongside the shell simList file, rather than monolithically. loadSimList() detects this layout automatically and restores the objects via lazyLoad(), materializing each one only on first access. Defaults to FALSE.

Two ways to use this

1. Portable -- take the simulation with you

Save everything: the objects, the metadata, and the files behind any file-backed objects. Use this to move a simulation to another machine or hand it to someone else.

`saveSimList(sim, "mySim.rds", projectPath = projectPath)`

`projectPath` is the root that everything is stored relative to, so the whole thing can be unpacked somewhere else and still resolve. A file-backed object is re-rooted on load if it lives under `projectPath` or under one of the sim's own paths (`outputPath`, `inputPath`, `cachePath`, ...).

2. In place -- keep the metadata, leave the files alone

Save the information but not the file bundle, on the assumption you still have the paths the run used -- above all outputPath(sim).

`saveSimList(sim, "mySim.rds", projectPath = projectPath, files = FALSE)`

Reload it and use `outputs(sim)` to see what the run wrote, then read back whatever you actually need. This is usually the practical choice: a real run writes far too many objects to bundle into an archive.

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().

The sim@.xData$._sim slot (a circular reference used internally during a running simulation) is removed before saving to avoid redundant data. It is not needed for a saved/restored simList.

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").

See Also

loadSimList()

Examples

## ---- 1. Portable: take everything with you ----
projectPath <- file.path(tempdir(), "myProject")
outPath <- file.path(projectPath, "outputs")
dir.create(outPath, recursive = TRUE, showWarnings = FALSE)

sim <- simInit(times = list(start = 0, end = 1, timeunit = "year"),
               paths = list(outputPath = outPath))
sim$anObject <- 1:10

saveSimList(sim, file.path(projectPath, "portable.rds"),
            projectPath = projectPath)

## unpack it anywhere -- pass the new location as projectPath
sim2 <- loadSimList(file.path(projectPath, "portable.rds"),
                    projectPath = projectPath)
sim2$anObject

## ---- 2. In place: metadata only, files stay put ----
## `files = FALSE` skips bundling; the run's own files are left where
## they are, and the reloaded simList tells you where to find them
saveSimList(sim, file.path(projectPath, "inPlace.rds"),
            projectPath = projectPath, files = FALSE)

sim3 <- loadSimList(file.path(projectPath, "inPlace.rds"),
                    projectPath = projectPath)
outputPath(sim3)   # where the run wrote its outputs
outputs(sim3)      # the manifest of what it wrote

unlink(projectPath, recursive = TRUE)