agent_urban_planning.compute_metrics

compute_metrics(population, environment, allocations, prices, long_commute_threshold=60.0, affordability_threshold=0.3, market_converged=True, market_convergence_metric=0.0, wages=None)[source]

Compute aggregate welfare metrics from per-agent allocations.

Walks the population, looks up each agent’s chosen zone and route, and aggregates weighted means, the Gini coefficient, Rawlsian extremes, commute statistics, affordability share, facility utilization, and per-zone population/employment/wage tables.

Parameters:

  • population (AgentPopulation) – The simulated AgentPopulation.

  • environment (Environment) – The Environment used by the simulation.

  • allocations (dict[int, ZoneChoice]) – Dict mapping agent_id to the ZoneChoice produced by the market clearer.

  • prices (dict[str, float]) – Mapping zone -> equilibrium price.

  • long_commute_threshold (float) – Minutes threshold for the long_commute_share indicator. Defaults to 60.0.

  • affordability_threshold (float) – Price/income ratio above which an agent’s housing counts as unaffordable. Defaults to 0.30.

  • market_converged (bool) – Whether the upstream market clearer reached convergence. Recorded in the result.

  • market_convergence_metric (float) – Final residual to record.

  • wages (Optional[dict[str, float]]) – Optional zone -> wage mapping (Ahlfeldt scenarios).

Return type:

WelfareMetrics

Returns:

A WelfareMetrics describing the run’s welfare outcome.

Examples

>>> import agent_urban_planning as aup
>>> # metrics = aup.compute_metrics(population, env, allocations, prices)
>>> # metrics.gini_coefficient