agent_urban_planning.AgentResult

class AgentResult(agent_id, weight, demographics, preferences, zone_utilities, zone_choice, equilibrium_price, commute_minutes, realized_utility, utility_vs_baseline=None, residence_zone='', workplace_zone='')[source]

Bases: object

Per-agent record summarizing an agent’s outcome in one run.

Captures the agent’s demographics, declared preferences, the zone-by-zone utilities seen at equilibrium, the realized choice and utility, the commute time, and (when a baseline is provided) the welfare difference relative to that baseline. Both the legacy zone_choice field and the explicit residence_zone/workplace_zone pair are populated; the legacy field equals residence_zone.

Variables:

  • agent_id – Stable agent identifier.

  • weight – Population share assigned to this type.

  • demographics – Flattened demographic snapshot (income, household size, etc.).

  • preferences – Dict with keys alpha, beta, gamma, delta reflecting the agent’s recorded preference weights.

  • zone_utilities – Per-zone utility evaluations.

  • zone_choice – Residence zone (legacy alias for residence_zone).

  • equilibrium_price – Price paid at the chosen residence zone.

  • commute_minutes – Realized commute time between residence and workplace.

  • realized_utility – Utility at the chosen pair.

  • utility_vs_baseline – Realized utility minus a baseline run’s utility, when a baseline is supplied. None otherwise.

  • residence_zone – Residence zone (matches zone_choice).

  • workplace_zone – Workplace zone. For Singapore scenarios equals demographics['job_location']; for Berlin scenarios this is the engine’s joint-choice output.

Parameters:

Examples

>>> import agent_urban_planning as aup
>>> # Returned in SimulationResults.agent_results; see SimulationEngine.run().
agent_id: int
weight: float
demographics: dict[str, Any]
preferences: dict[str, float]
zone_utilities: dict[str, float]
zone_choice: str
equilibrium_price: float
commute_minutes: float
realized_utility: float
utility_vs_baseline: float | None = None
residence_zone: str = ''
workplace_zone: str = ''
classmethod from_agent(agent, zone_utilities, zone_choice, equilibrium_price, commute_minutes, realized_utility, utility_vs_baseline=None, workplace_zone=None)[source]

Build an AgentResult from an Agent plus market output.

Convenience constructor that flattens the agent’s demographics and preferences into JSON-friendly dicts and fills in the residence/workplace fields from zone_choice and either an explicit workplace_zone or agent.job_location.

Parameters:

  • agent (Agent) – Source Agent whose demographics are snapshotted.

  • zone_utilities (dict[str, float]) – Per-zone utility evaluations as seen by the agent at the equilibrium prices.

  • zone_choice (str) – The agent’s chosen residence zone.

  • equilibrium_price (float) – Equilibrium price at the chosen zone.

  • commute_minutes (float) – Realized commute time.

  • realized_utility (float) – Utility at the chosen residence and workplace.

  • utility_vs_baseline (Optional[float]) – Optional difference vs. a baseline run.

  • workplace_zone (Optional[str]) – Optional workplace zone override; defaults to agent.job_location.

Return type:

AgentResult

Returns:

A new AgentResult populated from the inputs.

Examples

>>> import agent_urban_planning as aup
>>> # Used internally by SimulationEngine.run() — see that method.