timeline

timeline

Simulation and module timelines

Classes

Name	Description
Timeline	Handle time vectors and sequencing (“timelines”) for both simulations and modules.

Timeline

timeline.Timeline(
    start=None,
    stop=None,
    dt=None,
    dur=None,
    name=None,
    init=None,
    sim=None,
)

Handle time vectors and sequencing (“timelines”) for both simulations and modules.

Each module can have its own time instance, in the case where the time vector is defined by absolute dates, these time vectors are by definition aligned. Otherwise they can be specified using dur objects which express relative times (they can be added to a date to get an absolute time)

Parameters

Name	Type	Description	Default
start	str/int/float/ss.date/ss.dur	when the simulation/module starts, e.g. ‘2000’, ‘2000-01-01’, 2000, ss.date(2000), or ss.years(2000)	None
stop	str/int/float/ss.date/ss.dur	when the simulation/module ends (note: if start is a date, stop must be too)	None
dt	int/float/ss.dur	Simulation step size	None
dur	int/float/ss.dur	If “stop” is not provided, run for this duration	None
name	str	if provided, name the Timeline object	None
init	bool	whether or not to immediately initialize the Timeline object (by default, yes if start and stop or start and dur are provided; otherwise no)	None
sim	Sim	if provided, initialize the Timeline with this as the parent (i.e. populating missing values)	None

The Timeline object, after initialization, has the following time vectors, each representing a different way of representing time:

• tvec: ground truth simulation time, either as absolute ss.date instances, or relative ss.dur instances, e.g. DateArray([<2021.01.01>, <2021.01.03>, <2021.01.05>, <2021.01.07>])
• tivec: the vector of time indices (np.arange(len(tvec)))
• timevec: the “human-friendly” representation of tvec: same as tvec if using ss.date, else floats if using ss.dur
• yearvec: time represented as floating-point years
• datevec: time represented as ss.date instances
• relvec: relative time, in the sim’s time units

The Timeline object also has the following attributes/methods:

• ti (int): the current timestep
• npts (int): the total number of time points in the timeline (one more than the number of steps; see note below)
• now() (ss.date/float/str): the current time, based on tvec by default or a different vector if specified

Note: the time vectors include both the start and stop endpoints, so npts (the number of time points) is one more than the number of steps taken. For example, start=0, stop=1, dt=1 runs a single step but produces two time points ([0, 1]), since the state is recorded at both the start and the end. Specifying the length via dur is exactly equivalent to specifying stop (internally, stop = start + dur), so e.g. start=2000, dur=1 and start=2000, stop=2001 produce identical timelines. See the time user guide for the rationale behind the inclusive endpoint.

Examples

t1 = ss.Timeline(start=2000, stop=2020, dt=1.0)
t2 = ss.Timeline(start='2021-01-01', stop='2021-04-04', dt=ss.days(2))

Attributes

Name	Description
dt_year	The timestep size in years
finished	Check if the simulation is finished, i.e. we’re at the last time point
is_absolute	Check whether the fundamental simulation unit is absolute
npts	The number of time points (inclusive of both endpoints, so one more than the number of steps)
ready	Check if all parameters are in place to be initialized
year	The current time in years

Methods

Name	Description
init	Initialize all vectors
now	Get the current simulation time
reconcile_args	Reconcile the different options for the input parameters
to_dict	Return a dictionary of all time vectors
update	Reconcile different ways of supplying inputs

init

timeline.Timeline.init(sim=None, max_steps=20000, force=False)

Initialize all vectors

now

timeline.Timeline.now(key=None)

Get the current simulation time

Parameters

Name	Type	Description	Default
key	str	which type of time to get: “tvec” (default), “time”, “year”, “date”, or “str”	None

Examples

t = ss.Timeline(start='2021-01-01', stop='2022-02-02', dt='week')
t.ti = 25
t.now() # Returns <2021-06-25>
t.now('date') # Returns <2021-06-25>
t.now('year') # Returns 2021.479
t.now('str') # Returns '2021-06-25'

reconcile_args

timeline.Timeline.reconcile_args(sim=None)

Reconcile the different options for the input parameters

to_dict

timeline.Timeline.to_dict()

Return a dictionary of all time vectors

update

timeline.Timeline.update(
    pars=None,
    parent=None,
    reset=True,
    force=None,
    **kwargs,
)

Reconcile different ways of supplying inputs

Parameters

Name	Type	Description	Default
pars	dict	dict of time parameters to apply	None
parent	Timeline	parent timeline to inherit values from	None
reset	bool	if True and stale, reinitialize after update	True
force	bool / None	False = only fill missing values; None = prioritize current; True = prioritize parent	None
kwargs		additional time parameters (start, stop, dur, dt)	{}