Base Population

The BasePopulation component is the foundation of the public health population package. It is responsible for two distinct jobs: initializing new simulants with demographically consistent attributes, and aging them forward on each time step. A companion component, AgeOutSimulants, handles removing simulants that exceed a configured age threshold (via vivarium’s untracking mechanism).

Because vivarium itself is agnostic to the meaning of the columns in the state table, it is this component that gives simulants their demographic identity.

Initialization

When the framework’s simulant creator function triggers, BasePopulation’s initializer assigns each new simulant the following attributes:

age
sex
location
entrance_time
exit_time

The entrance_time marks when the simulant enters the simulation. The exit_time is initially set to pandas.NaT and is later updated by other components (e.g. Mortality) when the simulant leaves the simulation.

Demographic Sampling

The initializer loads population.structure data from the artifact and computes conditional sampling distributions with assign_demographic_proportions(). Three probability views are produced:

Quantity	Meaning
`P(sex, location, age\| year)`	Joint distribution used to draw simulant demographics for a given year.
`P(sex, location \| age, year)`	Conditional distribution used when a fixed initial age is specified.
`P(age \| year, sex, location)`	Conditional distribution used for smoothing ages within demographic strata.

Fixed Age vs. Age Range

Initialization supports two modes, determined by the values of age_start and age_end:

Fixed age (age_start == age_end): All simulants are placed in the single age bin containing that age, and then smoothed uniformly within the bin. Sex and location are drawn from P(sex, location | age, year).
Age range (age_start != age_end): The age distribution is clipped to the requested range, bins are selected probabilistically from P(sex, location, age| year), and ages are smoothed within the selected bins.

Both paths use the common random number framework through dedicated randomness streams so that initialization remains reproducible across simulation branches.

Scaled Population

ScaledPopulation extends the base initialization flow by multiplying the population structure by an external scaling factor before sampling. This is useful when the number of simulants in the model represents a known fraction of the true population size and downstream components (like crude-birth-rate fertility) need to reason about that relationship.

Time Step Behavior

On each time_step event, BasePopulation advances the age of every living simulant by the event’s step size. This update is deterministic and ensures all downstream components see a consistent age state within a single time step.

Aging Out and Untracking

AgeOutSimulants runs during time_step__cleanup. When population.untracking_age is configured, any simulant whose age meets or exceeds that threshold is marked and subsequently untracked by the framework. This provides a clean way to bound the active population for models focused on specific age windows.