The Simulation Clock

The components here provide implementations of different kinds of simulation clocks for use in vivarium.

For more information about time in the simulation, see the associated concept note.

class vivarium.framework.time.SimulationClock

A base clock that includes global clock and a pandas series of clocks for each simulant

property name

property columns_created: List[str]

property columns_required: List[str]

property time: Timestamp | datetime | Number

The current simulation time.

property stop_time: Timestamp | datetime | Number

The time at which the simulation will stop.

property minimum_step_size: Timedelta | timedelta | Number

The minimum step size.

property standard_step_size: Timedelta | timedelta | Number

The standard varied step size.

property step_size: Timedelta | timedelta | Number

The size of the next time step.

property event_time: Timestamp | datetime | Number

Convenience method for event time, or clock + step

setup(builder)

Parameters:

builder (Builder) –

on_post_setup(event)

Parameters:

event (Event) –

Return type:

None

on_initialize_simulants(pop_data)

Sets the next_event_time and step_size columns for each simulant

Parameters:

pop_data (SimulantData) –

Return type:

None

simulant_next_event_times(index)

The next time each simulant will be updated.

Parameters:

index (Index) –

Return type:

Series

simulant_step_sizes(index)

The step size for each simulant.

Parameters:

index (Index) –

Return type:

Series

step_backward()

Rewinds the clock by the current step size.

Return type:

None

step_forward(index)

Advances the clock by the current step size, and updates aligned simulant clocks.

Parameters:

index (Index) –

Return type:

None

get_active_simulants(index, time)

Gets population that is aligned with global clock

Parameters:

• index (Index) –

• time (Timestamp | datetime | Number) –

Return type:

Index

move_simulants_to_end(index)

Parameters:

index (Index) –

Return type:

None

step_size_post_processor(values, _)

Computes the largest feasible step size for each simulant. This is the smallest component-modified step size (rounded down to increments of the minimum step size), or the global step size, whichever is larger. If no components modify the step size, we default to the global step size.

Parameters:

values (List[ndarray | Series | DataFrame | Number]) – A list of step sizes

Returns:

The largest feasible step size for each simulant

Return type:

pandas.Series

class vivarium.framework.time.SimpleClock

A unitless step-count based simulation clock.

CONFIGURATION_DEFAULTS: Dict[str, Any] = {'time': {'end': 100, 'standard_step_size': None, 'start': 0, 'step_size': 1}}

A dictionary containing the defaults for any configurations managed by this manager. An empty dictionary indicates no managed configurations.

property name

setup(builder)

vivarium.framework.time.get_time_stamp(time)

class vivarium.framework.time.DateTimeClock

A date-time based simulation clock.

CONFIGURATION_DEFAULTS: Dict[str, Any] = {'time': {'end': {'day': 2, 'month': 7, 'year': 2010}, 'standard_step_size': None, 'start': {'day': 2, 'month': 7, 'year': 2005}, 'step_size': 1}}

A dictionary containing the defaults for any configurations managed by this manager. An empty dictionary indicates no managed configurations.

property name

setup(builder)

class vivarium.framework.time.TimeInterface(manager)

Parameters:

manager (SimulationClock) –

clock()

Gets a callable that returns the current simulation time.

Return type:

Callable[[], Timestamp | datetime | Number]

step_size()

Gets a callable that returns the current simulation step size.

Return type:

Callable[[], Timedelta | timedelta | Number]

simulant_next_event_times()

Gets a callable that returns the next event times for simulants.

Return type:

Callable[[Index], Series]

simulant_step_sizes()

Gets a callable that returns the simulant step sizes.

Return type:

Callable[[Index], Series]

move_simulants_to_end()

Gets a callable that moves simulants to the end of the simulation

Return type:

Callable[[Index], None]

register_step_size_modifier(modifier, requires_columns=(), requires_values=(), requires_streams=())

Registers a step size modifier.

Parameters:

• modifier (Callable[[Index], Series]) – Modifier of the step size pipeline. Modifiers can take an index and should return a series of step sizes.

• requires_columns (List[str]) – A list of the state table columns that already need to be present and populated in the state table before the modifier is called.

• requires_values (List[str]) – A list of the value pipelines that need to be properly sourced before the modifier is called.

• requires_streams (List[str]) – A list of the randomness streams that need to be properly sourced before the modifier is called.

Return type:

None