Life Cycle Management

The life cycle is a representation of the flow of execution states in a vivarium simulation. The tools in this model allow a simulation to formally represent its execution state and use the formal representation to enforce run-time contracts.

There are two flavors of contracts that this system enforces:

• Constraints: These are contracts around when certain methods, particularly those available off the Builder, can be used. For example, simulants should only be added to the simulation during initial population creation and during the main simulation loop, otherwise services necessary for initializing that population’s attributes may not exist. By applying a constraint, we can provide very clear errors about what went wrong, rather than a deep and unintelligible stack trace.

• Ordering Contracts: The SimulationContext will construct the formal representation of the life cycle during its initialization. Once generated, the context declares as it transitions between different lifecycle states and the tools here ensure that only valid transitions occur. These kinds of contracts are particularly useful during interactive usage, as they prevent users from, for example, running a simulation whose population has not been created.

The tools here also allow for introspection of the simulation life cycle.

exception vivarium.framework.lifecycle.LifeCycleError

Generic error class for the life cycle management system.

exception vivarium.framework.lifecycle.InvalidTransitionError

Error raised when life cycle ordering contracts are violated.

exception vivarium.framework.lifecycle.ConstraintError

Error raised when life cycle constraint contracts are violated.

class vivarium.framework.lifecycle.LifeCycleState(name)

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)

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)

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()

Marks an entrance into this state.

Return type:

None

add_handlers(handlers)

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 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.LifeCyclePhase(name, states, loop)

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)

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

Return type:

None

Parameters:

phase (LifeCyclePhase)

get_state(state_name)

Retrieve a life cycle state by name from the phase.

Return type:

LifeCycleState

Parameters:

state_name (str)

class vivarium.framework.lifecycle.LifeCycle

A concrete representation of the flow of simulation execution states.

add_phase(phase_name, states, loop)

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)

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)

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.

class vivarium.framework.lifecycle.ConstraintMaker(lifecycle_manager)

Factory for making state-based constraints on component methods.

Parameters:

lifecycle_manager (LifeCycleManager)

check_valid_state(method, permitted_states)

Ensures a component method is being called during an allowed state.

Return type:

None

Parameters:

• method (Callable[[...], Any]) – The method the constraint is applied to.

• permitted_states (list[str]) – The states in which the method is permitted to be called.

Raises:

ConstraintError – If the method is being called outside the permitted states.

constrain_normal_method(method, permitted_states)

Only permit a method to be called during the provided states.

Constraints are applied by dynamically wrapping and binding a method to an existing component at run time.

Return type:

Callable[..., Any]

Parameters:

• method (Callable[[...], Any]) – The method to constrain.

• permitted_states (list[str]) – The life cycle states in which the method can be called.

Returns:

The constrained method.

static to_guid(method)

Convert a method on to a global id.

Because we dynamically rebind methods, the old ones will get garbage collected, making id() unreliable for checking if a method has been constrained before.

Return type:

str

Parameters:

method (Callable[[...], Any]) – The method to convert to a global id.

Returns:

The global id of the method.

class vivarium.framework.lifecycle.LifeCycleManager

Manages ordering- and constraint-based contracts in the simulation.

property name: str

The name of this component.

property current_state: str

The name of the current life cycle state.

property timings: dict[str, list[float]]

add_phase(phase_name, states, loop=False)

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.

set_state(state)

Sets the current life cycle state to the provided state.

Return type:

None

Parameters:

state (str) – The name of the state to set.

Raises:

• LifeCycleError – If the requested state doesn’t exist in the life cycle.

• InvalidTransitionError – If setting the provided state represents an invalid life cycle transition.

get_state_names(phase)

Gets all states in the phase in their order of execution.

Return type:

list[str]

Parameters:

phase (str) – The name of the phase to retrieve the states for.

Returns:

A list of state names in order of execution.

add_handlers(state_name, handlers)

Registers a set of functions to be called during a life cycle state.

This method does not apply any constraints, rather it is used to build up an execution order for introspection.

Return type:

None

Parameters:

• state_name (str) – The name of the state to register the handlers for.

• handlers (list[Callable[[Event], None]]) – A list of functions that will execute during the state.

add_constraint(method, allow_during=(), restrict_during=())

Constrains a function to be executable only during certain states.

Return type:

None

Parameters:

• method (Callable[[...], Any]) – The method to add constraints to.

• allow_during (tuple[str, ...] | list[str]) – An optional list of life cycle states in which the provided method is allowed to be called.

• restrict_during (tuple[str, ...] | list[str]) – An optional list of life cycle states in which the provided method is restricted from being called.

Raises:

• ValueError – If neither allow_during nor restrict_during are provided, or if both are provided.

• LifeCycleError – If states provided as arguments are not in the life cycle.

• ConstraintError – If a lifecycle constraint has already been applied to the provided method.

class vivarium.framework.lifecycle.LifeCycleInterface(manager)

Interface to the life cycle management system.

The life cycle management system allows components to constrain methods so that they’re only available during certain simulation life cycle states.

Parameters:

manager (LifeCycleManager)

add_handlers(state, handlers)

Registers a set of functions to be called during a life cycle state.

This method does not apply any constraints, rather it is used to build up an execution order for introspection.

Return type:

None

Parameters:

• state (str) – The name of the state to register the handlers for.

• handlers (list[Callable[[Event], None]]) – A list of functions that will execute during the state.

add_constraint(method, allow_during=(), restrict_during=())

Constrains a function to be executable only during certain states.

Return type:

None

Parameters:

• method (Callable[[...], Any]) – The method to add constraints to.

• allow_during (tuple[str, ...] | list[str]) – An optional list of life cycle states in which the provided method is allowed to be called.

• restrict_during (tuple[str, ...] | list[str]) – An optional list of life cycle states in which the provided method is restricted from being called.

Raises:

• ValueError – If neither allow_during nor restrict_during are provided, or if both are provided.

• LifeCycleError – If states provided as arguments are not in the life cycle.

• ConstraintError – If a life cycle constraint has already been applied to the provided method.

current_state()

Returns a callable that gets the current simulation lifecycle state.

Return type:

Callable[[], str]

Returns:

A callable that returns the current simulation lifecycle state.