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() method 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

• 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_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. Components will look for a data_sources block in this dictionary to build lookup tables automatically.

property name: str

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.

property logger: loguru.Logger

The logger for this component.

Raises:

LifeCycleError – If the logger has not been initialized.

property population_view: PopulationView

The PopulationView for this component.

Raises:

PopulationError – If the component does not have access to the state table.

property private_columns: list[str]

The list of private columns created by this component.

property sub_components: Sequence[Component]

The components managed by this component.

property configuration_defaults: dict[str, Any]

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

property lookup_table_value_columns: dict[str, str | list[str]]

A mapping of lookup table names to their value columns.

property post_setup_priority: int

The priority of this component’s post_setup listener.

property time_step_prepare_priority: int

The priority of this component’s time_step__prepare listener.

property time_step_priority: int

The priority of this component’s time_step listener.

property time_step_cleanup_priority: int

The priority of this component’s time_step__cleanup listener.

property collect_metrics_priority: int

The priority of this component’s collect_metrics listener.

property simulation_end_priority: int

The priority of this component’s simulation_end listener.

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.

Return type:

None

Parameters:

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

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.

Return type:

None

Parameters:

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

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.

Return type:

None

Parameters:

event (Event)

Notes

This method is not commonly used functionality.

Parameters:

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

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.

Return type:

None

Parameters:

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

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.

Return type:

None

Parameters:

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

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.

Return type:

None

Parameters:

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

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.

Return type:

None

Parameters:

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

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.

Return type:

None

Parameters:

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

get_initialization_parameters()

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

Return type:

dict[str, Any]

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.

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[str, Any]

get_configuration(builder)

Retrieves the configuration for this component from the builder.

This method retrieves the configuration for this component from the simulation’s overall configuration. The configuration is retrieved using the name of the component as the key.

Return type:

LayeredConfigTree

Parameters:

builder (Builder) – The simulation’s builder object.

Returns:

The configuration for this component, or a default empty configuration.

build_lookup_table(builder, name, data_source=None, value_columns=None)

Builds a LookupTable.

If a data_source is not provided, the method will look for a data source in the component’s configuration under the key “data_sources” with the provided name.

If value_columns provided is a list or tuple, a LookupTable returning a DataFrame will be built. If it is a string or None, a LookupTable returning a Series will be built. If value_columns is None, the name of the returned Series will be “value”.

Parameters:

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

• data_source (DataInput | None) – The data source to build the LookupTable from. If None, the data source will be retrieved from the component’s configuration.

• name (str) – The name of the lookup table, used to retrieve the data source from the configuration if data_source is None.

• value_columns (list[str] | tuple[str, ...] | str | None) – The columns to include in the LookupTable.

Returns:

The LookupTable built from the data source.

Raises:

layered_config_tree.exceptions.ConfigurationError – If the data source is invalid.

Return type:

LookupTable[pd.Series[Any]] | LookupTable[pd.DataFrame]

get_data(builder, data_source)

Retrieves data from a data source.

If the data source is a float or a DataFrame, it is treated as the data itself. If the data source is a string, containing the substring ‘::’, it is treated as a function to call to retrieve the data. The string to the left of ‘::’ is the module to import, and the string to the right is the function to call. ‘self’ can be provided to the left of ‘::’ to call a method on the component itself. If the data source is a string without the substring ‘::’, it is treated as a key in the artifact.

Return type:

SupportsFloat | Timedelta | timedelta | Timestamp | datetime | DataFrame | list[SupportsFloat | Timedelta | timedelta | Timestamp | datetime] | tuple[SupportsFloat | Timedelta | timedelta | Timestamp | datetime, ...] | Mapping[str, list[SupportsFloat | Timedelta | timedelta | Timestamp | datetime] | list[str]]

Parameters:

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

• data_source (SupportsFloat | Timedelta | timedelta | Timestamp | datetime | DataFrame | list[SupportsFloat | Timedelta | timedelta | Timestamp | datetime] | tuple[SupportsFloat | Timedelta | timedelta | Timestamp | datetime, ...] | Mapping[str, list[SupportsFloat | Timedelta | timedelta | Timestamp | datetime] | list[str]] | str | Callable[[Builder], SupportsFloat | Timedelta | timedelta | Timestamp | datetime | DataFrame | list[SupportsFloat | Timedelta | timedelta | Timestamp | datetime] | tuple[SupportsFloat | Timedelta | timedelta | Timestamp | datetime, ...] | Mapping[str, list[SupportsFloat | Timedelta | timedelta | Timestamp | datetime] | list[str]]]) – The data source to retrieve data from.

Returns:

The data retrieved from the data source.

Raises:

layered_config_tree.exceptions.ConfigurationError – If the data source is invalid.