agent_urban_planning.SimulationResults¶

class SimulationResults(metrics, agent_results, policy_name='', scenario_name='', price_history=None, metadata=None)[source]¶

Bases: object

Top-level container for one simulation run’s output.

Aggregates the population-level WelfareMetrics, the list of per-agent AgentResult records, the price-history trajectory, and the run RunMetadata. Returned by SimulationEngine.run() and used directly by analysis utilities such as agent_urban_planning.analysis() plotting helpers.

Parameters:

metrics (WelfareMetrics) – Welfare metrics for the run.
agent_results (list[AgentResult]) – Per-agent records.
policy_name (str) – Name of the policy that produced this run.
scenario_name (str) – Name of the scenario.
price_history (Optional[list[dict]]) – Optional list of per-iteration market snapshots.
metadata (Optional[RunMetadata]) – Optional RunMetadata with reproducibility info (LLM provider/model, seed, cluster config, etc.).

Examples

>>> import agent_urban_planning as aup
>>> # results = sim.run(policy)
>>> # results.metrics.avg_utility
>>> # results.get_agent(0).realized_utility

get_agent(agent_id)[source]¶

Look up the per-agent result record by id.

Parameters:: agent_id (int) – Stable integer identifier of the agent.
Return type:: AgentResult
Returns:: The AgentResult for that agent.
Raises:: KeyError – If agent_id is not in the population.

Examples

>>> import agent_urban_planning as aup
>>> # results.get_agent(0).realized_utility

filter_agents(**criteria)[source]¶

Filter agent results by demographic criteria.

Returns the subset of AgentResult records matching all of the supplied filter criteria. Useful for cohort-level analyses (e.g. “results for households with children”).

Parameters:

**criteria –

Keyword filters. Supported keys:

has_children (bool)
has_elderly (bool)
car_owner (bool)
income_min / income_max (float)
age_min / age_max (int)
zone_choice (str)
job_location (str)

Return type:

list[AgentResult]

Returns:

List of AgentResult records satisfying every criterion. Empty when no agent matches.

Raises:

ValueError – If an unsupported criterion key is supplied.

Examples

>>> import agent_urban_planning as aup
>>> # families = results.filter_agents(has_children=True)
>>> # high_income = results.filter_agents(income_min=10000)

to_dict()[source]¶

Return a JSON-serializable dict representation of this run.

Return type:: dict
Returns:: dict with keys policy_name, scenario_name, metrics, agent_results, price_history, and metadata.

Examples

>>> import agent_urban_planning as aup
>>> # d = results.to_dict()
>>> # list(d)
['policy_name', 'scenario_name', 'metrics', 'agent_results',
 'price_history', 'metadata']

to_json()[source]¶

Serialize this run to an indented JSON string.

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

Examples

>>> import agent_urban_planning as aup
>>> # path.write_text(results.to_json())

classmethod from_json(json_str)[source]¶

Reconstruct a SimulationResults from its JSON form.

Parameters:: json_str (str) – JSON string previously produced by to_json().
Return type:: SimulationResults
Returns:: The deserialized SimulationResults.

Examples

>>> import agent_urban_planning as aup
>>> # restored = aup.SimulationResults.from_json(path.read_text())