State Machine

A state machine implementation for use in vivarium simulations.

class vivarium.framework.state_machine.Trigger(value)[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)[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.

property name: str
setup(builder)[source]
Parameters:

builder (Builder) –

Return type:

None

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

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

Parameters:

state_id (str) –

state_id

The name of this state. This should be unique

transition_set

A container for potential transitions out of this state.

property name: str
property sub_components: List
setup(builder)[source]
Parameters:

builder (Builder) –

Return type:

None

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(output, probability_func=<function State.<lambda>>, triggered=Trigger.NOT_TRIGGERED)[source]

Builds a transition from this state to the given state.

Parameters:
Returns:

The created transition object.

Return type:

Transition

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

state_id (str) –

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

A container for state machine transitions.

Parameters:

  • state_name (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 (bool) –

  • transitions (Transition) –

property name: str
property sub_components: List
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.

population_view

A view of the internal state of the simulation.

property name: str
property sub_components
setup(builder)[source]
Parameters:

builder (Builder) –

Return type:

None

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