[工具分享]CityLearn:面向建筑群能源协同与需求响应的强化学习环境
上一期实用工具我们介绍了对接单栋建筑 EnergyPlus 模型的强化学习环境 Sinergym。当控制对象从单栋建筑扩展到包含多栋住宅与商业建筑的街区或可再生能源社区(REC)时,调度问题不再只是调节室内温度设定点,还会涉及屋顶光伏消纳、户用与社区储能充放电、电动汽车(EV)定时充电、可平移柔性负荷以及配电网变压器容量限制。
开源项目 CityLearn 正是专门针对多建筑协同控制、负荷整形与需求响应开发的标准 Gymnasium 强化学习环境。该项目由 Jose Ramon Vazquez-Canteli 在智能环境实验室(Intelligent Environments Laboratory)发起、与 Soft-CPS 研究组及社区共同维护,代码采用 MIT 许可证。
多建筑能源社区仿真架构
与实时调用物理引擎重算建筑热平衡的工具不同,CityLearn 采用预先计算或实测的建筑冷热电负荷时间序列作为基础输入,将计算重心放在多建筑、多能源资产的协同调度与电网交互上。
在 CityLearn v3 架构中,一个能源社区由多栋建筑(含冷热系统与蓄能水箱)、光伏阵列、电池储能、电动汽车充电桩及可灵活调节负荷组成。环境在每个时间步读取各建筑的负荷、分时电价、光伏出力和储能荷电状态(SOC)作为观测(Observations),接收规则控制器(RBC)、模型预测控制(MPC)或强化学习智能体下发的充放电与温控动作(Actions),并在考虑本地社区能源共享、配电线路最大功率限制、设备故障或通信数据缺失等约束后推进模拟。

图 1|CityLearn v3 官方架构示意图,展示可配置的可再生能源社区、建筑资产、控制器接口与社区级 KPI 评价体系(来源:CityLearn 项目仓库,MIT 许可证)。
模拟结束后,调用内置的 env.evaluate_v2() 即可直接输出建筑级(building)与社区级(district)的关键绩效指标(KPIs)记分卡,包括社区总购电成本(district_cost_total_control_eur)、电网总购电量(district_energy_grid_total_import_control_kwh)、电动汽车离场最低电量达标率(district_ev_performance_departure_min_acceptable_feasible_ratio)以及配电越限电量(district_electrical_service_phase_violations_energy_total_kwh)等,方便在完全一致的基准控制器(如内置的 BusinessAsUsualAgent)下横向对比不同算法的表现。
v3.5.0 更新:葡萄牙可再生能源社区数据集
在 2026 年 11 月 17 日发布的 CityLearn 3.5.0 版本中,Tiago Fonseca(@calofonseca)等人合入了四套葡萄牙可再生能源社区(Portugal REC)合成数据集,代号分别为 pt_rec_4、pt_rec_15、pt_rec_30 和 pt_rec_100。这四套数据分别对应包含 4、15、30 和 100 个住宅及商业成员的能源社区,覆盖 2023—2024 两个完整年份,时间步长为 15 分钟,整包共含 983 个文件(216 MB),对应论文《Synthetic electricity demand and flexibility datasets for Portuguese energy communities》的 v3.4 版数据,按 CC BY 4.0 协议开放。
数据集内置了 9 个主场景(涵盖社区成员动态增减、受限的电网输入功率上限、电网停电中断、设备故障、观测数据缺失以及需求响应事件)和 6 个单一条件剔除对照场景,共计 19 套预置 Schema。在官方验证中,19 套配置运行最复杂单周(672 个时间步)的峰值内存占用约为 1.7 GB。此外,3.5.0 版本还升级了 DataSet.get_dataset() 的远程下载逻辑,支持直接拉取包含多级子文件夹的嵌套数据集,且无论目录嵌套多深,每次下载仅消耗 2 次 GitHub API 请求(实际数据文件直接从 raw.githubusercontent.com 获取)。
安装与快速上手
CityLearn 支持 Python 3.9 及以上版本,在虚拟环境中通过 pip install citylearn 即可直接安装。首次在代码中按名称调用公开数据集(如 "citylearn_challenge_2022_phase_all_plus_evs" 或新增的 "pt_rec_15")时,程序会自动从 GitHub 下载对应配置文件。如果在批量实验时遇到 GitHub 匿名 API 每小时 60 次的限流提示,只需在本地环境变量中配置 CITYLEARN_GITHUB_TOKEN 或 GITHUB_TOKEN 即可解除限制。官方同时提供了在线可视化面板 CityLearn UI,可用于直接导入导出的时间序列并对比各控制策略的负荷曲线。
