Urban Multi-domain Integrated Dynamics — a knowledge-enhanced cross-domain tool for urban ecological environment evaluation and design integration.

UrbanMind represents thermal, atmospheric, building-energy, and vegetation states on a shared heterogeneous graph, grounds scenario responses in curated physical constraints and intervention evidence (KRCG: knowledge retrieval and constraint grounding), and links to Rhino/Grasshopper for synchronized parameter updates.

Companion code for the manuscript "From fragmented simulation to integrated assessment: A knowledge-enhanced cross-domain tool for urban ecological environment evaluation" (Building and Environment, under review).

Demo

Live session against the released backend: intervention sliders (canopy fraction, roof albedo) drive real model inference; the four domain fields, per-request latency, and the appended runs/demo_session.jsonl log lines update on every edit. The model here is the reference implementation trained on a synthetic city (demo/train_synthetic.py).

• Full video (web viewer + Rhino 8/Grasshopper integration): docs/media/urbanmind_demo_full.mp4
• Run it yourself: python demo/train_synthetic.py && python demo/serve_demo.py, then open http://127.0.0.1:8787
• Grasshopper client: paste gh_bridge/UrbanMind_GH_component.py into a Rhino 8 Python 3 Script component (see docs/grasshopper_recording.md)

The interactive case-study page (https://4kc328.csb.app/) is an interface mock-up with precomputed responses and is not connected to the model backend; runtimes displayed there are illustrative. Measured runtimes come from urbanmind/runtime/benchmark.py (see manuscript Section 5.4). The end-to-end video in docs/media/ demonstrates a reference implementation trained on a synthetic city and is not one of the manuscript's three case cities.

Architecture

flowchart LR
    A["Layer One<br/>Data infrastructure"]:::data --> B["Stage 1<br/>Multi-scale graph<br/>world model"]:::model
    B --> C["Stage 2<br/>KRCG physical<br/>grounding"]:::krcg
    C --> D["Stage 3<br/>Decision generation<br/>and uncertainty"]:::unc
    D --> E["Layer Three<br/>Rhino / Grasshopper<br/>bridge"]:::gh
    classDef data fill:#102524,stroke:#85B1AF,color:#E8F4F1
    classDef model fill:#102524,stroke:#86DB2A,color:#E8F4F1
    classDef krcg fill:#102524,stroke:#FF5C0A,color:#E8F4F1
    classDef unc fill:#102524,stroke:#7759FF,color:#E8F4F1
    classDef gh fill:#102524,stroke:#9DFA3A,color:#E8F4F1

Loading

Repository layout

Path	Purpose
urbanmind/data/	500 m grid, spatial blocking, temporal harmonization audit, PRISMA Track A/B record-level assignment
urbanmind/model/	Heterogeneous graph, coupling tensor, FiLM rollout, KRCG retrieval, constraint projection, sub-grid downscaling, uncertainty decomposition
urbanmind/train/	Three-phase training (masked autoencoding → grounding → intervention fine-tuning)
urbanmind/eval/	Experiments 1–3, unified statistical protocol (cluster bootstrap + Holm), calibration evaluation
urbanmind/runtime/	Timestamped per-run benchmark logging for the <30 s interactive claim
urbanmind/gh_bridge/	HTTP endpoint consumed by the Grasshopper component
scripts/	Track B library construction, record-assignment table, Experiment 2 runners, runtime benchmark, synthetic end-to-end demo
data/trackb/	Track B intervention outcome library: 208 verified records, DOI/site-level split, extracted effect sizes
demo/	Trainable synthetic backend, web viewer, video recording script
tests/	Smoke tests on synthetic data

Reproducibility artifacts

These modules generate the supplementary artifacts referenced in the manuscript:

• Record-level Track A/B split (urbanmind/data/tracks.py, scripts/make_record_assignment.py) — DOI- and study-site-disjoint partition of the intervention library between Phase-3 fine-tuning and Experiment-2 validation (manuscript Appendix A.5).
• Track B intervention outcome library (scripts/build_trackb_library.py, data/trackb/) — 208 Crossref-verified records across five intervention categories, with the enforced fine-tuning/validation assignment (data/trackb/trackb_assignment.csv), Köppen climate groups (scripts/assign_climate_groups.py), and extracted quantitative effect sizes (scripts/merge_trackb_effects.py).
• Experiment 2 under the enforced split (scripts/run_experiment2.py synthetic pipeline check, scripts/run_experiment2_real.py literature-effects run) — full coupling vs. sequential surrogate with paired cluster bootstrap over studies.
• Temporal harmonization audit (urbanmind/data/temporal.py) — per-variable proportions of measured / interpolated / rule-based downscaled / missing values with stagewise uncertainty inflation (Appendix A.9).
• Unified statistical protocol (urbanmind/eval/stats.py) — paired cluster bootstrap over independent units, Cohen's d, Holm correction within pre-declared test families (Section 4.5).
• Uncertainty calibration (urbanmind/eval/calibration.py) — coverage, interval width, expected calibration error, reliability diagrams (Appendix A.11).
• Runtime evidence (urbanmind/runtime/benchmark.py) — per-run timestamped logs, warm-up discards, failure/timeout records, hardware capture (Section 5.4).

Reproducibility index (BAE revision)

Files referenced in the response to reviewers (first revision). Comment numbers follow the response letter (R1 = Reviewer 1, R2 = Reviewer 2).

Revision item	Response letter	Files
Track B record-level split and leakage check	R1.1, R2.6	data/trackb/trackb_assignment.csv (208 records: DOI, study site, intervention, climate tag, subset), urbanmind/data/tracks.py (DOI- and site-disjoint assignment, verify_disjoint leakage check), scripts/make_record_assignment.py
PM2.5 station-holdout evaluation	R1.2, R2.9	scripts/fetch_holdout_data.sh, scripts/train_reference_model.py, scripts/station_holdout_eval.py, data/holdout/holdout_results_external.json
KRCG grounding verification (parent-cell closure, constraint projection)	R1.4, R2.10	urbanmind/model/grounding.py, scripts/grounding_verification.py, data/grounding_verification.json
Blocked-bootstrap inference for Experiment 1 (unified statistical protocol, Section 4.5)	R1.5, R1.6, R2.12	scripts/exp1_blocked_inference.py, urbanmind/eval/stats.py
Runtime benchmark harness (Section 5.4)	R1.7	urbanmind/runtime/benchmark.py
Uncertainty calibration evaluation (coverage, width, ECE, reliability)	R2.11	scripts/calibration_eval.py
Bibliography audit against Crossref	R2.13	scripts/audit_bibliography.py, data/bib_audit_report.json
Source-level completeness statistics (temporal harmonization audit)	R1.3	scripts/source_completeness_stats.py

Quick start

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# End-to-end smoke run on synthetic data (no external data needed)
python scripts/synthetic_demo.py

# Run the test suite
pytest tests/

Data

The gridded observation data (NOAA ISD, EPA AQS, NEA, CNEMC, MODIS, Sentinel-2, city energy disclosures) must be obtained from their original providers; see manuscript Section 3.1 and Appendix A.2 for sources and harmonization rules. Loaders in urbanmind/data/ operate on the harmonized 500 m daily grid format documented there. The Track B literature library in data/trackb/ is included: every record carries its DOI and the source review it was drawn from.

License

MIT — see LICENSE.