State Machine

A state machine implementation for use in vivarium simulations.

class vivarium.framework.state_machine.Trigger[source]

An enumeration.

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: 0>)[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) – A method or function that describing the probability of this transition occurring.
name
setup(builder)[source]
set_active(index)[source]
set_inactive(index)[source]
probability(index)[source]
class vivarium.framework.state_machine.State(state_id)[source]

An abstract representation of a particular position in a finite and discrete state space.

state_id

The name of this state. This should be unique

Type:str
transition_set

A container for potential transitions out of this state.

Type:TransitionSet
name
sub_components
setup(builder)[source]
next_state(index, event_time, population_view)[source]

Moves a population between different states using information this state’s transition_set.

Parameters:
transition_effect(index, event_time, population_view)[source]

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

Parameters:
  • index (iterable of ints) – An iterable of integer labels for the simulants.
  • event_time (pandas.Timestamp) – The time at which this transition occurs.
  • population_view (vivarium.framework.population.PopulationView) – A view of the internal state of the simulation.
cleanup_effect(index, event_time)[source]
add_transition(output, probability_func=<function State.<lambda>>, triggered=<Trigger.NOT_TRIGGERED: 0>)[source]

Builds a transition from this state to the given state.

output : State
The end state after the transition.
allow_self_transitions()[source]
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)[source]
class vivarium.framework.state_machine.TransitionSet(state_name, *transitions, allow_null_transition=False)[source]

A container for state machine transitions.

Parameters:
  • state_name (object) – The unique name of the state that instantiated this TransitionSet. Typically a string but any object implementing __str__ will do.
  • iterable (iterable) – Any iterable whose elements are Transition objects.
  • allow_null_transition (bool, optional) –
name
sub_components
setup(builder)[source]

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

Parameters:builder (engine.Builder) – Interface to several simulation tools including access to common random number generation, in particular.
Returns:This component’s sub-components.
Return type:iterable
choose_new_state(index)[source]

Chooses a new state for each simulant in the index.

Parameters:index (iterable of ints) – An iterable of integer labels for the simulants.
Returns:
  • outputs (list) – The possible end states of this set of transitions.
  • decisions (pandas.Series) – A series containing the name of the next state for each simulant in the index.
append(transition)[source]
extend(transitions)[source]
class vivarium.framework.state_machine.Machine(state_column, states=None)[source]

A collection of states and transitions between those states.

states

The collection of states represented by this state machine.

Type:iterable of State objects
state_column

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

Type:str
population_view

A view of the internal state of the simulation.

Type:pandas.DataFrame
name
sub_components
setup(builder)[source]

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

Parameters:builder (engine.Builder) – Interface to several simulation tools including access to common random number generation, in particular.
Returns:This component’s sub-components.
Return type:iterable
add_states(states)[source]
transition(index, event_time)[source]

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

Parameters:
  • index (iterable of ints) – An iterable of integer labels for the simulants.
  • event_time (pandas.Timestamp) – The time at which this transition occurs.
cleanup(index, event_time)[source]
to_dot()[source]

Produces a ball and stick graph of this state machine.

Returns:A ball and stick visualization of this state machine.
Return type:graphviz.Digraph