State Machine

A state machine implementation for use in vivarium simulations.

class vivarium.framework.state_machine.Trigger(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

NOT_TRIGGERED = 0

START_INACTIVE = 1

START_ACTIVE = 2

class vivarium.framework.state_machine.Transition(input_state, output_state, probability_func=<function Transition.<lambda>>, triggered=Trigger.NOT_TRIGGERED)

A process by which an entity might change into a particular state.

Parameters:

• input_state (State) – The start state of the entity that undergoes the transition.

• output_state (State) – The end state of the entity that undergoes the transition.

• probability_func (Callable[[Index], Series]) – A method or function that describing the probability of this transition occurring.

set_active(index)

Parameters:

index (Index) –

Return type:

None

set_inactive(index)

Parameters:

index (Index) –

Return type:

None

probability(index)

Parameters:

index (Index) –

Return type:

Series

class vivarium.framework.state_machine.State(state_id, allow_self_transition=False)

An abstract representation of a particular position in a state space.

Parameters:

• state_id (str) –

• allow_self_transition (bool) –

state_id

The name of this state. This should be unique

transition_set

A container for potential transitions out of this state.

property model: str

set_model(model_name)

Defines the column name for the model this state belongs to

Parameters:

model_name (str) –

Return type:

None

next_state(index, event_time, population_view)

Moves a population between different states.

Parameters:

• index (Index) – An iterable of integer labels for the simulants.

• event_time (Time) – When this transition is occurring.

• population_view (PopulationView) – A view of the internal state of the simulation.

Return type:

None

transition_effect(index, event_time, population_view)

Updates the simulation state and triggers any side-effects associated with entering this state.

Parameters:

• index (Index) – An iterable of integer labels for the simulants.

• event_time (Time) – The time at which this transition occurs.

• population_view (PopulationView) – A view of the internal state of the simulation.

Return type:

None

cleanup_effect(index, event_time)

Parameters:

• index (Index) –

• event_time (Time) –

Return type:

None

add_transition(transition)

Adds a transition to this state and its TransitionSet.

Parameters:

transition (Transition) – The transition to add

Return type:

None

allow_self_transitions()

Return type:

None

transition_side_effect(index, event_time)

Parameters:

• index (Index) –

• event_time (Time) –

Return type:

None

class vivarium.framework.state_machine.Transient

Used to tell _next_state to transition a second time.

class vivarium.framework.state_machine.TransientState(state_id, allow_self_transition=False)

Parameters:

• state_id (str) –

• allow_self_transition (bool) –

class vivarium.framework.state_machine.TransitionSet(state_id, *transitions, allow_self_transition=False)

A container for state machine transitions.

Parameters:

• state_id (str) – The unique name of the state that instantiated this TransitionSet. Typically a string but any object implementing __str__ will do.

• iterable – Any iterable whose elements are Transition objects.

• allow_null_transition – Specified whether it is possible not to transition on a given time-step

• transitions (Transition) –

• allow_self_transition (bool) –

property name: str

Returns the name of the component. By convention, these are in snake case with arguments of the __init__ appended and separated by ..

Names must be unique within a simulation.

The name is created by first converting the name of the class to snake case. Then, the names of the initialization parameters are appended, separated by .. If a parameter is an instance of Component, its name property is used; otherwise, the string representation of the parameter is used. The resulting string is stored in the _name attribute and returned.

IMPORTANT: this property must not be accessed within the __init__ functions of this component or its subclasses or its value may not be initialized correctly.

Returns:

The unique name of the component.

Return type:

str

setup(builder)

Performs this component’s simulation setup and return sub-components.

Parameters:

builder (Builder) – Interface to several simulation tools including access to common random number generation, in particular.

Return type:

None

choose_new_state(index)

Chooses a new state for each simulant in the index.

Parameters:

index (Index) – An iterable of integer labels for the simulants.

Returns:

• List – The possible end states of this set of transitions.

• pandas.Series – A series containing the name of the next state for each simulant in the index.

Return type:

Tuple[List, Series]

append(transition)

Parameters:

transition (Transition) –

Return type:

None

extend(transitions)

Parameters:

transitions (Iterable[Transition]) –

Return type:

None

class vivarium.framework.state_machine.Machine(state_column, states=())

A collection of states and transitions between those states.

Parameters:

• state_column (str) –

• states (Iterable[State]) –

states

The collection of states represented by this state machine.

state_column

A label for the piece of simulation state governed by this state machine.

property sub_components

Provide components managed by this component.

Returns:

A list of components that are managed by this component.

Return type:

List[Component]

property columns_required: List[str] | None

Provides names of columns required by the component.

Returns:

Names of required columns not created by this component. An empty list means all available columns are needed. None means no additional columns are necessary.

Return type:

Optional[List[str]]

add_states(states)

Parameters:

states (Iterable[State]) –

Return type:

None

transition(index, event_time)

Finds the population in each state and moves them to the next state.

Parameters:

• index (Index) – An iterable of integer labels for the simulants.

• event_time (Time) – The time at which this transition occurs.

Return type:

None

cleanup(index, event_time)

Parameters:

• index (Index) –

• event_time (Time) –

Return type:

None

get_initialization_parameters()

Gets the values of the state column specified in the __init__`.

Note: this retrieves the value of the attribute at the time of calling which is not guaranteed to be the same as the original value.

Return type:

Dict[str, Any]