# 复刻 BrainBox 暖通 AI 栈 · Resources

> 本课程的事实基线。三根支柱各自有一手论文 + 官方仓库，下面按支柱组织。
> **定调基线**：仓库内事实核查 [`world-model-brainbox-factcheck.md`](../../architecture/world-model-brainbox-factcheck.md) —— BrainBox 走的是 Neural ODE + 无模型 DRL，**非** MBRL / 世界模型。

## 定调（仓库内，最高信任）
- [world-model-brainbox-factcheck.md](../../architecture/world-model-brainbox-factcheck.md) — BrainBox 技术路线核查：专利/官网/CTO 论文/Trane 收购公告均无 MBRL/DreamerV3/world model 字样；自述为 Neural ODE + DRL。
- [world-model-research.md](../../architecture/world-model-research.md) — 世界模型调研（§6 HVAC、§9 架构建议）。本课程是它的"可复刻落地版"。

## 仿真环境（贯穿全课）
- **EnergyPlus** — 美国能源部建筑能耗仿真引擎。下载（macOS ARM 原生支持自 v25.1）：https://energyplus.net/downloads
- **EnergyPlus Python API（`pyenergyplus`）** — 官方绑定，回调里读传感器/写执行器。文档：https://energyplus.readthedocs.io/en/latest/api.html
- **Sinergym** — EnergyPlus → Gymnasium 的 RL 环境封装，社区首选。仓库：https://github.com/ugr-sail/sinergym · 文档：https://ugr-sail.github.io/sinergym/ · 论文（e-Energy 2021）：https://dl.acm.org/doi/10.1145/3486611.3488729 · 更新综述（arXiv 2412.08293）：https://arxiv.org/abs/2412.08293 · 版本钉死 Sinergym 3.11/3.12 ↔ EnergyPlus 25.1.0 ↔ Python 3.12.3。
- **eppy / geomeppy** — IDF 文件编程式编辑 / 几何操作。https://github.com/santoshphilip/eppy · https://github.com/jamiebull1/geomeppy
- **BOPTEST** — IBPSA 楼宇控制基准测试框架（规则基线 + KPI）。https://github.com/ibpsa/project1-boptest
- 平台提示：Sinergym 官方只测 Ubuntu；macOS ARM 可用但要手动配 PYTHONPATH；**教学推荐走 Docker 镜像**，跨平台可复现。

## 支柱 A · Neural ODE 预测（物理信息深度学习）
- **Neural ODE 原始论文**（Chen et al., NeurIPS 2018 Best Paper）— https://arxiv.org/abs/1806.07366
- **torchdiffeq** — 参考实现，作者即论文一作。`pip install torchdiffeq`。仓库：https://github.com/rtqichen/torchdiffeq · `odeint_adjoint`（O(1) 内存）vs `odeint`（更快、吃内存）。
- **torchdyn / torchode** — 更高层 / 并行批求解，加速 Neural ODE 训练。https://github.com/DiffEqML/torchdyn · torchode 论文 https://arxiv.org/abs/2210.12375
- **PINN 原始论文**（Raissi, Perdikaris, Karniadakis 2019, JCP）— 物理 ODE 作为损失项的软约束。ScienceDirect：https://www.sciencedirect.com/science/article/pii/S0021999118307125 · arXiv：https://arxiv.org/abs/1711.10561 · 作者代码：https://github.com/maziarraissi/PINNs
- **建筑热 RC 网络模型** — 物理 ODE 来源。1R1C 区域模型、3R2C 墙体模型综述（Ramallo-González 2013）：https://www.sciencedirect.com/science/article/abs/pii/S0378778813000315 · 算例（Bagheri 2015）：https://www.sfu.ca/~mbahrami/pdf/2015/A%20Resistance-Capacitance%20Model%20for%20Real-Time%20Thermal%20Calculation%20of%20Cooling%20Load%20in%20HVAC-R%20Systems.pdf
- **HVAC 领域 Neural ODE / PINN 最新作**（证明路线当前可用）：多区域 PINN（Sabbagh 2025）https://www.sciencedirect.com/science/article/pii/S0378778825013532 · MILA 建筑温控神经微分方程 https://mila.quebec/en/article/neural-differential-equations-for-temperature-control-in-buildings-under-demand-response
- **多区域 LSTM 温度预测**（Fang 2021，Energy & Buildings）— LSTM 基线对照。https://hal.science/hal-03625852/file/2021%20-%20Zhen%20Fang%20et%20al.%20-%20Energy%20and%20Buildings.pdf

