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)[source]
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)[source]

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)[source]
Parameters:

index (Index)

Return type:

None

set_inactive(index)[source]
Parameters:

index (Index)

Return type:

None

probability(index)[source]
Parameters:

index (Index)

Return type:

Series

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

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)[source]

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)[source]

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)[source]

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)[source]
Parameters:
  • index (Index)

  • event_time (Time)

Return type:

None

add_transition(transition)[source]

Adds a transition to this state and its TransitionSet.

Parameters:

transition (Transition) – The transition to add

Return type:

None

allow_self_transitions()[source]
Return type:

None

transition_side_effect(index, event_time)[source]
Parameters:
  • index (Index)

  • event_time (Time)

Return type:

None

class vivarium.framework.state_machine.Transient[source]

Used to tell _next_state to transition a second time.

class vivarium.framework.state_machine.TransientState(state_id, allow_self_transition=False)[source]
Parameters:
  • state_id (str)

  • allow_self_transition (bool)

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

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)[source]

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)[source]

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)[source]
Parameters:

transition (Transition)

Return type:

None

extend(transitions)[source]
Parameters:

transitions (Iterable[Transition])

Return type:

None

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

A collection of states and transitions between those states.

Parameters:
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)[source]
Parameters:

states (Iterable[State])

Return type:

None

transition(index, event_time)[source]

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)[source]
Parameters:
  • index (Index)

  • event_time (Time)

Return type:

None

get_initialization_parameters()[source]

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]