ringo
7eab40f8fc
- schema-community.json: 7→11 defs（新增 BuildingRef, WeatherContext, SimulationContext） - schema-community-energy.json: 8→11 defs（新增 CommunityEnergyDemand 等） - 移除 AI 标注（已人工审核） - 新增 bps-schema 社区级字段说明 - 新增 CEA 字段映射文档链接
239 lines
9.8 KiB
Markdown
239 lines
9.8 KiB
Markdown
# bps-schema
|
||
|
||
建筑性能模拟数据模型。所有类型定义以 draft-2020-12 标准 JSON Schema 为准。
|
||
|
||
## 文件架构
|
||
|
||
采用"尺度 × 模拟域"二维分文件架构。每个尺度按几何和模拟域拆分为独立文件。
|
||
|
||
### 建筑单体尺度
|
||
|
||
| 文件 | $id | defs | 说明 |
|
||
|------|-----|------|------|
|
||
| `schema-building.json` | bps/building | 30 | 建筑几何实体，对齐 HBJSON 几何层级 |
|
||
| `schema-energy.json` | bps/energy | 49 | EnergyPlus 能耗模拟参数 |
|
||
| `schema-radiance.json` | bps/radiance | 25 | Radiance 采光模拟参数 |
|
||
| `schema-cfd.json` | bps/cfd | 14 | CFD 建筑风环境模拟参数（AI 生成的示例文件，需人工审核后使用） |
|
||
|
||
### 社区尺度
|
||
|
||
| 文件 | $id | defs | 说明 |
|
||
|------|-----|------|------|
|
||
| `schema-community.json` | bps/community | 11 | 社区几何：Site / Terrain / Road / GreenSpace / WaterBody / BuildingRef / WeatherContext / SimulationContext |
|
||
| `schema-community-energy.json` | bps/community-energy | 11 | 区域能源：Plant / Network / Pipe / BuildingConnection / CommunityEnergyDemand |
|
||
| `schema-community-cfd.json` | bps/community-cfd | 13 | 社区风环境：计算域 / 网格 / 湍流 / 边界条件 / 求解器（AI 生成的示例文件，需人工审核后使用） |
|
||
| `schema-community-microclimate.json` | bps/community-microclimate | 2 | 微气候：UHI 强度 / 风速修正 / 地表反照率（AI 生成的示例文件，需人工审核后使用） |
|
||
|
||
### 城市尺度
|
||
|
||
| 文件 | $id | defs | 说明 |
|
||
|------|-----|------|------|
|
||
| `schema-urban.json` | bps/urban | 3 | 城市几何：ClimateZone / LandUse（AI 生成的示例文件，需人工审核后使用） |
|
||
| `schema-urban-energy.json` | bps/urban-energy | 5 | 城市能源：需求聚合 / 可再生能源潜力 / 碳平衡（AI 生成的示例文件，需人工审核后使用） |
|
||
| `schema-urban-cfd.json` | bps/urban-cfd | 15 | 城市风环境：行人高度评估 / 街道峡谷 / 风舒适标准（AI 生成的示例文件，需人工审核后使用） |
|
||
|
||
### 聚合入口
|
||
|
||
| 文件 | $id | defs | 说明 |
|
||
|------|-----|------|------|
|
||
| `schema-all.json` | bps/all | 11 | 引用以上所有文件，提供完整验证入口 |
|
||
|
||
**合计**：11 个领域文件 + 1 个聚合文件，178 个类型定义。
|
||
|
||
## 与 CEA 的字段映射
|
||
|
||
详见 [docs/cea-mapping.md](docs/cea-mapping.md)。该文档记录了 bps-schema 各字段与 CEA（City Energy Analyst）输入/输出文件的对应关系，涵盖社区级的建筑属性、气象配置、模拟配置、用能需求汇总。高层持续更新。
|
||
|
||
## Schema 规范
|
||
|
||
所有文件均遵循 [JSON Schema draft-2020-12](https://json-schema.org/draft/2020-12/release-notes)：
|
||
|
||
- `$defs` — 所有类型、枚举、实体的定义区
|
||
- `$ref` — 类型引用，使用 JSON Schema 标准 `$ref` 机制
|
||
- `oneOf` — 判别联合体（如边界条件的 5 种类型）
|
||
- `allOf` — 实体组合（`_IdentifiedObject` + 具体属性）
|
||
- `const` / `enum` — 类型判别字段和枚举值
|
||
- `required` — 必填字段
|
||
- `default` — 缺省值
|
||
- `minimum` / `maximum` / `exclusiveMinimum` — 数值约束
|
||
- `pattern` / `minLength` / `maxLength` — 字符串约束
|
||
- `additionalProperties: false` — 严格模式，禁止额外字段
|
||
|
||
## schema-building.json：建筑几何
|
||
|
||
对齐 [honeybee-schema](https://github.com/ladybug-tools/honeybee-schema) 几何层级，覆盖 Model → Room → Face → Aperture/Door → Shade 层级。
|
||
|
||
### 几何原语
|
||
|
||
- `Point3D` — 三维坐标 (x, y, z)
|
||
- `Face3D` — 平面多边形（boundary + holes + plane）
|
||
- `Mesh3D` — 三角/四边形网格（vertices + faces + colors）
|
||
- `Plane` — 平面（法线 n + 原点 o + x 轴）
|
||
- `Color` — RGBA 颜色
|
||
|
||
### 边界条件
|
||
|
||
- `Outdoors` / `Surface` / `Ground` / `Adiabatic` / `OtherSideTemperature`
|
||
- Aperture/Door 仅支持 Outdoors 和 Surface 两种
|
||
|
||
### 标识符规范
|
||
|
||
- `identifier`：`^[.A-Za-z0-9_-]+$`，1-100 字符
|
||
- `display_name`：无限制（仅用于 UI 展示）
|
||
- `user_data`：可选字典
|
||
|
||
## schema-energy.json：能耗模拟参数
|
||
|
||
覆盖 HBJSON energy properties 核心实体：材料、构造、时间表、负荷、HVAC、构造集、程序类型。
|
||
|
||
### 材料
|
||
|
||
- `EnergyMaterial` — 有质量材料
|
||
- `EnergyMaterialNoMass` — 无质量材料
|
||
- `EnergyMaterialVegetation` — 植被材料
|
||
- `EnergyWindowMaterialGlazing` / `Gas` / `GasCustom` / `GasMixture` / `SimpleGlazSys` — 窗材料
|
||
- `EnergyWindowMaterialBlind` / `Shade` — 百叶/遮阳
|
||
- `EnergyWindowFrame` — 窗框
|
||
|
||
### 构造
|
||
|
||
- `OpaqueConstruction` / `WindowConstruction` / `AirBoundaryConstruction` / `ShadeConstruction`
|
||
- 各自 Abridged 版本（identifier 引用）
|
||
- `WindowConstructionShade` / `WindowConstructionDynamic` — 含动态遮阳的窗构造
|
||
|
||
### 时间表
|
||
|
||
- `ScheduleTypeLimit` / `ScheduleDay` / `ScheduleFixedInterval` / `ScheduleRulesetAbridged` / `ScheduleRule`
|
||
|
||
### 负荷与设定值
|
||
|
||
- `PeopleAbridged` / `LightingAbridged` / `ElectricEquipmentAbridged` / `GasEquipmentAbridged`
|
||
- `ServiceHotWaterAbridged` / `InfiltrationAbridged` / `VentilationAbridged`
|
||
- `SetpointAbridged` / `InternalMassAbridged` / `ProcessAbridged`
|
||
|
||
### 程序类型 / 构造集 / HVAC
|
||
|
||
- `ProgramTypeAbridged` / `ConstructionSetAbridged`
|
||
- `DefaultProgramTypesAbridged` / `DefaultConstructionSetAbridged`
|
||
- `IdealAirSystemAbridged`
|
||
|
||
## schema-radiance.json：采光模拟参数
|
||
|
||
兼容 HBJSON radiance properties，覆盖 Radiance 材质、构造集、传感器网格、视角。
|
||
|
||
### 材质（Modifiers）
|
||
|
||
- `Plastic` — 塑料材质（RGB 反射率 + 镜面度 + 粗糙度）
|
||
- `Metal` — 金属材质（继承 Plastic，镜面度默认 0.9）
|
||
- `Trans` — 半透明材质（透射漫反射比 + 透射镜面比）
|
||
- `Glass` — 玻璃材质（RGB 透射率 + 折射率）
|
||
- `Mirror` — 镜面材质（RGB 反射率）
|
||
- `Light` / `Glow` — 发光材质（RGB 发射率）
|
||
- `BSDF` — 双向散射分布函数材质（BSDF XML 数据 + 朝向）
|
||
- `Void` — 空材质
|
||
|
||
### 材质集（Modifier Sets）
|
||
|
||
- `WallModifierSetAbridged` / `FloorModifierSetAbridged` / `RoofCeilingModifierSetAbridged`
|
||
- `ApertureModifierSetAbridged` / `DoorModifierSetAbridged` / `ShadeModifierSetAbridged`
|
||
- `ModifierSet` — 材质集聚合
|
||
|
||
### 传感器与视角
|
||
|
||
- `Sensor` / `SensorGrid` — 传感器网格
|
||
- `View` — Radiance 视角（6 种视角类型）
|
||
|
||
## schema-cfd.json：CFD 风环境模拟
|
||
|
||
独立领域（非 HBJSON），覆盖 CFD 建筑风环境分析的完整参数体系。
|
||
|
||
### 核心参数
|
||
|
||
- `WindProfile` — 风剖面（4 种剖面 + 地形类别 + 风向）
|
||
- `CFDDomain` — 计算域定义
|
||
- `MeshParameters` — 网格设置（基础网格 + 局部加密 + 壁面层）
|
||
- `TurbulenceParameters` — 湍流设置（6 种模型 + 壁面函数）
|
||
- `BoundaryConditions` — 进出口/顶部/侧面/地面/建筑墙面边界类型
|
||
- `SolverSettings` — 求解器设置（稳态/瞬态 + SIMPLE/PISO + 收敛准则）
|
||
|
||
## schema-community*.json：社区尺度
|
||
|
||
### 几何（schema-community.json）
|
||
|
||
- `Site` — 场地顶级实体，含 2D 边界、地形、道路、绿地、水体
|
||
- `TerrainGrid` / `TerrainTIN` — 高程网格或三角网
|
||
- `Road` / `GreenSpace` / `WaterBody` — 基础设施
|
||
- `BuildingRef` — 社区建筑引用，通过 `ref` 指向 building schema 标识符
|
||
- `CommunityBuildingAttributes` — 社区尺度的建筑属性：使用类型、构造标准、层数、高度、底面积、热区/占位/电气比例
|
||
- `WeatherContext` — 气象数据引用（EPW 路径、气候区、经纬度）
|
||
- `SimulationContext` — 模拟配置（数据库区域、场景名称）
|
||
|
||
### 区域能源（schema-community-energy.json）
|
||
|
||
- `DistrictEnergy` — 区域能源系统顶级实体
|
||
- `Plant` — 源站（CHP / Boiler / HeatPump / Chiller / PV 等）
|
||
- `Network` — 管网（CHW / HW / Steam / Electricity）
|
||
- `Pipe` / `BuildingConnection` — 管段与建筑接入
|
||
- `CommunityEnergyDemand` — **新增** 社区级用能需求汇总
|
||
- `BuildingEnergyDemand` — 每栋建筑年度用能（heating/cooling/electricity/dhw MWh + 峰值）
|
||
- `AggregatedEnergyDemand` — 社区聚合指标（总用能、EUI）
|
||
- DistrictEnergy 新增 `demand` 字段，连接负荷输入与区域能源系统
|
||
|
||
### 风环境（schema-community-cfd.json）
|
||
|
||
- `CFDDomain` — 社区尺度计算域
|
||
- `MeshParameters` — 含局部加密区域
|
||
- `SolverSettings` / `TurbulenceParameters` / `BoundaryConditions`
|
||
|
||
## schema-urban*.json：城市尺度
|
||
|
||
### 几何（schema-urban.json）
|
||
|
||
- `ClimateZone` — 气候分区（边界 + 气候区代码 + 度日数）
|
||
- `LandUse` — 用地性质（边界 + 用地类型 + 容积率 + 建筑密度）
|
||
|
||
### 能源（schema-urban-energy.json）
|
||
|
||
- `UrbanEnergyDemand` — 各用地类型年度能耗
|
||
- `RenewablePotential` — 屋顶/立面/地面可再生能源潜力
|
||
- `UrbanEnergyBalance` — 城市能源平衡（自给率 / 碳排放 / EUI）
|
||
|
||
### 风环境（schema-urban-cfd.json）
|
||
|
||
- `UrbanCFDSettings` — 城市级 CFD 设置
|
||
- `WindComfortAssessment` — 行人风舒适评估（Laws / NEN_8100 / COST_732 标准）
|
||
- `MeshParameters` — 含行人高度加密层
|
||
|
||
## 使用方式
|
||
|
||
### 数据验证
|
||
|
||
```bash
|
||
pip install jsonschema
|
||
python3 -c "
|
||
import json, jsonschema
|
||
with open('schema-building.json') as f:
|
||
schema = json.load(f)
|
||
with open('model.hbjson') as f:
|
||
data = json.load(f)
|
||
jsonschema.validate(data, schema)
|
||
"
|
||
```
|
||
|
||
### TypeScript 类型生成
|
||
|
||
```bash
|
||
npx quicktype schema-building.json -o dist/building.d.ts --lang typescript
|
||
npx quicktype schema-energy.json -o dist/energy.d.ts --lang typescript
|
||
npx quicktype schema-radiance.json -o dist/radiance.d.ts --lang typescript
|
||
npx quicktype schema-cfd.json -o dist/cfd.d.ts --lang typescript
|
||
```
|
||
|
||
### Python Pydantic 生成
|
||
|
||
```bash
|
||
pip install datamodel-code-generator
|
||
datamodel-codegen --input schema-building.json --output dist/building.py --output-model-type pydantic_v2.BaseModel
|
||
datamodel-codegen --input schema-energy.json --output dist/energy.py --output-model-type pydantic_v2.BaseModel
|
||
```
|