bps-schema/docs/cea-mapping.md

bps-schema 与 CEA 软件字段映射

日期：2026-05-29 版本：v1 — 社区尺度初次对齐

---

一、文件级映射

bps-schema 按几何尺度和模拟域分文件管理。以下列出各 schema 文件与 CEA 输入/输出文件的对应关系。

bps-schema 文件	对应 CEA 文件/数据	说明
schema-community.json	zone.shp（建筑底图） streets.shp（路网） terrain.shp（地形） surroundings.shp（周边地物） .cache/supply-system/（缓存）	社区级几何+建筑引用+气象配置
schema-community-energy.json	inputs/technology/components/ inputs/technology/assemblies/ outputs/data/demand/Total_demand.csv	区域能源系统+用能需求输出
schema-community-cfd.json	不直接对应 CEA（CEA 无 CFD）	CFD 风环境参数
schema-community-microclimate.json	不直接对应 CEA（CEA 不模拟微气候）	微气候参数
schema-building.json	zone.shp 每栋建筑记录 inputs/building-properties/*.dbf inputs/building-geometry/zone.shp	建筑级几何（HBJSON）
schema-energy.json	inputs/technology/archetypes/ inputs/technology/assemblies/	EnergyPlus 模拟参数（其他团队负责）
schema-urban.json	不直接对应 CEA（CEA 社区级为顶层）	城市级几何

---

二、社区级几何映射（schema-community.json）

2.1 Site 对象

bps-schema 字段	CEA 来源	CEA 路径/文件	说明
type	常量 "Site"	—	—
boundary	CEA 无直接对应	—	场地边界多边形（CEA 以建筑集合隐式定义场地）
terrain	terrain.shp	inputs/topography/terrain.shp	地形格网/TIN
roads	streets.shp	inputs/networks/streets.shp	道路中心线与宽度
green_spaces	surroundings.shp	inputs/surroundings/surroundings.shp（部分）	周边绿地
water_bodies	surroundings.shp（部分）	inputs/surroundings/surroundings.shp	水体边界
buildings	zone.shp	inputs/building-geometry/zone.shp	新增，建筑引用列表
weather	weather.epw	inputs/weather/weather.epw	新增，气象数据引用
simulation_context	default.config	cea/default.config	新增，模拟配置

2.2 BuildingRef → 建筑引用

bps-schema 字段	CEA 来源	说明
type	常量 "BuildingRef"	—
ref	zone.shp → Name	指向 schema-building.json 的建筑 identifier
community_attributes	zone.shp 多列 + typology.dbf	社区尺度的建筑属性（见下）

2.3 CommunityBuildingAttributes

CEA 字段→bps-schema 字段的逐列映射，来源为 zone.shp + typology.dbf。

bps-schema 字段	CEA 字段	CEA 来源	类型/格式	说明
primary_use_type	1ST_USE	typology.dbf	string	主要使用类型枚举，参考 CEA USE_TYPES.csv
construction_standard	STANDARD	typology.dbf	string	CEA 构造标准代码，如 STANDARD2/5
year_of_construction	YEAR	typology.dbf	integer	建成年份
floors_above_ground	floors_ag	zone.shp	integer	地上层数
floors_below_ground	floors_bg	zone.shp	integer	地下层数
height_above_ground_m	height_ag	zone.shp	number	地上高度（m）
height_below_ground_m	height_bg	zone.shp	number	地下高度（m）
footprint_m2	geometry.area	zone.shp	number	底面积（m²），由几何计算
heated_share	Hs_ag	architecture.dbf	[0,1]	地上部分热区比例
occupied_share	Ns	architecture.dbf	[0,1]	地上部分占位比例
electrified_share	Es	architecture.dbf	[0,1]	电气化比例
basement_conditioned	Hs_bg（推断）	architecture.dbf	boolean	地下室是否空调
void_deck_floors	void_deck	zone.shp	number	架空层数

2.4 WeatherContext

bps-schema 字段	CEA 来源	说明
type	常量 "WeatherContext"	—
epw_file_path	config.general → weather	EPW 文件路径
climate_zone	default.config → databases-path	气候区标识：CH/SG/DE
location.latitude	EPW 文件头	纬度
location.longitude	EPW 文件头	经度
location.timezone_offset	EPW 文件头	时区偏移

2.5 SimulationContext

bps-schema 字段	CEA 来源	CEA 配置键	说明
type	常量 "SimulationContext"	—	—
database_region	database-helper → databases-path	[database-helper] databases-path	CH/SG/DE
scenario_name	config.general → scenario-name	[general] scenario-name	场景名，如 baseline
description	用户定义	—	场景描述

---

三、社区级能源映射（schema-community-energy.json）

3.1 Plant / Network / Pipe

bps-schema	CEA 来源	说明
Plant.plant_type	cea/technologies/supply_systems/	CEA 供给系统类型枚举
Plant.rated_capacity	cea/databases/CH/SUPPLY_*.csv	额定容量
Plant.cop	cea/databases/CH/SUPPLY_*.csv	能效比
Network.network_type	cea/technologies/network_layout/	管网类型
Network.supply_temperature	用户配置	供温
Network.return_temperature	用户配置	回温
Pipe.diameter	管网优化输出	管径
Pipe.insulation_thickness	cea/databases/CH/DISTRIBUTION.csv	保温厚度
BuildingConnection.design_flow_rate	水力计算输出	设计流量

3.2 CommunityEnergyDemand（CEA 模拟输出）

CEA 的 Total_demand.csv 包含每栋建筑的年度用能汇总。以下映射关系：

bps-schema 字段	CEA Total_demand.csv 字段	计算方式
BuildingEnergyDemand.building_ref	name	建筑标识符
BuildingEnergyDemand.gross_floor_area_m2	GFA_m2	建筑面积
BuildingEnergyDemand.conditioned_floor_area_m2	Af_m2	空调面积
annual.heating_mwh	QH_sys_MWhyr	总供热（sys 端）
annual.cooling_mwh	QC_sys_MWhyr	总供冷（sys 端）
annual.electricity_mwh	E_sys_MWhyr	总电力
annual.dhw_mwh	Qww_sys_MWhyr	生活热水
annual.total_mwh	各列求和	总用能
peak_heating_kw	QH_sys0_kW	供热峰值
peak_cooling_kw	QC_sys0_kW	供冷峰值

聚合字段 AggregatedEnergyDemand：

bps-schema 字段	计算公式
total_buildings	建筑栋数
total_gfa_m2	Σ GFA_m2
total_conditioned_m2	Σ Af_m2
total_heating_mwh	Σ QH_sys_MWhyr
total_cooling_mwh	Σ QC_sys_MWhyr
total_electricity_mwh	Σ E_sys_MWhyr
total_dhw_mwh	Σ Qww_sys_MWhyr
total_energy_mwh	Σ（以上四项）
energy_use_intensity_kwh_m2	total_energy_mwh × 1000 / total_gfa_m2

3.3 DistrictEnergy 新增字段

bps-schema 字段	CEA 来源	说明
demand	outputs/data/demand/Total_demand.csv	新增，引用 CommunityEnergyDemand
supply_temperature_hw_c	cea/default.config → demand	供热设计供温
return_temperature_hw_c	cea/default.config → demand	供热设计回温
supply_temperature_chw_c	cea/default.config → demand	供冷设计供温
return_temperature_chw_c	cea/default.config → demand	供冷设计回温

---

四、CEA 数据库到 bps-schema 的引用体系

CEA 内置数据库（cea/databases/CH/）定义了构造/系统/设备的标准参数，bps-schema 中通过 code 字段引用：

bps-schema CommunityBuildingAttributes
  └── primary_use_type ──────→ CH/ARCHETYPES/USE/USE_TYPES.csv
  └── construction_standard ─→ CH/ARCHETYPES/CONSTRUCTION/CONSTRUCTION_TYPES.csv

bps-schema building 侧（其他团队负责）
  └── envelope codes ───────→ CH/ASSEMBLIES/ENVELOPE/*.csv
  └── hvac codes ───────────→ CH/ASSEMBLIES/HVAC/*.csv
  └── supply codes ─────────→ CH/ASSEMBLIES/SUPPLY/*.csv

---

五、CEA 参考案例映射示例

以 CEA 参考案例中 B1000 建筑为例，展示完整的社区级数据映射：

{
  "type": "Site",
  "identifier": "zurich-open-baseline",
  "boundary": [[463100, 15224700], [463300, 15224700], ...],
  "buildings": [
    {
      "type": "BuildingRef",
      "ref": "B1000",
      "community_attributes": {
        "primary_use_type": "OFFICE",
        "construction_standard": "STANDARD2",
        "year_of_construction": 1943,
        "floors_above_ground": 7,
        "floors_below_ground": 1,
        "height_above_ground_m": 21,
        "footprint_m2": 1509,
        "heated_share": 0.95,
        "occupied_share": 0.85,
        "electrified_share": 0.9,
        "basement_conditioned": true,
        "void_deck_floors": 0
      }
    }
  ],
  "weather": {
    "type": "WeatherContext",
    "epw_file_path": "inputs/weather/weather.epw",
    "climate_zone": "CH"
  },
  "simulation_context": {
    "type": "SimulationContext",
    "database_region": "CH",
    "scenario_name": "baseline",
    "description": "Zurich Open reference case baseline"
  },
  "roads": [ ... ],
  "green_spaces": [ ... ]
}

CEA 模拟输出到 bps-schema 的 CommunityEnergyDemand 映射：

{
  "type": "CommunityEnergyDemand",
  "identifier": "zurich-baseline-demand",
  "buildings": [
    {
      "building_ref": "B1000",
      "gross_floor_area_m2": 12071,
      "conditioned_floor_area_m2": 8865,
      "annual": {
        "heating_mwh": 755.3,
        "cooling_mwh": 42.8,
        "electricity_mwh": 31.2,
        "dhw_mwh": 63.5,
        "total_mwh": 892.8
      },
      "peak_heating_kw": 632.3,
      "peak_cooling_kw": 131.9
    }
  ],
  "aggregated": {
    "total_buildings": 15,
    "total_gfa_m2": 84422,
    "total_heating_mwh": 4878.2,
    "total_cooling_mwh": 184.9,
    "total_electricity_mwh": 133.2,
    "total_dhw_mwh": 583.3,
    "total_energy_mwh": 5779.6,
    "energy_use_intensity_kwh_m2": 68.5
  }
}

---

六、未覆盖项（已知缺口）

以下 CEA 数据在当前 bps-schema 中尚无对应定义，供后续版本参考：

CEA 数据	建议归属	说明
inputs/building-properties/envelope.csv（围护构造选型）	building schema	其他团队负责
inputs/building-properties/hvac.csv（暖通系统选型）	building schema	其他团队负责
inputs/building-properties/supply.csv（供给系统选型）	building schema	其他团队负责
inputs/building-properties/internal_loads.csv（内部负荷）	building schema	其他团队负责
inputs/building-properties/indoor_comfort.csv（舒适度参数）	building schema	其他团队负责
inputs/building-properties/schedules/（逐时作息）	社区级或新增	可复用的作息模板定义
cea/databases/CH/ASSEMBLIES/（装配库）	新增 schema-assemblies	构造/暖通/供给系统的目录库
cea/databases/CH/COMPONENTS/（组件库）	新增 schema-components	设备详细参数
outputs/data/demand/{building}.csv（逐时输出）	社区级或 building	可选，76列×8760行逐时数据

---

附录 A：CEA 枚举值参考

A.1 USE_TYPES

CEA 使用类型枚举（来源：cea/databases/CH/ARCHETYPES/USE/USE_TYPES.csv）：

OFFICE, SCHOOL, RETAIL, MULTI_RES, SINGLE_RES, HOTEL, HOSPITAL, INDUSTRIAL, RESTAURANT, GYM, LIBRARY, MUSEUM, PARKING, SWIMMING, LAB, SERVERROOM, FOODSTORE, UNIVERSITY, COOLROOM

A.2 数据库区域

CH = 瑞士（温带气候基准），SG = 新加坡（热带气候），DE = 德国

A.3 Construction Standard

CEA 构造标准代码（来源：cea/databases/CH/ARCHETYPES/CONSTRUCTION/CONSTRUCTION_TYPES.csv）： STANDARD1 ~ STANDARD6，对应不同年代的围护结构传热系数水平。