SpaDES (version 1.2.0)

times: Time usage in SpaDES

Description

Functions for the simtimes slot of a simList object and its elements. To maintain modularity, the behavior 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)

Usage

times(x, ...)
"times"(x)
times(x) <- value
"times"(x) <- value
time(x, unit, ...)
"time"(x)
"time"(x, unit)
time(x) <- value
"time"(x) <- value
end(x, unit, ...)
"end"(x)
"end"(x, unit)
end(x) <- value
"end"(x) <- value
start(x, unit, ...)
"start"(x)
"start"(x, unit)
start(x) <- value
"start"(x) <- value
.callingFrameTimeunit(x)
".callingFrameTimeunit"(x)
".callingFrameTimeunit"(x)
timeunit(x)
"timeunit"(x)
timeunit(x) <- value
"timeunit"(x) <- value
timeunits(x)
"timeunits"(x)

Arguments

x

A simList simulation object.

...

Additional parameters.

value

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)

unit

Character. One of the time units used in SpaDES.

Value

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

Details

NOTE: These have default behavior 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 spades simulation.

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

time

Current simulation time.

start

Simulation start time.

end

Simulation end time.

timeunit

Simulation timeunit.

timeunits

Module timeunits.

times

List of all simulation times (current, start, end, timeunit).

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 NA, timeunit defaults to none.

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.

See Also

simList-class, simList-accessors-envir, simList-accessors-events, simList-accessors-inout, simList-accessors-modules, simList-accessors-objects, simList-accessors-params, simList-accessors-paths.