## 支柱 B · 无模型 DRL 设定值优化
- **Stable Baselines3** — SAC/TD3/PPO 参考库。`pip install stable-baselines3[extra]`（v2.9.0, 2026-06）。仓库：https://github.com/DLR-RM/stable-baselines3 · 示例：https://stable-baselines3.readthedocs.io/en/master/guide/examples.html
- **Farama Gymnasium** — 环境接口标准（`reset()`→2 元组、`step()`→5 元组）。`pip install gymnasium`（v1.0+，API 已冻结）。仓库：https://github.com/Farama-Foundation/Gymnasium · 接口文档：https://gymnasium.farama.org/api/env/
- **算法选型**：连续控制首选 **SAC**（off-policy、样本高效、熵正则）；有大量并行仿真副本时可用 **PPO**。
- **d3rlpy** — 离线 RL（CQL/IQL），用历史 BMS 日志预训练再在线微调。`pip install d3rlpy`（v2.8.1）。仓库：https://github.com/takuseno/d3rlpy
- **HVAC-RL 代表论文**：
  - HVAC-DPT（Decision Transformer / in-context RL，未见建筑零训练泛化，节能 45%）— arXiv **2411.19746**（注意：研究材料里写的 2407.07419 是电信论文，已更正）：https://arxiv.org/abs/2411.19746
  - 专家引导 DRL + 安全屏蔽（Xu 等，Nature Sci Rep 2025）— DOI **10.1038/s41598-025-91326-z**（研究材料里写的 -87288-x 是 COVID 论文，已更正）：https://doi.org/10.1038/s41598-025-91326-z
  - Sinergym 上 SAC/TD3/PPO 基准评测 — https://arxiv.org/abs/2401.05737
  - Steady Soft Actor-Critic for HVAC（Sun 2025, MDPI Buildings）— https://www.mdpi.com/2075-5309/15/4/644

## 支柱 C · 安全门控与部署
- **Safe RL 综述**（建筑场景）：Safe RL for Buildings: Minimizing Energy Use（Esmaeili 2025, Energies）— https://www.mdpi.com/1996-1073/18/19/5313 （提出神经 barrier certificate + 屏蔽 governor）。
- **CLUE**（安全 model-based RL + 认知不确定性，BuildSys 2023）— https://sites.ucmerced.edu/files/wdu/files/23buildsys_clue.pdf
- **Safe Building HVAC Control via Batch RL**（IEEE 2022）— 离线预训练避免危险在线探索：https://www.computer.org/csdl/journal/su/2022/04/09748006/1CdACdGDfDa
- **ASHRAE-55** 舒适带（operative temp 18–26°C）、CO₂ < 1000ppm —— 奖励 / 硬约束的标准来源。
- **Pivot 架构衔接** — [`architecture.md`](../../architecture/architecture.md) §1 智能体矩阵 + 安全门控层；[`world-model-research.md`](../../architecture/world-model-research.md) §6.6 安全门控设计、§9.4 数据管线。

## BrainBox 自述（事实来源，用于"复刻对标"）
- Advancing AI 技术页：https://brainboxai.com/en/expertise/advancing-ai-for-reduced-building-energy-consumption
  - "96% predictive accuracy for each HVAC zone up to 6 hours ahead"
  - "integrating physics-based principles with black box deep learning"
  - 提及 Neural ODE（与 Mila / Pierre-Luc Bacon 合作）。
- 数据架构文章：https://brainboxai.com/en/articles/lifting-the-veil-on-brainbox-ais-data-architecture
- Trane 收购公告（2024.12）：https://investors.tranetechnologies.com/news-and-events/news-releases/news-release-details/2024/Trane-Technologies-to-Acquire-BrainBox-AI/default.aspx
- ⚠️ "10x less data" 是 BrainBox 未直接发表的数字（事实核查确认），课程里只作"物理先验带来数据高效"的框架性陈述，不当作官方统计。

## 研究材料中的两处 ID 勘误（已在本课程修正）
| 研究材料原文 | 实际指向 | 正确值 |
|---|---|---|
| HVAC-DPT = arXiv 2407.07419 | 电信 NOMA 论文 | arXiv **2411.19746** |
| Nature Sci Rep DOI -87288-x | COVID 代谢组论文 | DOI **-91326-z** |

## Gaps（缺口 / 无法复刻的部分）
- BrainBox 内部模型结构、超参、数据管线细节——**未公开**，课程里凡触及皆标注"推测"，给可辩护的最小实现。
- 真实楼宇硬件接入（BACnet/Modbus 下行控制）——本课程在仿真里闭环，真实接入留作"生产化"延伸，不在主线。
- BrainBox 自称的具体节能数字（25%）属 DRL 路线，**不能外推**为 Neural ODE 或 MBRL 的价值锚点。