psong11/bentonville-gas-simulator

## 项目简介 这是一个燃气分配数字孪生，其 **1,240 个节点和 1,597 条管道完全遵循 Bentonville 的真实街道**。其节点需求源自真实的土地使用和地址密度，管道年代参考了人口普查中的房屋年龄数据，并纳入了真实的 FEMA 洪水暴露情况 —— 此外，还配备了物理引擎、风险分析和传感器布局算法，以充分发挥这些数据的价值。 在[在线网站](https://bentonville-gas-sim.vercel.app)上可以尝试以下三件事： 1. **询问网络。** 聊天栏是一个集成了八种工具、运行在实时模拟器上的 Claude agent。它通过真实的计算数据回答运营问题，并在地图上高亮显示其引用的管道。 2. **将地图切换为 Risk 视图。** 每条管道的评分公式为 `risk = P(fail) × consequence` —— 那些红色的走廊代表位于繁忙交通路段下方的老旧钢管，一旦发生故障，将导致数百 m³/h 的供气被隔离。 3. **拖动传感器预算滑块。** 一个贪婪的次模优化器（greedy submodular optimizer）会针对 200 个物理模拟泄漏场景规划传感器布局，并绘制边际收益曲线：**8 个传感器可以检测到 75% 的泄漏场景，而随机布局仅为 34%。** ## 数据（均为公开数据，由 `etl/` 拉取） | 来源 | 提供的内容 | |---|---| | [Bentonville 市 GIS](https://gis.bentonvillear.com/arcgis/rest/services) — 街道中心线 | 网络拓扑：干管遵循真实街道，层级由车速/车道数决定 | | 城市 GIS — 2025 年土地利用 + 地址点 | 节点需求（住宅/商业/工业 × 密度） | | 城市 GIS — FEMA 洪水图层（2022 年 3 月） | 每条管道的 100 年/500 年一遇洪水暴露情况 + 地图覆盖层 | | ARDOT 交通流量统计 | 开挖破坏风险代理指标（导致分配网络损坏的主要原因） | | 美国人口普查 ACS（街区组） | 建造年代中位数 → 管道年代先验概率；人口 | | PHMSA NPMS（人工参考） | 真实传输走廊附近门站的近似位置 | ETL 脚本运行一次（`python -m etl.fetch && python -m etl.build_network`）并提交带版本的 artifacts —— 部署的应用程序绝不会调用城市服务器。 ## 核心算法 **风险引擎** ([risk.py](risk.py)) — 针对每条管道计算 `risk = P(fail) × consequence`，进行百分位归一化处理，并提供完整的因子分解： - `P(fail)`：材质/年代先验概率（基于 PHMSA 事故模式） × 洪水暴露 × 开挖强度 × 压力利用率 - `Consequence`：管道发生故障时被隔离的需气量（图桥接）、承载流量、边介数中心性（edge betweenness）、与关键设施的距离 **传感器布局** ([placement.py](placement.py)) — 通过物理引擎模拟 200 个风险加权泄漏场景，构建一个泄漏特征矩阵（在 2 kPa 的检测下限下，哪些传感器能从*物理上*探测到哪些泄漏）。基于该矩阵的加权最大覆盖问题属于单调次模函数（monotone submodular），因此贪婪选择策略可达到 (1−1/e) 的近似最优 —— 并且计算速度足够快，完全支持在预算滑块拖动时实时进行重新规划。 **物理引擎** ([physics.py](physics.py)) — 采用 Darcy-Weisbach 压降公式（Swamee-Jain 摩擦系数），进行迭代网络求解，并引入了跳数衰减的泄漏影响场，使得泄漏能够像真实情况一样对其水力邻域造成压力下降。 ## AI Agent `POST /api/agent` 接口会流式传输 SSE 数据，同时 Claude (Opus 4.8) 会在 UI 所使用的相同服务之上运行一个工具调用循环： | 工具 | 计算内容 | |---|---| | `get_network_status` | 压力分布、阈值违规、活动泄漏、警告信息 | | `list_inspection_candidates` | 包含因子分解的风险引擎排名 | | `run_scenario` | 在不同的门站压力/需求乘数下重新模拟 | | `inject_leaks` / `clear_leaks` / `detect_leaks` | 训练场景 + 基于传感器的泄漏检测 | | `place_sensors` | 次模布局方案 + 边际收益曲线 | | `get_hazard_context` | 洪水暴露情况、管道年代分布、区域性灾害（龙卷风/冰雹/喀斯特） | 工具返回的结果包含节点/管道 ID；前端会在地图上对引用的位置产生闪烁脉冲效果。 ## 系统架构 ``` React 19 + Vite + MapLibre/deck.gl ──► FastAPI + NetworkX/NumPy ──► Claude API (Vercel, static) (Vercel Python function) ▲ committed artifacts: data/network.json, leak_signatures.npz, overlays/ built offline by: etl/fetch.py → etl/build_network.py → etl/build_signatures.py ``` ## 本地运行 ``` # backend — http://localhost:8000 (文档位于 /docs) python3 -m venv .venv && source .venv/bin/activate pip install -r requirements-dev.txt uvicorn api.main:app --reload --port 8000 # frontend — http://localhost:5173 (将 /api 和 /ws 代理到 :8000) cd frontend && npm install && npm run dev ``` 可选：在 `.env` 中配置 `ANTHROPIC_API_KEY` 以启用聊天 agent；配置 `CENSUS_API_KEY` 后，在下次运行 ETL 时将通过真实的 ACS 数据升级管道年代数据。 ``` # 从原始 sources 重新构建 artifacts python -m etl.fetch && python -m etl.build_network && python -m etl.build_signatures # tests (159 个 backend + 32 个 frontend) pytest tests/ -q cd frontend && npm test ``` ## 部署 前后端两部分均运行在 Vercel 上：前端是一个静态的 Vite 构建版本，其中 `/api/*` 被重定向至后端项目，而 FastAPI 后端则作为一个 Python 函数运行（`scripts/deploy_backend.sh`）。由于 Serverless 环境不支持 WebSocket，应用程序会自动回退到 REST 模式（在状态栏中显示为“On-demand”）。为了避免成本失控，agent 接口已配置了速率限制。 ## 项目起源 本项目诞生于 **2025 年 12 月 17 日的 Bentonville 硫醇事件** —— 这起燃气异味恐慌事件导致沃尔玛总部和 Bentonville 高中进行了人员疏散，最终查明是 J 街和沃尔顿大道附近在进行管线维护时发生的臭味剂释放。该事件留下了一个疑问：*一座不断发展的城市该如何预见真实存在的问题？* 这个项目就是答案之一：公共数据 + 物理引擎 + 优化算法 + 一个能让这一切变得可对话交互的 AI agent。 ## 许可证 MIT

标签：AI智能体, GIS, 代码示例, 城市规划, 基础设施仿真, 数字孪生, 数据分析, 特权检测, 自定义脚本, 逆向工具