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 timesteps
• now() (ss.date/float/str): the current time, based on the timevec by default or a different vector if specified

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
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: “time” (default), “year”, “date”, “tvec”, 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