agent_urban_planning.AgentPopulation

class AgentPopulation(agents)

Bases: object

Collection of weighted representative agent types.

Holds the full list of Agent instances comprising the simulation’s population, indexed by integer position. Each agent carries a weight that represents its population share; weights must sum to 1.0 across the population. Construct via from_config() from a parsed agent YAML, which handles distributional sampling (per-zone Census or single national) or explicit per-agent records.

Parameters:

agents (list[Agent]) – List of Agent instances. The constructor validates that their weights sum to 1.0 within tolerance.

Raises:

ValueError – If agents weights do not sum to 1 within 1e-6.

Examples

>>> import agent_urban_planning as aup
>>> # config = aup.data.builtin.load_agents("singapore_real_v2")
>>> # pop = aup.AgentPopulation.from_config(config)
>>> # len(pop)  # number of representative types
>>> # for agent in pop:
>>> #     ... # iterate over the population

classmethod from_config(config, rng=None, strict=True)

Generate an agent population from a configuration object.

Dispatches on config.mode: "distributional" samples agents from per-zone Census distributions (or, for unit-test configs with strict=False, a single national distribution), otherwise loads explicitly declared agent records.

Parameters:

• config (AgentDistributionalConfig) – Parsed AgentDistributionalConfig from a YAML file.

• rng (Optional[RandomState]) – Optional numpy.random.RandomState for reproducible sampling. If None, a fresh state is created.

• strict (bool) – If True (default), reject configs without per-zone Census data. Set to False only in unit tests that use small synthetic configs.

Return type:

AgentPopulation

Returns:

A new AgentPopulation. Weights are normalized to sum to 1.

Raises:

RuntimeError – When strict=True and the config lacks per-zone zone_distributions.

Examples

>>> import agent_urban_planning as aup
>>> # config = aup.data.builtin.load_agents("singapore_real_v2")
>>> # pop = aup.AgentPopulation.from_config(config, strict=True)