Lifecycle Entities

Core entity classes for the lifecycle management system.

class vivarium.framework.lifecycle.entities.LifeCycleState(name)[source]

A representation of a simulation run state.

Parameters:: name (str)

property name: str: The name of the lifecycle state.

property entrance_count: int: The number of times this state has been entered.

add_next(next_state, loop=False)[source]

Link this state to the next state in the simulation life cycle.

States are linked together and used to ensure that the simulation life cycle proceeds in the proper order. A life cycle state can be bound to two next states to allow for loops in the life cycle and both are considered valid when checking for valid state transitions. The first represents the linear progression through the simulation, while the second represents a loop in the life cycle.

Return type:

None

Parameters:

next_state (LifeCycleState) – The next state in the simulation life cycle.
loop (bool) – Whether the provided state is the linear next state or a loop back to a previous state in the life cycle.

valid_next_state(state)[source]

Check if the provided state is valid for a life cycle transition.

Return type:: bool
Parameters:: state (LifeCycleState | None) – The state to check.
Returns:: Whether the state is valid for a transition.

enter()[source]

Marks an entrance into this state.

Return type:: None

add_handlers(handlers)[source]

Registers a set of functions that will be executed during the state.

The primary use case here is for introspection and reporting. For setting constraints, see vivarium.framework.lifecycle.interface.LifeCycleInterface.add_constraint().

Return type:: None
Parameters:: handlers (list[Callable[[Event], None]]) – The set of functions that will be executed during this state.

class vivarium.framework.lifecycle.entities.LifeCyclePhase(name, states, loop)[source]

A representation of a distinct lifecycle phase in the simulation.

A lifecycle phase is composed of one or more unique lifecycle states. There is exactly one state within the phase which serves as a valid exit point from the phase. The states may operate in a loop.

Parameters:

name (str)
states (list[str])
loop (bool)

property name: str: The name of this life cycle phase.

property states: tuple[LifeCycleState, ...]: The states in this life cycle phase in order of execution.

add_next(phase)[source]

Link the provided phase as the next phase in the life cycle.

Return type:: None
Parameters:: phase (LifeCyclePhase)

get_state(state_name)[source]

Retrieve a life cycle state by name from the phase.

Return type:: LifeCycleState
Parameters:: state_name (str)

class vivarium.framework.lifecycle.entities.LifeCycle[source]

A concrete representation of the flow of simulation execution states.

add_phase(phase_name, states, loop)[source]

Add a new phase to the lifecycle.

Phases must be added in order.

Return type:

None

Parameters:

phase_name (str) – The name of the phase to add. Phase names must be unique.
states (list[str]) – The list of names (in order) of the states that make up the life cycle phase. State names must be unique across the entire life cycle.
loop (bool) – Whether the life cycle phase states loop.

Raises:

LifeCycleError – If the phase or state names are non-unique.

get_state(state_name)[source]

Retrieve a life cycle state from the life cycle.

Return type:: LifeCycleState
Parameters:: state_name (str) – The name of the state to retrieve
Returns:: The requested state.
Raises:: LifeCycleError – If the requested state does not exist.

get_state_names(phase_name)[source]

Retrieve the names of all states in the provided phase.

Return type:: list[str]
Parameters:: phase_name (str) – The name of the phase to retrieve the state names from.
Returns:: The state names in the provided phase.
Raises:: LifeCycleError – If the phase does not exist in the life cycle.