Lesson 05 · 工具链

上下游工具链：eppy / Sinergym / OpenStudio

把方案里那串英文名词排成一条流水线，每个说清"在哪一环、干什么"。

先把整条流水线画出来

        ┌──────────── 建模（造 IDF）────────────┐
        │   OpenStudio App / SketchUp            │
        │        或 BIM(Revit)→IFC→IfcOpenShell    │
        │                 │                       │
        │                 ▼                       │
        │           原始 building.idf             │
        └─────────────────┬───────────────────────┘
                          │ 批量改参数（域随机化/校准/埋 Actuator）
                          ▼
        ┌──────────── eppy（Python 改 IDF）────────┐
        │   idf = IDF("building.idf")              │
        │   chiller = idf.HVACTemplate...[0]       │
        │   chiller.Capacity *= 1.05               │
        │   idf.save()                             │
        └─────────────────┬────────────────────────┘
                          │ 把 IDF + EPW 包成标准 RL 环境
                          ▼
        ┌──────────── Sinergym（包成 Gymnasium）────┐
        │   env = gym.make("Eplus-...-v1")         │
        │   obs, info = env.reset()                │
        │   obs, r, term, trunc, info = env.step(a)│
        └─────────────────┬────────────────────────┘
                          │ 我们的智能体在这里训练
                          ▼
                    DreamerV3 训练循环

三者的分工就是这条流水线上的三段：建模 → 批改 → 封装。下面逐个说。

① OpenStudio —— 建模（造 IDF）

OpenStudio 是 NREL 出的开源建模平台，分两部分：

• OpenStudio SDK（Ruby/C++）：可编程的建模内核。
• OpenStudio Application：图形界面，最早是 SketchUp 插件，现在能独立画楼、配空调系统、设时间表。

它是业界最主流的 EnergyPlus 建模途径。你在图形界面里把楼搭好、空调系统配好，它前向翻译（forward-translate）成 IDF 交给 EnergyPlus 跑。方案 [§2.2.3] 的"路径 A（BIM 高精度）"和"路径 B（示例改）"最终都要落到一个 IDF 上，而 OpenStudio 是产出高质量 IDF 的首选。

② eppy —— 批改（脚本化改 IDF）

eppy 是一个 Python 库，把 IDF 当成 Python 对象来读写。它不负责画楼，只负责把已有的 IDF 程序化地改。为什么 RL 项目特别需要它？看方案 [§2.2.4] 的域随机化：

from eppy.modeleditor import IDF
import random

IDF.setiddname("Energy+.idd")
idf = IDF("building.idf", "Energy+.idd")

# 把每面墙的 U 值随机扰动 ±10%，让智能体见过"不那么完美的楼"
for surface in idf.idfobjects["BuildingSurface:Detailed"]:
    # 取构造名 → 找到材料层 → 改厚度/导热，等效改 U 值
    ...

# 把冷机容量扰动 ±15%
for ch in idf.idfobjects["HVACTemplate:Plant:Chiller"]:
    ch.reference_capacity *= random.uniform(0.85, 1.15)

idf.saveas("building_randomized.idf")

域随机化是缩小 sim-to-real gap 的核心手段——方案 [§2.2.4] 明确推荐"域随机化 + 残差策略 + 渐进部署"。而要批量生成几百个参数略有不同的 IDF，靠 OpenStudio GUI 不现实，必须 eppy。这就是它在我们流水线里不可替代的位置。

③ Sinergym —— 封装（包成 RL 环境）

第 4 课讲了 EMS/pyenergyplus 那套回调+队列通信很绕。Sinergym 就是把它封装成 RL 圈大家都认的标准接口——Gymnasium（强化学习环境的事实标准 API）。用起来你几乎感觉不到 EnergyPlus 的存在：

import gymnasium as gym
import sinergym

env = gym.make(
    "Eplus-office-hot-continuous-v1",   # 内置环境名
    weather="CHN_Wuhan.IF",              # 或自定义 EPW
    # 也可传自定义 idf_file=...
)

obs, info = env.reset()
for _ in range(1000):
    action = policy(obs)                 # 你的 RL 策略（DreamerV3）
    obs, reward, terminated, truncated, info = env.step(action)
    if terminated or truncated:
        obs, info = env.reset()
env.close()

它的价值在于：DreamerV3-torch 期待的就是 Gymnasium 接口，我们只要写一个薄薄的 envs/hvac.py 把 Sinergym 环境适配进去（方案 [§2.1.4] 给了骨架），而不必从零处理 pyenergyplus 的线程队列。这就是方案 [§2.2.2] 选它而不是 CityLearn 或自建的根本理由。

卡住了就问我：如果你不确定"我到底要不要碰 OpenStudio"——按方案 §7 的分工，建模主要是暖通工程师/顾问的活，后端工程师碰的主要是 eppy 和 Sinergym。问我你的角色具体到哪一环，我帮你定位。