agent_urban_planning.WelfareMetrics¶

class WelfareMetrics(avg_utility, gini_coefficient, min_utility, max_utility, avg_commute_minutes, long_commute_share, housing_unaffordable_share, zone_populations, zone_prices, facility_utilization=<factory>, market_converged=True, market_convergence_metric=0.0, zone_employment=<factory>, zone_wages=<factory>)[source]¶

Bases: object

Aggregate welfare metrics summarizing one simulation run.

Captures both classical welfare measures (average utility, weighted Gini, Rawlsian min/max) and the planning-relevant indicators (commute times, housing affordability, facility utilization, zone-level population, employment, wages, prices). Populated by compute_metrics() from market output.

Variables:

avg_utility – Population-weighted mean utility.
gini_coefficient – Weighted Gini coefficient of utility values (0 = perfect equality, 1 = perfect inequality). Negative utilities are shifted to non-negative before computation.
min_utility – Smallest realized utility (Rawlsian floor).
max_utility – Largest realized utility.
avg_commute_minutes – Weighted mean commute time.
long_commute_share – Share of population with commute exceeding long_commute_threshold minutes.
housing_unaffordable_share – Share of population whose price/income ratio exceeds affordability_threshold.
zone_populations – Mapping zone -> share of total population keyed by residence zone.
zone_prices – Mapping zone -> equilibrium price.
facility_utilization – Per-facility utilization (demand / capacity) records.
market_converged – Whether the market clearer reached convergence.
market_convergence_metric – Final residual at termination.
zone_employment – Mapping zone -> share keyed by workplace.
zone_wages – Mapping zone -> wage (Ahlfeldt scenarios only).

Parameters:

avg_utility (float)
gini_coefficient (float)
min_utility (float)
max_utility (float)
avg_commute_minutes (float)
long_commute_share (float)
housing_unaffordable_share (float)
zone_populations (dict[str, float])
zone_prices (dict[str, float])
facility_utilization (list[FacilityUtilization])
market_converged (bool)
market_convergence_metric (float)
zone_employment (dict[str, float])
zone_wages (dict[str, float])

Examples

>>> import agent_urban_planning as aup
>>> # Typically created by aup.compute_metrics(); see the quickstart tutorial.
>>> # results.metrics.avg_utility

avg_utility: float¶

gini_coefficient: float¶

min_utility: float¶

max_utility: float¶

avg_commute_minutes: float¶

long_commute_share: float¶

housing_unaffordable_share: float¶

zone_populations: dict[str, float]¶

zone_prices: dict[str, float]¶

facility_utilization: list[FacilityUtilization]¶

market_converged: bool = True¶

market_convergence_metric: float = 0.0¶

zone_employment: dict[str, float]¶

zone_wages: dict[str, float]¶

to_dict()[source]¶

Return a JSON-serializable dict copy of every field.

Return type:: dict
Returns:: Plain dict produced by dataclasses.asdict().

Examples

>>> from agent_urban_planning.core.metrics import WelfareMetrics
>>> m = WelfareMetrics(
...     avg_utility=1.0, gini_coefficient=0.2, min_utility=0.0,
...     max_utility=2.0, avg_commute_minutes=20.0,
...     long_commute_share=0.1, housing_unaffordable_share=0.05,
...     zone_populations={}, zone_prices={},
... )
>>> m.to_dict()["avg_utility"]
1.0

to_json()[source]¶

Serialize to a pretty-printed JSON string.

Return type:: str
Returns:: Indented JSON string suitable for writing to disk.

Examples

>>> from agent_urban_planning.core.metrics import WelfareMetrics
>>> m = WelfareMetrics(
...     avg_utility=1.0, gini_coefficient=0.2, min_utility=0.0,
...     max_utility=2.0, avg_commute_minutes=20.0,
...     long_commute_share=0.1, housing_unaffordable_share=0.05,
...     zone_populations={}, zone_prices={},
... )
>>> "avg_utility" in m.to_json()
True

classmethod from_dict(data)[source]¶

Reconstruct a WelfareMetrics from its serialized dict.

Parameters:: data (dict) – Dict shaped like the output of to_dict().
Return type:: WelfareMetrics
Returns:: A WelfareMetrics instance with facility_utilization records re-hydrated from their dict form.

Examples

>>> from agent_urban_planning.core.metrics import WelfareMetrics
>>> m = WelfareMetrics(
...     avg_utility=1.0, gini_coefficient=0.2, min_utility=0.0,
...     max_utility=2.0, avg_commute_minutes=20.0,
...     long_commute_share=0.1, housing_unaffordable_share=0.05,
...     zone_populations={}, zone_prices={},
... )
>>> WelfareMetrics.from_dict(m.to_dict()).avg_utility
1.0