HABM: Human-like Agent-Based Modeling for Urban Planning

Proof-of-concept implementation for "Believable Urban Planning via Large Language Model-enabled Behavior Modeling: A Conceptual Framework"

Overview

This repository provides an illustrative demonstration of the Human-like Agent-Based Modeling (HABM) framework, which integrates Large Language Models (LLMs) with agent-based simulation to produce behaviorally authentic urban policy evaluation.

The demo implements a transportation policy scenario in Mingcheng, a fictional mid-sized Chinese city, where five resident agents with diverse sociodemographic profiles respond to parking fee increases and a new metro line across four simulation rounds.

What this demo demonstrates

HABM Component	Implementation
Agent initialization	Structured attributes (age, income, commute) + unstructured narrative (personal history, values)
TPB integration	Attitudes, subjective norms, and perceived behavioral control encoded in each agent's persona
Cognitive modules	Perception → Memory → Reflection → Planning, following the architecture in Section 3
Multi-round simulation	4 rounds: independent baseline → social influence → policy shock → post-reflection
Believability metrics	9 quantitative metrics across consistency, robustness, and adaptability (Table 1)
Ablation experiment	With vs. without reflection module
Rule-ABM comparison	HABM vs. traditional heuristic-based ABM (Algorithm 1)
Monte Carlo analysis	N=5 independent runs for cross-run reproducibility

Agents

Agent	Age	Occupation	Current mode	Role in simulation
Chen Wei	38	Software engineer	Private car	"Swing" user — may transition to metro
Liu Meiling	29	Freelance designer	Metro + bike	Committed transit user — baseline control
Zhang Guoqiang	55	Logistics company owner	Private car	Functionally constrained — rigidity test
Wang Lili	67	Retired teacher	Bus + walking	Elderly/accessibility — equity dimension
Hao Peng	24	Graduate student	Bus	Expectation-reality gap — attitude dynamics

Quick start

1. Clone and install

git clone https://github.com/Fe6ruAr9-pku/habm-demo.git
cd habm-demo
pip install -r requirements.txt

2. Configure API key

The demo uses an OpenAI-compatible API. It has been tested with Alibaba Cloud Bailian (Qwen models) but is compatible with any OpenAI-compatible endpoint.

# Option A: Environment variable (recommended)
export HABM_API_KEY='your-api-key-here'

# Option B: Copy and edit .env.example
cp .env.example .env
# Edit .env with your API key

Supported providers:

Provider	BASE_URL	Tested models
Alibaba Cloud (default)	https://dashscope.aliyuncs.com/compatible-mode/v1	qwen-plus, qwen-max
OpenAI	https://api.openai.com/v1	gpt-4o, gpt-4o-mini
DeepSeek	https://api.deepseek.com/v1	deepseek-chat

To use a different provider:

export HABM_BASE_URL='https://api.openai.com/v1'
export HABM_MODEL='gpt-4o-mini'

3. Run

# Full pipeline: single run + Monte Carlo (N=5) + ablation + Rule-ABM comparison
# Estimated time: 2-3 hours | API calls: ~296
python habm_transport_demo.py --mode full

# Single run only (~30 minutes | ~37 API calls)
python habm_transport_demo.py --mode single

# Rule-ABM comparison (single run + deterministic comparison)
python habm_transport_demo.py --mode rule_abm

# Monte Carlo only (5 independent runs)
python habm_transport_demo.py --mode monte_carlo --mc-runs 5

# Ablation only (with vs. without reflection)
python habm_transport_demo.py --mode ablation

Output

Each run produces a JSON file containing:

habm_demo_results.json          # Single-run results (default)
habm_full_analysis.json         # Full pipeline (--mode full)
habm_monte_carlo_results.json   # Monte Carlo best run
habm_ablation_full.json         # Ablation condition A
habm_ablation_noreflect.json    # Ablation condition B

Output structure

{
  "primary_run": {
    "results": {
      "Chen Wei": {
        "decisions": [
          {"round": 1, "chosen_mode": "metro", "confidence": 0.75, "attitude_score": 3, "reasoning": "..."},
          ...
        ],
        "reflection": "...",
        "plan": {"short_term_plan": "...", "medium_term_plan": "...", "desired_policy_change": "..."}
      },
      ...
    },
    "metrics": {
      "Chen Wei": {"C1_behavior_prompt_similarity": 0.206, "C2_rule_violation_rate": 0.0, ...},
      ...
    }
  },
  "monte_carlo": {"n_runs": 5, "convergence": {...}},
  "ablation": {"comparison": {...}},
  "rule_abm_comparison": {...}
}

Simulation design

Round 1 ──────── Round 2 ──────── Round 3 ──────── Reflect ──────── Round 4
Baseline         Social            Policy shock      Memory            Post-
(independent)    (community        (CNY 25/hr +      consolidation     reflection
                  meeting)          construction)                       decision

  Perception ──→ Decision ──→ Memory ──→ Reflection ──→ Planning
       ↑              ↑           ↑            ↑             ↑
    [Environment]  [TPB]      [Episodic]   [Insight]     [12-month
                                 log       generation      plan]

Believability metrics (Table 1)

Dimension	Metric	Code
Consistency	Behavior-Prompt Similarity	C1
	Rule Violation Rate	C2
	Memory-Behavior Coherence	C3
Robustness	Stability Under Perturbation	R1
	Decision Entropy	R2
	Outcome Variance	R3
Adaptability	Reaction Latency	A1
	Strategy Switch Count	A2
	Learning Impact Index	A3

Project structure

habm-demo/
├── habm_transport_demo.py    # Main simulation script (single file, ~1,740 lines)
├── requirements.txt          # Python dependencies
├── .env.example              # API configuration template
├── .gitignore
├── README.md
└── docs/
    └── habm_simulation.gif   # Animated demo (R1→R4 progression)

Key design decisions

Why a single file? The demo is designed for reproducibility and ease of review. All components (agent personas, environment, simulation logic, metrics, experiments) are contained in one self-documenting Python file with clear section headers. This mirrors the "structured demonstration" framing in Section 4 of the paper.

Why Qwen? The demo uses Alibaba Cloud's Qwen models via an OpenAI-compatible API. Any model supporting the OpenAI chat completions format can be substituted by changing the environment variables. Note: models with <think> tag outputs (e.g., Qwen3.5-Plus reasoning mode) require enable_thinking: False in the API call to prevent JSON parsing failures.

Why 5 agents? The five agents were selected through purposive sampling to represent distinct segments of the urban commuter population (Yin, 2018): car-dependent professionals, flexible transit users, logistics operators, elderly residents, and low-income students.

License

This project is released for academic and research purposes. See LICENSE for details.