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`（建筑底图）<br>`streets.shp`（路网）<br>`terrain.shp`（地形）<br>`surroundings.shp`（周边地物）<br>`.cache/supply-system/`（缓存） | 社区级几何+建筑引用+气象配置 |
| `schema-community-energy.json` | `inputs/technology/components/`<br>`inputs/technology/assemblies/`<br>`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` 每栋建筑记录<br>`inputs/building-properties/*.dbf`<br>`inputs/building-geometry/zone.shp` | 建筑级几何（HBJSON） |
| `schema-energy.json` | `inputs/technology/archetypes/`<br>`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 建筑为例，展示完整的社区级数据映射：

```json
{
  "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 映射：

```json
{
  "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`，对应不同年代的围护结构传热系数水平。