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:	index (iterable of ints) – An iterable of integer labels for the simulants. event_time (pandas.Timestamp) – When this transition is occurring. population_view (vivarium.framework.population.PopulationView) – A view of the internal state of the simulation.

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