Population Manager

class vivarium.framework.population.manager.SimulantData(index, user_data, creation_time, creation_window)

Data to help components initialize simulants.

Any time simulants are added to the simulation, each initializer is called with this structure containing information relevant to their initialization.

Parameters:

• index (pd.Index[int])

• user_data (dict[str, Any])

• creation_time (ClockTime)

• creation_window (ClockStepSize)

index: pd.Index[int]

The index representing the new simulants being added to the simulation.

user_data: dict[str, Any]

A dictionary of extra data passed in by the component creating the population.

creation_time: ClockTime

The time when the simulants enter the simulation.

creation_window: ClockStepSize

The span of time over which the simulants are created. Useful for, e.g., distributing ages over the window.

class vivarium.framework.population.manager.PopulationManager

Manages the population state table.

CONFIGURATION_DEFAULTS: dict[str, Any] = {'population': {'population_size': 100}}

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

property name: str

The name of this component.

property private_columns: DataFrame

The dataframe of all population private columns.

Notes

Critically, the private columns dataframe not only contains all private columns created for the simulation, but also serves as the simulant index for the entire population. Even if no private columns are created, this dataframe will exist and all simulants will be represented by its index.

setup(builder)

Registers the population manager with other vivarium systems.

Return type:

None

Parameters:

builder (Builder)

on_post_setup(event)

Return type:

None

Parameters:

event (Event)

register_tracked_query(query)

Updates list of registered tracked queries with the provided query.

Return type:

None

Parameters:

query (str) – The new query to add to the running list of tracked queries.

Notes

While we log a warning if the same query is registered multiple times, we make no attempt to de-duplicate functionally-equivalent queries that are syntactically different, e.g. “x > 5” and “5 < x”. In such cases, duplicate queries will be applied which is not optimal but will not affect correctness.

get_private_column_names(component_name)

Gets the names of private columns created by a given component.

Return type:

list[str]

Parameters:

component_name (str) – The name of the component whose private column names are to be retrieved.

Returns:

The list of private column names created by the specified component. If the component has not created any private columns, an empty list is returned.

get_private_columns(component, index=None, columns=None)

Gets the private columns for a given component.

While the private_columns property provides a dataframe of all private columns in population, this method returns only the private columns created by the specified component. If no component is specified, then no columns are returned.

Parameters:

• component (Component | Manager) – The component whose private columns are to be retrieved. If None, no columns are returned.

• index (pd.Index[int] | None) – The index of simulants to include in the returned dataframe. If None, all simulants are included.

• columns (str | list[str] | tuple[str, ...] | None) – The specific column(s) to include. If None, all columns created by the component are included.

Raises:

PopulationError – If columns are requested during initial population creation (when no columns yet exist) or if the provided component does not create one or more of them.

Returns:

The private column(s) created by the specified component. Will return a Series if a single column is requested or a Dataframe otherwise.

Return type:

pd.DataFrame | pd.Series[Any]

get_population_index()

Gets the index of the current population.

Return type:

pd.Index[int]

get_view(component=None)

Gets a time-varying view of the population state table.

The requested population view can be used to view the current state or to update the state with new values.

Return type:

PopulationView

Parameters:

component (Component | None) – The component requesting this view. If None, the view will provide read-only access.

Returns:

A view of the requested private columns of the population state table.

get_simulant_creator()

Gets a function that can generate new simulants.

The creator function takes the number of simulants to be created as its first argument and a population configuration dict that will be available to simulant initializers as its second argument. It generates the new rows in the population state table and then calls each initializer registered with the population system with a data object containing the state table index of the new simulants, the configuration info passed to the creator, the current simulation time, and the size of the next time step.

Returns:

The simulant creator function.

Return type:

Callable[[int, dict[str, Any] | None], pd.Index[int]]

register_initializer(initializer, columns, required_resources=())

Registers a component’s initializers and any (private) columns created by them.

This does three primary things: 1. Registers each private column’s corresponding attribute producer. 2. Records metadata about which component created which private columns. 3. Registers the initializer as a resource.

A columns value of None indicates that no private columns are being registered. This is useful when a component or manager needs to register an initializer that does not create any private columns.

Return type:

None

Parameters:

• initializer (Callable[[SimulantData], None]) – A function that will be called to initialize the state of new simulants.

• columns (str | Sequence[str] | None) – The private columns that the given initializer provides the initial state information for.

• required_resources (Sequence[str | Resource]) – The resources that the initializer requires to run. Strings are interpreted as attributes.

Raises:

PopulationError – If this initializer has already been registered or if the columns being created by this initializer overlap with columns created by another initializer.

get_all_attribute_names()

Gets the names of all attributes in the population.

Return type:

list[str]

Returns:

A list of all attribute names in the population.

get_population(attributes, index=None, query='', squeeze=True, mode='default')

Provides a copy of the population state table.

Parameters:

• attributes (list[str] | tuple[str, ...] | Literal['all']) – The attributes to include as the state table. If “all”, all attributes are included.

• index (pd.Index[int] | None) – The index of simulants to include in the returned population. If None, all simulants are included.

• query (str) – Additional conditions used to filter the index.

• squeeze (Literal[True, False]) – Whether or not to attempt to squeeze a multi-level column into a single-level column and/or a single-column dataframe into a series.

• mode (Literal['default', 'source', 'no-post-processors']) – The mode for pipeline evaluation. One of “default”, “source”, or “no-post-processors”.

Return type:

Any

Notes

If mode is not “default”, the returned data will not be squeezed regardless of the squeeze argument passed.

Returns:

A copy of the population state table.

Raises:

• TypeError – If attributes is not a list or tuple of strings or “all”.

• PopulationError –

  • If any of the requested attributes do not exist in the state table. - If a required column for querying is missing from the state table. - If the population has not yet been initialized.

• ValueError – If multiple attributes are requested when mode is not “default”.

Parameters:

• attributes (list[str] | tuple[str, ...] | Literal['all'])

• index (pd.Index[int] | None)

• query (str)

• squeeze (Literal[True, False])

• mode (Literal['default', 'source', 'no-post-processors'])

Return type:

Any

get_tracked_query()

Gets the combined tracked query for the population.

Return type:

str

Returns:

A query string combining all registered tracked queries with “and” operators.

update(update)

Return type:

None

Parameters:

update (DataFrame)