% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/spades-core-package.R
\docType{package}
\name{SpaDES.core-package}
\alias{SpaDES.core}
\alias{SpaDES.core-package}
\title{Categorized overview of the \code{SpaDES.core} package}
\description{
\code{SpaDES.core} is a framework for building spatial discrete-event systems
from re-usable modules. A simulation is held in a single \code{simList} object,
modules schedule events that change the \code{simList}, and the events run in
time order until the simulation ends.

Below is a categorized list of the functions you will use most often.
Each entry is a short, plain-language description; click through for full
details.

Bug reports: \url{https://github.com/PredictiveEcology/SpaDES.core/issues}

Module repository: \url{https://github.com/PredictiveEcology/SpaDES-modules}

Wiki: \url{https://github.com/PredictiveEcology/SpaDES/wiki}
}
\details{
\if{html}{\figure{SpaDES.png}{options: width=100 alt="SpaDES logo" style="float: right;"}}
\if{latex}{\figure{SpaDES.png}{options: width=0.5in}}
}
\section{1 Initialize and run a simulation}{


\tabular{ll}{
\code{\link[=simInit]{simInit()}} \tab Set up a new simulation.\cr
\code{\link[=simInit2]{simInit2()}} \tab Like \code{\link[=simInit]{simInit()}}, but takes all arguments as a single list.\cr
\code{\link[=spades]{spades()}} \tab Run the simulation that \code{simInit()} set up.\cr
\code{\link[=simInitAndSpades]{simInitAndSpades()}} \tab Convenience: \code{simInit()} then \code{spades()} in one call.\cr
\code{\link[=simInitAndSpades2]{simInitAndSpades2()}} \tab Like \code{\link[=simInitAndSpades]{simInitAndSpades()}}, but takes all arguments as a single list.\cr
\code{\link[=restartSpades]{restartSpades()}} \tab Resume a simulation after an error or interruption.\cr
\code{\link[=restartOrSimInitAndSpades]{restartOrSimInitAndSpades()}} \tab Try to restart from a saved state; otherwise start fresh.\cr
}
}

\section{2 Events}{


Events are the building blocks of a simulation. Modules schedule events
that run at a given time and may schedule further events.

\tabular{ll}{
\code{\link[=scheduleEvent]{scheduleEvent()}} \tab Schedule an event to run at a given simulation time.\cr
\code{\link[=scheduleConditionalEvent]{scheduleConditionalEvent()}} \tab Schedule an event that runs when a condition becomes \code{TRUE}.\cr
\code{\link[=conditionalEvents]{conditionalEvents()}} \tab List the conditional events currently waiting.\cr
\code{\link[=doEvent]{doEvent()}} \tab Internal dispatcher; usually not called directly.\cr
\code{\link[=defineEvent]{defineEvent()}} \tab Define a new event type inside a module.\cr
}
}

\section{3 The \code{simList} object}{


The \code{simList} holds everything about a simulation: parameters, modules,
the event queue, the simulation times, and all the data objects modules
read and write. Its objects live in an environment, so updates happen
in place rather than by copying.

\tabular{ll}{
\link{simList-class} \tab The \code{simList} class definition.\cr
\code{\link[=envir]{envir()}} \tab The environment that holds the simulation's objects.\cr
\code{\link[SpaDES.core:Copy]{Copy()}} \tab Make a true (deep) copy of a \code{simList}.\cr
}
}

\section{4 \code{simList} accessors}{


Functions to read and write the various parts of a \code{simList}. All getters
have matching setters (e.g., \code{params(sim) <- ...}).

\subsection{4.1 Parameters}{
\tabular{ll}{
\code{\link[=params]{params()}} \tab All simulation parameters, as a nested list.\cr
\code{\link[=P]{P()}} \tab Get a parameter for the current module without naming it.\cr
\code{\link[=globals]{globals()}} \tab Simulation-wide (global) parameters.\cr
\code{\link[=paramCheckOtherMods]{paramCheckOtherMods()}} \tab Compare a parameter's value across modules.\cr
}
}

\subsection{4.2 Paths}{
Where files are read from and written to.

\tabular{ll}{
\code{\link[=paths]{paths()}} \tab All paths used by the simulation.\cr
\code{\link[=getPaths]{getPaths()}}, \code{\link[=setPaths]{setPaths()}} \tab Get or set all paths in one call.\cr
\code{\link[=cachePath]{cachePath()}} \tab Where cached results are stored.\cr
\code{\link[=modulePath]{modulePath()}} \tab Where modules are loaded from.\cr
\code{\link[=inputPath]{inputPath()}} \tab Where input files are read from.\cr
\code{\link[=outputPath]{outputPath()}} \tab Where output files are written.\cr
\code{\link[=dataPath]{dataPath()}} \tab Where a module finds its \verb{data/} folder.\cr
\code{\link[=figurePath]{figurePath()}} \tab Where figures are saved.\cr
\code{\link[=logPath]{logPath()}} \tab Where simulation logs are written.\cr
\code{\link[=scratchPath]{scratchPath()}} \tab Disposable working directory.\cr
\code{\link[=rasterPath]{rasterPath()}}, \code{\link[=terraPath]{terraPath()}} \tab Temporary raster directories.\cr
}
}

\subsection{4.3 Simulation times}{
\tabular{ll}{
\code{\link[=time]{time()}} \tab The current simulation time.\cr
\code{\link[=start]{start()}}, \code{\link[=end]{end()}} \tab Start and end times.\cr
\code{\link[=times]{times()}} \tab All times (current, start, end) at once.\cr
\code{\link[=timeunit]{timeunit()}} \tab The time unit of the simulation (or of a module).\cr
\code{\link[=timeunits]{timeunits()}} \tab The time units of all modules in the simulation.\cr
\code{\link[=minTimeunit]{minTimeunit()}}, \code{\link[=maxTimeunit]{maxTimeunit()}} \tab The shortest and longest time unit in use.\cr
\code{\link[=convertTimeunit]{convertTimeunit()}} \tab Convert a number between time units.\cr
\code{\link[=elapsedTime]{elapsedTime()}} \tab How much real time each module and event used.\cr
}

Helpers for writing durations: \code{\link[=dsecond]{dsecond()}}, \code{\link[=dmin]{dmin()}}, \code{\link[=dhour]{dhour()}}, \code{\link[=dday]{dday()}},
\code{\link[=dweek]{dweek()}}, \code{\link[=dmonth]{dmonth()}}, \code{\link[=dyear]{dyear()}}.
}

\subsection{4.4 Event queues}{
\tabular{ll}{
\code{\link[=events]{events()}} \tab The queue of scheduled events.\cr
\code{\link[=current]{current()}} \tab The event being run right now.\cr
\code{\link[=completed]{completed()}} \tab Events that have already run.\cr
}
}

\subsection{4.5 Objects in the simulation}{
\tabular{ll}{
\code{\link[=objs]{objs()}} \tab All data objects in the simulation environment.\cr
\code{\link[=ls]{ls()}}, \code{\link[=objects]{objects()}} \tab Names of those objects (base R methods).\cr
\code{\link[=ls.str]{ls.str()}} \tab Names plus a short summary of each object's structure.\cr
}
}

\subsection{4.6 Modules in the simulation}{
\tabular{ll}{
\code{\link[=modules]{modules()}} \tab The modules loaded in this simulation.\cr
\code{\link[=depends]{depends()}} \tab Each module's declared dependencies.\cr
\code{\link[=packages]{packages()}} \tab R packages required by the modules.\cr
}
}
}

\section{5 Building a module}{


\subsection{5.1 Module metadata}{
Every module declares its name, parameters, inputs and outputs using
these constructors, called inside \code{\link[=defineModule]{defineModule()}}.

\tabular{ll}{
\code{\link[=defineModule]{defineModule()}} \tab Top-level metadata constructor.\cr
\code{\link[=defineParameter]{defineParameter()}} \tab Declare one parameter with a default.\cr
\code{\link[=expectsInput]{expectsInput()}} \tab Declare one input the module reads from \code{sim}.\cr
\code{\link[=createsOutput]{createsOutput()}} \tab Declare one output the module writes to \code{sim}.\cr
\code{\link[=bindrows]{bindrows()}} \tab Combine the rows above into the metadata table.\cr
}
}

\subsection{5.2 Reading module metadata back}{
\tabular{ll}{
\code{\link[=moduleMetadata]{moduleMetadata()}} \tab The whole metadata block.\cr
\code{\link[=moduleParams]{moduleParams()}}, \code{\link[=moduleInputs]{moduleInputs()}}, \code{\link[=moduleOutputs]{moduleOutputs()}} \tab Just one slice.\cr
\code{\link[=moduleObjects]{moduleObjects()}} \tab All objects a module reads or writes.\cr
\code{\link[=moduleVersion]{moduleVersion()}} \tab The declared version.\cr
\link{moduleDefaults} \tab Default values used when metadata is missing.\cr
\code{\link[=parameters]{parameters()}}, \code{\link[=inputObjects]{inputObjects()}}, \code{\link[=outputObjects]{outputObjects()}} \tab Read these on a \code{simList}.\cr
\code{\link[=citation]{citation()}}, \code{\link[=documentation]{documentation()}}, \code{\link[=reqdPkgs]{reqdPkgs()}} \tab Other metadata accessors.\cr
}
}

\subsection{5.3 Helpers inside event functions}{
\tabular{ll}{
\code{\link[=currentModule]{currentModule()}} \tab The name of the running module.\cr
\code{\link[=suppliedElsewhere]{suppliedElsewhere()}} \tab \code{TRUE} if another module already provides an object.\cr
\code{\link[=checkObject]{checkObject()}} \tab Confirm a required object exists in \code{sim}.\cr
\code{\link[=findObjects]{findObjects()}} \tab Look up objects across modules.\cr
}
}

\subsection{5.4 Authoring and packaging modules}{
\tabular{ll}{
\code{\link[=newModule]{newModule()}} \tab Create a new module from a template.\cr
\code{\link[=newModuleCode]{newModuleCode()}}, \code{\link[=newModuleDocumentation]{newModuleDocumentation()}}, \code{\link[=newModuleTests]{newModuleTests()}} \tab
Generate individual parts of a module.\cr
\code{\link[=copyModule]{copyModule()}} \tab Copy a module to a new location and (optionally) rename it.\cr
\code{\link[=openModules]{openModules()}} \tab Open one or more module files in the editor.\cr
\code{\link[=zipModule]{zipModule()}} \tab Zip up a module for distribution.\cr
\code{\link[=convertToPackage]{convertToPackage()}} \tab Turn a module into an installable R package.\cr
\code{\link[=newProject]{newProject()}} \tab Create a new project that contains modules.\cr
}
}
}

\section{6 Module dependencies and diagrams}{


\code{simInit()} works out which modules depend on which. These functions
inspect that graph.

\tabular{ll}{
\code{\link[=depsEdgeList]{depsEdgeList()}} \tab Edge list of object dependencies between modules.\cr
\code{\link[=depsGraph]{depsGraph()}} \tab The same, as an \code{igraph}.\cr
\code{\link[=moduleDiagram]{moduleDiagram()}} \tab A simplified picture of which module feeds which.\cr
\code{\link[=objectDiagram]{objectDiagram()}} \tab A detailed picture, by individual object.\cr
\code{\link[=eventDiagram]{eventDiagram()}} \tab Gantt chart of events that ran in a completed simulation.\cr
}
}

\section{7 Caching}{


Caching makes a workflow reproducible and skips re-running steps that
have not changed. Caching uses the \code{reproducible} package; SpaDES adds
shortcuts for caching at the \code{spades}, module, event, and function level.

\tabular{ll}{
\code{\link[reproducible:Cache]{reproducible::Cache()}} \tab Cache any function call.\cr
\code{\link[reproducible:showCache]{reproducible::showCache()}} \tab Inspect what is in the cache.\cr
\code{\link[reproducible:clearCache]{reproducible::clearCache()}} \tab Remove cached entries.\cr
\code{\link[reproducible:keepCache]{reproducible::keepCache()}} \tab Keep only the entries you name.\cr
}

Inside a module's metadata you can set the parameter \code{.useCache} to \code{TRUE}
(cache the whole module), a character vector (cache only those events),
or use \code{.useCacheArgs} to pin per-event arguments to \code{\link[reproducible:Cache]{reproducible::Cache()}}.
See the caching vignette: \code{vignette("iii-cache", package = "SpaDES.core")}.
}

\section{8 Plotting}{


Plotting goes through \code{quickPlot::Plot()}, which is optimised for fast
redraws within a simulation. SpaDES.core adds the \code{\link[=Plots]{Plots()}} wrapper that
lets a module choose at runtime whether to render to screen, a PNG file,
or no output at all.

\tabular{ll}{
\code{\link[=Plots]{Plots()}} \tab Module-friendly wrapper for any plotting function.\cr
\code{\link[=anyPlotting]{anyPlotting()}} \tab \code{TRUE} if the current \code{.plots} setting will produce any output.\cr
}
}

\section{9 Code checking}{


When \code{simInit()} runs, it can statically check each module's code against
the metadata: every \code{sim$x} and parameter access is checked to be sure it
matches the declared inputs, outputs, and parameters.

\tabular{ll}{
\code{\link[=codeCheckModule]{codeCheckModule()}} \tab Run the checks on a module on disk (no \code{simInit()} needed).\cr
}

Controlled by these options:
\tabular{ll}{
\code{spades.moduleCodeChecks} \tab Turn the in-\code{simInit()} checks on (\code{TRUE}) or off (\code{FALSE}).\cr
\code{spades.codeCheckEngine} \tab \code{"v1"} (default) or \code{"v2"} (new, structured output).\cr
}
}

\section{10 Persistence and recovery}{


\tabular{ll}{
\code{\link[=saveSimList]{saveSimList()}} \tab Save a \code{simList} to disk.\cr
\code{\link[=loadSimList]{loadSimList()}} \tab Load one back.\cr
\code{\link[=zipSimList]{zipSimList()}}, \code{\link[=unzipSimList]{unzipSimList()}} \tab Save/load a \code{simList} together with its files.\cr
\code{\link[=saveState]{saveState()}} \tab Snapshot the state during a run.\cr
\code{\link[=restartR]{restartR()}} \tab Restart R (for example, to free memory) and continue.\cr
\code{\link[=saveFiles]{saveFiles()}}, \code{\link[=loadFiles]{loadFiles()}} \tab Save or load files described by \code{outputs()} / \code{inputs()}.\cr
\code{\link[=checksums]{checksums()}} \tab Verify (or write) checksums for a module's data files.\cr
}
}

\section{11 Memory monitoring}{


\tabular{ll}{
\code{\link[=memoryUse]{memoryUse()}} \tab Memory used by each event in a finished simulation.\cr
\code{\link[=memoryUseThisSession]{memoryUseThisSession()}} \tab Memory used by the current R session.\cr
}

See \code{vignette("iv-advanced", package = "SpaDES.core")} for how to enable
the background sampler with \code{options(spades.memoryUseInterval = ...)}.
}

\section{12 Module repository and downloads}{


\tabular{ll}{
\code{\link[=getModuleVersion]{getModuleVersion()}} \tab Get the latest version number on the repository.\cr
\code{\link[=getSampleModules]{getSampleModules()}} \tab Copy the bundled sample modules somewhere usable.\cr
}
}

\section{13 Sample modules included with the package}{


Three small modules in \verb{inst/sampleModules/}, plus a module group that
loads all three:

\tabular{ll}{
\code{randomLandscapes} \tab Generates a \code{SpatRaster} stack of random landscape layers.\cr
\code{fireSpread} \tab Simulates fire ignition and spread on those layers.\cr
\code{caribouMovement} \tab Agent-based caribou movement (correlated random walk).\cr
\code{SpaDES_sampleModules} \tab Module group that loads all three.\cr
}

Get a copy with \code{getSampleModules(tempdir())}.
}

\section{14 Package options}{


Many behaviours are configurable through R options (e.g., default paths,
how much output to print, code-checking, parallelism). See \code{\link[=spadesOptions]{spadesOptions()}}
for the full list with defaults and descriptions; the defaults are also
returned as a named list by calling \code{spadesOptions()}.
}

\seealso{
\code{\link[=spadesOptions]{spadesOptions()}}
}
\author{
\strong{Maintainer}: Eliot J B McIntire \email{eliot.mcintire@canada.ca} (\href{https://orcid.org/0000-0002-6914-8316}{ORCID})

Authors:
\itemize{
  \item Eliot J B McIntire \email{eliot.mcintire@canada.ca} (\href{https://orcid.org/0000-0002-6914-8316}{ORCID})
  \item Alex M Chubaty \email{achubaty@for-cast.ca} (\href{https://orcid.org/0000-0001-7146-8135}{ORCID})
}

Other contributors:
\itemize{
  \item Yong Luo \email{Yong.Luo@gov.bc.ca} [contributor]
  \item Steve Cumming \email{Steve.Cumming@sbf.ulaval.ca} [contributor]
  \item Ceres Barros \email{ceres.barros@ubc.ca} (\href{https://orcid.org/0000-0003-4036-977X}{ORCID}) [contributor]
  \item His Majesty the King in Right of Canada, as represented by the Minister of Natural Resources Canada [copyright holder]
}

}
