agent_urban_planning.LocationChoice¶

class LocationChoice(residence, workplace, utility, zone_utilities=<factory>)[source]¶

Bases: object

An agent’s chosen (residence, workplace) pair plus diagnostic utilities.

The canonical output of any DecisionEngine. For Singapore-style scenarios where workplace is fixed as an agent attribute, workplace is set to agent.job_location; for Berlin-style scenarios where workplace is a genuine choice output, it reflects the engine’s decision. The diagnostic zone_utilities mapping supports both flat (single-zone) and namespaced (joint R/W) layouts.

Variables:

residence – Zone ID where the agent lives (their chosen residence).
workplace – Zone ID where the agent works. For Singapore-style scenarios equals agent.job_location; for Berlin-style scenarios it is a genuine choice output.
utility – Realized utility at the chosen pair.
zone_utilities – Per-zone diagnostic utilities. In single-zone engines, keys are residence zone IDs. In joint-choice engines, keys may optionally be namespaced "R:<zone>" / "W:<zone>".

Parameters:

residence (str)
workplace (str)
utility (float)
zone_utilities (dict[str, float])

Examples

>>> from agent_urban_planning import LocationChoice
>>> choice = LocationChoice(
...     residence="Mitte",
...     workplace="Charlottenburg",
...     utility=2.71,
...     zone_utilities={"R:Mitte": 1.4, "W:Charlottenburg": 1.31},
... )
>>> choice.zone_name  # backward-compat alias for residence
'Mitte'

residence: str¶

workplace: str¶

utility: float¶

zone_utilities: dict[str, float]¶

property zone_name: str¶

Backward-compatible alias for residence.

Existing code that reads choice.zone_name continues to work against the new dataclass. Prefer residence in new code.