State Machine

A state machine implementation for use in vivarium simulations.

vivarium.framework.state_machine.default_probability_function(index)[source]

Transition decision function that always triggers this transition.

Parameters:

index (pd.Index[int])

Return type:

pd.Series[float]

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)

  • output_state (State)

  • probability_func (Callable[[pd.Index[int]], pd.Series[float]])

  • triggered (Trigger)

set_active(index)[source]
Parameters:

index (pd.Index[int])

Return type:

None

set_inactive(index)[source]
Parameters:

index (pd.Index[int])

Return type:

None

probability(index)[source]
Parameters:

index (pd.Index[int])

Return type:

pd.Series[float]

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

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

Parameters:

  • state_id (str)

  • allow_self_transition (bool)

  • initialization_weights (DataInput)

state_id

The name of this state. This should be unique

transition_set

A container for potential transitions out of this state.

property configuration_defaults: dict[str, Any]

Provides a dictionary containing the defaults for any configurations managed by this component.

These default values will be stored at the component_configs layer of the simulation’s LayeredConfigTree.

Returns:

  • A dictionary containing the defaults for any configurations managed by

  • this component.

property model: str | None
has_initialization_weights()[source]

Determines if state has explicitly defined initialization weights.

Return type:

bool

set_model(model_name)[source]

Defines the column name for the model this state belongs to

Return type:

None

Parameters:

model_name (str)

next_state(index, event_time, population_view)[source]

Moves a population between different states.

Parameters:

  • index (pd.Index[int]) – An iterable of integer labels for the simulants.

  • event_time (ClockTime) – 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 (pd.Index[int]) – An iterable of integer labels for the simulants.

  • event_time (ClockTime) – 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 (pd.Index[int])

  • event_time (ClockTime)

Return type:

None

add_transition(transition=None, output_state=None, probability_function=<function default_probability_function>, triggered=Trigger.NOT_TRIGGERED)[source]

Adds a transition to this state and its TransitionSet.

A transition can be added by passing a Transition object or by specifying an output state and a decision function. If a transition is provided, the output state and decision function must not be.

Parameters:

  • transition (Transition | None) – The transition to add.

  • output_state (State | None) – The state to transition to

  • probability_function (Callable[[pd.Index[int]], pd.Series[float]]) – A function that determines the probability that this transition should happen. By default, this is a function that will produce a probability of 1.0 for all simulants in the state.

  • triggered (Trigger) – A flag indicating whether this transition is triggered by some event.

Return type:

Transition

allow_self_transitions()[source]
Return type:

None

transition_side_effect(index, event_time)[source]
Parameters:

  • index (pd.Index[int])

  • event_time (ClockTime)

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, initialization_weights=0.0)[source]
Parameters:

  • state_id (str)

  • allow_self_transition (bool)

  • initialization_weights (DataInput)

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

A container for state machine transitions.

Parameters:
state_id

The unique name of the state that instantiated this TransitionSet. Typically a string but any object implementing __str__ will do.

allow_null_transition

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

transitions

A list of transitions that can be taken from this state.

random

The randomness stream.

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 name of the component.

Return type:

str

setup(builder)[source]

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

Return type:

None

Parameters:

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

choose_new_state(index)[source]

Chooses a new state for each simulant in the index.

Parameters:

index (pd.Index[int]) – An iterable of integer labels for the simulants.

Returns:

A tuple of the possible end states of this set of transitions and a series containing the name of the next state for each simulant in the index.

Return type:

tuple[list[State | str], pd.Series[Any]]

append(transition)[source]
Return type:

None

Parameters:

transition (Transition)

extend(transitions)[source]
Return type:

None

Parameters:

transitions (Iterable[Transition])

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

A collection of states and transitions between those states.

Parameters:

  • state_column (str)

  • states (Iterable[State])

  • initial_state (State | None)

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: Sequence[Component]

Provide components managed by this component.

Returns:

The sub-components that are managed by this component.

Return type:

List[Component]

property columns_created: list[str]

Provides names of columns created by the component.

Returns:

  • Names of the columns created by this component, or an empty list if

  • none.

property initialization_requirements: list[str | Resource]

A list containing the columns, pipelines, and randomness streams required by this component’s simulant initializer.

setup(builder)[source]

Defines custom actions this component needs to run during the setup lifecycle phase.

This method is intended to be overridden by subclasses to perform any necessary setup operations specific to the component. By default, it does nothing.

Return type:

None

Parameters:

builder (Builder) – The builder object used to set up the component.

on_initialize_simulants(pop_data)[source]

Method that vivarium will run during simulant initialization.

This method is intended to be overridden by subclasses if there are operations they need to perform specifically during the simulant initialization phase.

Return type:

None

Parameters:

pop_data (SimulantData) – The data associated with the simulants being initialized.

Return type:

None

on_time_step(event)[source]

Method that vivarium will run during the time_step event.

This method is intended to be overridden by subclasses if there are operations they need to perform specifically during the time_step event.

Return type:

None

Parameters:

event (Event) – The event object associated with the time_step event.

on_time_step_cleanup(event)[source]

Method that vivarium will run during the time_step__cleanup event.

This method is intended to be overridden by subclasses if there are operations they need to perform specifically during the time_step__cleanup event.

Return type:

None

Parameters:

event (Event) – The event object associated with the time_step__cleanup event.

add_states(states)[source]
Return type:

None

Parameters:

states (Iterable[State])

transition(index, event_time)[source]

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

Parameters:

  • index (pd.Index[int]) – An iterable of integer labels for the simulants.

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

Return type:

None

cleanup(index, event_time)[source]
Parameters:

  • index (pd.Index[int])

  • event_time (ClockTime)

Return type:

None

get_initialization_parameters()[source]

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

Return type:

dict[str, Any]

Returns:

The value of the state column.

Notes

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