Functions for the simtimes slot of a simList object and its elements. To maintain modularity, the behaviour of these functions depends on where they are used. In other words, different modules can have their own timeunit. SpaDES converts these to seconds when running a simulation, but shows the user time in the units of the model as shown with timeunit(sim)

times(x, ...)

# S4 method for simList

times(x) <- value

# S4 method for simList
times(x) <- value

# S3 method for simList
time(x, unit, ...)

time(x) <- value

# S4 method for simList
time(x) <- value

end(x, ...)

# S3 method for simList
end(x, unit, ...)

end(x) <- value

# S4 method for simList
end(x) <- value

start(x, ...)

# S3 method for simList
start(x, unit = NULL, ...)

start(x) <- value

# S4 method for simList
start(x) <- value


# S4 method for simList

timeunit(x) <- value

# S4 method for simList
timeunit(x) <- value


# S4 method for simList

elapsedTime(x, ...)

# S3 method for simList
elapsedTime(x, byEvent = TRUE, units = "auto", ...)



A simList


Additional parameters.


A time, given as a numeric, optionally with a unit attribute, but this will be deduced from the model time units or module time units (if used within a module).


Character. One of the time units used in SpaDES.


Logical. If TRUE, the elapsed time will be by module and event; FALSE will report only by module. Default is TRUE.


character string. Units in which the results are desired. Can be abbreviated.


Returns or sets the value of the slot from the simList object.


timeunit will extract the current units of the time used in a simulation (i.e., within a spades call). If it is set within a simInit, e.g., times=list(start=0, end=52, timeunit = "week"), it will set the units for that simulation. By default, a simInit call will use the smallest unit contained within the metadata for the modules being used. If there are parent modules, then the parent module timeunit will be used even if one of its children is a smaller timeunit. If all modules, including parents, are set to NA, timeunit defaults to seconds. If parents are set to NA, then the set of modules defined by that parent module will be given the smallest units of the children.

Currently, available units are "second", "hours", day", "week", "month", and "year" can be used in the metadata of a module.

The user can also define a new unit. The unit name can be anything, but the function definition must be of the form dunitName, e.g., dyear or dfortnight. The unit name is the part without the d and the function name definition includes the d. This new function, e.g., dfortnight <- function(x) lubridate::duration(dday(14)) can be placed anywhere in the search path or in a module.

timeunits will extract the current units of the time of all modules used in a simulation. This is different from timeunit because it is not necessarily associated with a spades call.

In many cases, the "simpler" use of each of these functions may be slower computationally. For instance, it is much faster to use time(sim, "year") than time(sim). So as a module developer, it is advantageous to write out the longer one, minimizing the looking up that R must do.


These have default behaviour that is based on the calling frame timeunit. When used inside a module, then the time is in the units of the module. If used in an interactive mode, then the time will be in the units of the simulation.

Additional methods are provided to access the current, start, and end times of the simulation:

timeCurrent simulation time.
startSimulation start time.
endSimulation end time.
timeunitSimulation timeunit.
timeunitsModule timeunits.
timesList of all simulation times (current, start, end, timeunit).

See also

SpaDES.core-package(), specifically the section 1.2.5 on Simulation times; elapsedTime(),

Other functions to access elements of a 'simList' object: .addDepends(), doEvent.checkpoint(), envir(), events(), globals(), inputs(), modules(), objs(), packages(), params(), paths(), progressInterval()


Alex Chubaty and Eliot McIntire


# Elapsed Time
s1 <- simInit()
#> Setting:
#>   options(
#>     reproducible.cachePath = '/tmp/RtmppEYNhs/myProject/cache'
#>     spades.inputPath = '/tmp/RtmppEYNhs/myProject/inputs'
#>     spades.outputPath = '/tmp/RtmppEYNhs/myProject/outputs'
#>     spades.modulePath = '/tmp/RtmppEYNhs/myProject/modules'
#>     spades.scratchPath = '/tmp/RtmppEYNhs/SpaDES/scratch'
#>   )
#> Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
s2 <- spades(s1)
#> Jan12 22:40:20       Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
#> Jan12 22:40:20 chckpn  total elpsd: 0.00088 secs | 0 checkpoint init 0
#> Jan12 22:40:20 save    total elpsd: 0.0025 secs | 0 save init 0
#> Jan12 22:40:20 prgrss  total elpsd: 0.0041 secs | 0 progress init 0
#> Jan12 22:40:20 load    total elpsd: 0.0056 secs | 0 load init 0
#> simList saved in
#>  SpaDES.core:::.pkgEnv$.sim 
#> It will be deleted at next spades() call.
#>    moduleName eventType      elapsedTime
#> 1: checkpoint      init 0.002143860 secs
#> 2:       save      init 0.001563072 secs
#> 3:   progress      init 0.001484394 secs
#> 4:       load      init 0.001382589 secs
elapsedTime(s2, units = "mins")
#>    moduleName eventType       elapsedTime
#> 1: checkpoint      init 3.573100e-05 mins
#> 2:       save      init 2.605120e-05 mins
#> 3:   progress      init 2.473990e-05 mins
#> 4:       load      init 2.304316e-05 mins