API reference

The library’s public API. All names listed here are importable directly from the top-level agent_urban_planning package (or its short alias aup):

import agent_urban_planning as aup

Core simulation

SimulationEngine(scenario, agent_config[, ...])	Orchestrate one end-to-end simulation: config to environment to market to metrics.
Environment(zones, transport[, ...])	Spatial environment holding zones and transportation network.
Zone(name, housing_supply, ...[, ...])	One geographic unit (planning area or block) in a scenario.
Agent(agent_id, household_size, age_head, ...)	One representative household type (a weighted demographic record).
AgentPopulation(agents)	Collection of weighted representative agent types.
PreferenceWeights(alpha, beta, gamma, delta)	Four-axis preference weights for an agent or archetype.
HousingMarket([price_elasticity, ...])	Elasticity-based tatonnement with adaptive damping and two-segment clearing.
AhlfeldtMarket(ahlfeldt_params[, ...])	Two-market tatonnement clearing Q (residential floor) AND w (wages).
MarketResult(prices, allocations, ...[, ...])	Equilibrium output of a HousingMarket or AhlfeldtMarket run.
WelfareMetrics(avg_utility, ...[, ...])	Aggregate welfare metrics summarizing one simulation run.
SimulationResults(metrics, agent_results[, ...])	Top-level container for one simulation run's output.
AgentResult(agent_id, weight, demographics, ...)	Per-agent record summarizing an agent's outcome in one run.
RunMetadata([run_id, timestamp, ...])	Reproducibility metadata for a single simulation run.

persona_summary(agent)	Produce a stable, human-readable one-line persona from an agent's demographics.
compute_metrics(population, environment, ...)	Compute aggregate welfare metrics from per-agent allocations.

Decision engines (public API)

The three first-class decision-engine classes — configurable via constructor kwargs to reproduce V1-V5 from the paper:

DecisionEngine(*args, **kwargs)	Protocol every decision engine implements.
UtilityEngine(params, *[, mode, noise])	Closed-form Cobb-Douglas + Fréchet utility decision engine.
HybridDecisionEngine(params[, elicitor, ...])	LLM-elicited preferences + closed-form mixed-logit choice (V4).
LLMDecisionEngine(params, llm_client, *[, ...])	Full LLM-as-decision-maker hierarchical engine (V5).
LocationChoice(residence, workplace, utility)	An agent's chosen (residence, workplace) pair plus diagnostic utilities.
ZoneChoice([zone_name, utility, ...])	Backward-compatible alias for LocationChoice.

Decision engines (paper-internal — advanced)

The underlying paper-internal classes that the public API delegates to. Most users should not need to import these directly.

AhlfeldtUtilityEngine(params[, seed, ...])	Cobb-Douglas + Fréchet joint residence-workplace decision engine.
AhlfeldtABMEngine(params, *[, ...])	Monte Carlo argmax decision engine with configurable shock distribution.
AhlfeldtArgmaxHybridEngine(params[, ...])	Pure argmax with LLM-elicited per-type beta_k / kappa_k preferences.
AhlfeldtHierarchicalLLMEngine(params, ...[, ...])	LLM-as-decision-maker engine with clustering and two-stage prompts.