Component

A base Component class to be used to create components for use in vivarium simulations.

vivarium.component.DEFAULT_EVENT_PRIORITY = 5

The default priority at which events will be triggered.

class vivarium.component.Component

The base class for all components used in a Vivarium simulation.

A Component in a Vivarium simulation represents a distinct feature or aspect of the model. It encapsulates the logic and data needed for that feature. Components commonly interact with the rest of the simulation by creating and updating columns in the state table, registering pipelines, and registering modifiers on pipelines created by other components. Observer components might also register observations. All components within a simulation must have a unique name, which is generated by default from the component’s class and the argument passed to its constructor.

The setup_component is run by Vivarium during the setup phase and performs a series of operations to prepare the component for the simulation. These operations include setting the logger for the component, calling the component’s custom setup method, setting the population view if the component needs one, and registering listeners for each lifecycle event if the component has defined a method to be triggered on that event.

Subclasses of Component should override these properties as needed:

• sub_components

• configuration_defaults

• columns_created

• columns_required

• initialization_requirements

• population_view_query

• post_setup_priority

• time_step_prepare_priority

• time_step_priority

• time_step_cleanup_priority

• collect_metrics_priority

• simulation_end_priority

Subclasses of Component should override these methods in order to have operations occur during the appropriate lifecycle phase of a simulation:

• setup

• on_post_setup

• on_initialize_simulants

• on_time_step_prepare

• on_time_step

• on_time_step_cleanup

• on_collect_metrics

• on_simulation_end

CONFIGURATION_DEFAULTS: Dict[str, Any] = {}

A dictionary containing the defaults for any configurations managed by this component. An empty dictionary indicates no managed configurations.

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

property sub_components: List[Component]

Provide components managed by this component.

Returns:

A list of components that are managed by this component.

Return type:

List[Component]

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 ConfigTree.

Returns:

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

Return type:

Dict[str, Any]

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.

Return type:

List[str]

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]]

property initialization_requirements: Dict[str, List[str]]

Provides the names of all values required by this component during simulant initialization.

Returns:

A dictionary containing the additional requirements of this component during simulant initialization. An omitted key or an empty list for a key implies no requirements for that key during initialization.

Return type:

Dict[str, List[str]]

property population_view_query: str | None

Provides a query to use when filtering the component’s PopulationView.

Returns:

A pandas query string for filtering the component’s PopulationView. Returns None if no filtering is required.

Return type:

Optional[str]

property post_setup_priority: int

Provides the priority of this component’s post_setup listener.

Returns:

The priority of this component’s post_setup listener. This value can range from 0 to 9, inclusive.

Return type:

int

property time_step_prepare_priority: int

Provides the priority of this component’s time_step__prepare listener.

Returns:

The priority of this component’s time_step__prepare listener. This value can range from 0 to 9, inclusive.

Return type:

int

property time_step_priority: int

Provides the priority of this component’s time_step listener.

Returns:

The priority of this component’s time_step listener. This value can range from 0 to 9, inclusive.

Return type:

int

property time_step_cleanup_priority: int

Provides the priority of this component’s time_step__cleanup listener.

Returns:

The priority of this component’s time_step__cleanup listener. This value can range from 0 to 9, inclusive.

Return type:

int

property collect_metrics_priority: int

Provides the priority of this component’s collect_metrics listener.

Returns:

The priority of this component’s collect_metrics listener. This value can range from 0 to 9, inclusive.

Return type:

int

property simulation_end_priority: int

Provides the priority of this component’s simulation_end listener.

Returns:

The priority of this component’s simulation_end listener. This value can range from 0 to 9, inclusive.

Return type:

int

setup_component(builder)

Sets up the component for a Vivarium simulation.

This method is run by Vivarium during the setup phase. It performs a series of operations to prepare the component for the simulation.

It sets the logger for the component, sets up the component, sets the population view, and registers various listeners including post_setup, simulant_initializer, time_step_prepare, time_step, time_step_cleanup, collect_metrics, and simulation_end listeners.

Parameters:

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

Return type:

None

setup(builder)

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.

Parameters:

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

Return type:

None

on_post_setup(event)

Method that vivarium will run during the post_setup event.

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

NOTE: This method is not commonly used functionality.

Parameters:

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

Return type:

None

on_initialize_simulants(pop_data)

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.

Parameters:

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

Return type:

None

on_time_step_prepare(event)

Method that vivarium will run during the time_step__prepare event.

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

Parameters:

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

Return type:

None

on_time_step(event)

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.

Parameters:

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

Return type:

None

on_time_step_cleanup(event)

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.

Parameters:

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

Return type:

None

on_collect_metrics(event)

Method that vivarium will run during the collect_metrics event.

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

Parameters:

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

Return type:

None

on_simulation_end(event)

Method that vivarium will run during the simulation_end event.

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

Parameters:

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

Return type:

None

get_initialization_parameters()

Retrieves the values of all parameters specified in the __init__ that have an attribute with the same name.

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.

Returns:

A dictionary where the keys are the names of the parameters used in the __init__ method and the values are their current values.

Return type:

dict