Skip to content

validation_protocol.md

Latest commit

 

History

History
229 lines (170 loc) · 14.4 KB

validation_protocol.md

File metadata and controls

229 lines (170 loc) · 14.4 KB
Raw

校准、验证与科学声明协议

0. 契约状态：运行时与目标设计不可混淆

层级 文件/对象 当前状态 能否直接驱动当前 CLI
Active runtime object SimulationConfig、schemas/simulation_config.schema.json 当前合成 MVP 的实际字段、默认值和范围 是；CLI 支持同结构 JSON/YAML/YML
Active JSON example examples/synthetic_minute.json 等 当前 doctor/run 直接读取 是
Active YAML example configs/runtime.synthetic.example.yaml 与 minute JSON 语义相当；synthetic/engineering-only 是；需安装 PyYAML
Target design config configs/mvp.example.yaml、configs/scientific.example.yaml 数据接入/科学完整版蓝图 否
Target rich contracts Scenario、RunRequest、EvidenceBundle schema 场景、调度、证据的目标契约 否；当前 runner/API 未调用
Real-data manifest AssetManifest schema、石牌 pilot manifest/Scenario/RunRequest 官方目录候选与基础本地完整性预检 只可驱动 asset-preflight；不下载、不适配、不仿真

因此，Scenario/RunRequest/EvidenceBundle 通过 schema 只证明目标对象结构合法，不证明当前代码可以消费或产生它们。当前 manifest 的 COMPLETE/FAILED 等字段也不是 EvidenceBundle 的实现。

1. 证据层级

层级 内容 可支持的声明
V0 静态/契约 schema、单位、CRS、时间语义、哈希 输入和输出结构合法
V1 数值单元 单元测试、守恒、制造解、网格/时间步收敛 离散实现符合指定方程
V2 理想化基准 阴影、导热、干燥、湿表面蒸发、平流扩散 机制在受控条件下合理
V3 现场校准 独立传感器训练时段 参数适配该地点/时段
V4 独立验证 未用于校准的时段/季节 在验证域内有测得误差
V5 外部验证 另一街区/城市/气候 有限的空间泛化证据
V6 运行部署 连续接入、时延、缺测、漂移、故障恢复 满足特定用途的运行要求

任何交付报告都必须声明最高完成层级。通过 V0/V1 不得描述为“准确预测”。

2. 预处理验证

  • 所有栅格/矢量统一投影 CRS 与垂直基准；
  • 建筑高度语义明确为相对地面高度还是绝对屋顶高程；
  • DEM/DSM 不重复计算建筑高度；
  • 气象时间戳统一为 UTC，保留原始时区与累计窗口；
  • 云量限定 [0,1]，降雨非负，风向转矢量后插值；
  • 累计辐射/降雨按原数据约定解码；
  • 每次重投影和重采样记录算法，分类数据不得使用双线性插值；
  • 质量控制不删除原始值，只新增 flag 与规范化资产。

2.1 建筑高度候选的额外门槛

  • 3D-GloBFP 是约 2020 年的 ML vector height，不是实测或 3 m raster；
  • release 未明确 roof statistic/vertical datum，必须保持 VERTICAL_REFERENCE_NOT_EXPLICIT_IN_RELEASE；
  • 所有面积与 IoU 在 EPSG:32649 计算；任意相交不能直接赋值；
  • 主筛选 IoU 0.50 仅为未校准的 screening gate，必须同时报告 0.75 IoU 与 0.50/0.90 target-area coverage 敏感性；
  • 全局一对一冲突、无匹配与歧义必须保留，禁止静默补高或写回 Overture；
  • 33 分区 RMSE 1.9–14.6 m 和中国 RMSE 13.17 m 只可作为区域先验，不可作为石牌单栋 误差条；
  • schema/QC 通过后仍保持 MATCH_QC_COMPLETE_SIMULATION_BLOCKED，直至独立本地高度验证、 覆盖门槛和许可审查完成并另建 promoted asset。

3. V1/V2 必需测试

  1. 无源、无边界通量时总水量守恒；
  2. 纯导热平板与解析/高精度参考解比较；
  3. 常量场在平流扩散下保持常量；
  4. 一个脉冲场的输运方向和数值扩散正确；
  5. 单建筑太阳阴影位置与几何参考一致；
  6. 夜间短波严格为零或在浮点容差内为零；
  7. 干表面蒸发受可用水限制并归零；
  8. 饱和空气下蒸发受到抑制；
  9. 降雨输入、截留、下渗、径流、蒸发和库存闭合；
  10. 时间步减半与网格加密后的核心指标变化收敛；
  11. 同一输入、配置、代码哈希与种子重复运行一致；
  12. 边界缓冲区变化不应主导核心分析区结果。

具体容差由浮点精度、离散阶数和基准误差在实现阶段登记，不在此设计中伪造统一阈值。

3.1 当前实现的稳定性门槛（审计说明）

src/urban_microclimate/config.py 当前使用以下定义：

S_h = 1/dx^2 + 1/dy^2 + 1/dz^2
Nu_thermal = dt_internal * D_thermal * S_h
Nu_humidity = dt_internal * D_humidity * S_h
dt_diff = diffusion_limit / (max(D_thermal, D_humidity) * S_h)

扩散时间步公式中没有额外的因子 2。默认 diffusion_limit=0.45，配置层限制其位于 (0, 0.5]。稳定步长还同时取决于平流 CFL 门槛和表面交换/辐射时间尺度门槛；外部时间步可被自动细分为多个内部步。

这些是实现的确定性运行门槛，只能证明运行遵守已编码的无量纲数限制。它们不构成离散格式稳定性定理、时间/空间收敛证明或完整耦合模型的科学验证。进入 V2 前仍必须完成时间步减半、网格加密、制造解/解析基准和守恒误差分析，并报告指标变化，而不是仅报告门槛通过。

4. 现场校准设计

温度

  • 固定站：2 m 空气温湿度，需辐射屏蔽和通风条件记录；
  • 表面：红外测温或热红外遥感，需要发射率和过境时刻；
  • 垂直/空间：移动测量可补足，但要处理时间漂移与传感器响应；
  • 不同观测类型分别验证，不能用地表温度校准空气温度后称两者都准确。

蒸发/蒸散

  • 优先：涡度协方差潜热通量或称重式蒸渗仪；
  • 次级：表面水量收支、土壤水分变化与能量平衡估算；
  • 卫星 ET 产品只能作为空间/日尺度间接对比，需要处理像元支持域；
  • 若没有蒸腾模块，观测总 ET 与模型裸地/表面蒸发不能直接一一比较。

参数分组

  1. 几何/材料：高度、反照率、发射率、热参数；
  2. 输运：风场和湍流扩散；
  3. 水文：持水、下渗、径流；
  4. 蒸发：气动/表面阻力；
  5. 辐射：云量到短长波的参数化。

逐组校准、保留物理边界，并报告可识别性。避免一次性自由拟合全部参数造成等效性与过拟合。

5. 数据切分

  • development：管线开发，可反复查看；
  • calibration：冻结目标函数后估计参数；
  • validation：冻结代码与参数后一次性评价；
  • stress/OOD：极端热、降雨后、不同风向和缺测故障；
  • 可选 external：另一地点。

按连续时段/天气事件分组切分，不能随机打散相邻分钟造成时间泄漏。建筑/材料先验和验证观测的来源依赖需要登记。

6. 评价指标

温度

MAE、RMSE、mean bias、相关系数、日最高/最低温误差、分时段/天气类型误差、空间结构误差。应分别报告空气温度与表面温度。

蒸发

累计量 bias、MAE/RMSE、相关性、日总量误差、降雨后衰减曲线误差、能量闭合残差。若观测是潜热通量，需用一致潜热常数和符号换算。

数值与系统

质量/能量闭合、最大 CFL、失败率、运行时间、峰值内存、单位模拟时长成本、恢复能力、输入覆盖率。

同时报告误差分布、bootstrap 区间与失败案例。评价阈值在看到验证集结果前由用途和仪器精度预注册。

7. 跨字段安全规则

7.1 当前 SimulationConfig

simulation_config.schema.json 覆盖单字段类型、默认值和范围；当前 SimulationConfig.validate() 仍是执行前的事实门槛，并额外检查有限值、building_max_height_m >= building_min_height_m、自动子步上限等条件。JSON Schema 验证不能替代运行时稳定性报告。

7.2 目标富契约

以下规则属于尚未接线的 Scenario/RunRequest/EvidenceBundle 目标设计；JSON Schema 之外仍需要确定性检查：

  • end_time > start_time，强迫必须覆盖含 spin-up 的全时段；
  • 分钟输出间隔必须是聚合器可处理的正整数秒；
  • dx/dy/dz 与域范围产生的网格数不得超过配置预算；
  • 建筑最高点必须低于模型顶边界并保留缓冲层；
  • height_reference 与 DEM 垂直基准一致；
  • 降雨 rate/accumulation 必须与 interval_seconds 配套；
  • 云量和湿度范围合法；风速非负且风向/分量语义唯一；
  • evapotranspiration 输出要求植被蒸腾模块和相应参数已启用；
  • 任何资产哈希不匹配均拒绝运行；
  • 正式/长时运行需要显式批准，dry-run 不得标记为科学模拟；
  • 失败或诊断缺失的运行不得进入 SUCCEEDED。

7.3 最小可执行接线路线（尚未实现）

  1. 在 CLI/API 入口先按 run_request.schema.json 校验 RunRequest，并解析不可变 scenario_ref/config_ref；
  2. 第一阶段只允许 config_ref 指向已通过 simulation_config.schema.json 和 SimulationConfig.from_dict 的合成运行配置；
  3. 按 scenario.schema.json 校验 Scenario，但桥接器必须明确拒绝当前 runner 无法消费的 DEM、建筑和气象资产，不能假装这些资产已经进入模型；
  4. 实现一个确定性 compatibility validator，核对 Scenario 的网格/时间意图、RunRequest seed/资源上限与 active SimulationConfig 是否一致；
  5. 只有兼容检查通过时，才把 SimulationConfig 映射交给现有 runner；现有代码仍是合成域执行器；
  6. 运行后用独立 normalizer 将当前 manifest/metrics/artifacts 转换为目标 EvidenceBundle，并逐字段绑定哈希、失败状态与局限；
  7. 为正向合成桥接、资产场景拒绝、引用/哈希错误、资源超限和失败 normalizer 增加测试后，才可宣称“最小接通”。

当前代码代理已实现其中的受控 bounded-synthetic 子集：项目根引用、资格/资源门槛、合成 runner 调用和 EvidenceBundle normalizer。它没有实现通用 schema 自动校验或真实数据 adapter； preflight_only 场景仍被安全拒绝。以下真实资产路线仍是待实现能力。

7.4 真实资产 manifest 与石牌 pilot（仅预检）

schemas/asset_manifest.schema.json 要求每个资产记录远端 URI、本地路径、字节数、 SHA-256、media type、CRS、时间、单位、许可、查询、质量和局限。五类必需角色通过 contains 约束，资产总数不设固定上限。download_status=not_downloaded 时本地路径、 字节数和哈希必须为 null；不得为满足 schema 而散列 URL、空文件或描述文字冒充数据哈希。

scenarios/shipai_microclimate_pilot/ 的 Scenario/RunRequest 均标记 execution_eligibility=preflight_only，RunRequest 因此只能是 mode=dry_run 且不得附正式 批准。引用路径统一相对于 urban_microclimate/ 项目根解析。当前 asset-preflight 可读取 manifest 并输出 PREFLIGHT_ONLY_NOT_SIMULATION；bridge-run 会拒绝该 RunRequest 并且不创建 run 目录。RunRequest 自身仍不是通用真实数据 dry-run 路由。

本地 data/shipai_pilot/asset_manifest.json 已通过 schema 和 6 个文件的 bytes/SHA-256/ 基础内容检查，合计 71,494 bytes；Scenario 绑定该 manifest 的 SHA-256。这个结果只证明项目内 文件与 manifest 一致。建筑 height 为 0/65、楼层为 2/65，且 NASA POWER 降雨响应元数据与 产品页常规单位说明存在待 adapter 决策的语义冲突，因此执行资格仍是 preflight_only。

第五轮的 DataAdapter/NormalizedPilotBundle 契约将该冲突显式化：小时响应按 hourly_mean_rate_expressed_as_mm_per_day 解释，每小时深度为 value/24；按 UTC 日合计后与 Daily API 比较。2024-06-01/02 residual 分别为 0.00125/0 mm，使用只针对两位小数输出 量化的保守绝对容差 0.01 mm/day。此检查通过只允许生成规范化强迫，不解除建筑高度 0/65 的 FAIL_CLOSED 仿真阻断。完整定义见 docs/data_adapter_contract.md。

在未来实现中，manifest 的结构通过后还必须执行：安全路径、角色唯一性、远端目录与许可、 本地 bytes/hash/media type、CRS/垂直基准、空间时间覆盖、单位/累计语义、原生分辨率、资源 预算和 adapter 能力检查。任何粗分辨率强迫都要保留原生分辨率与边界标记，不能因重采样到 细网格而宣称获得街谷观测。完整门槛见 docs/real_data_preflight.md。

content_summary 的跨字段一致性也由确定性校验器负责：non_null_count <= total_count， 非空 fraction 应与两者之比一致，矢量属性的 total_count 应与 feature count 一致，栅格 dimensions 的乘积应与有效/缺测计数口径可解释。JSON Schema 只限制单字段类型和范围， 不证明这些统计是从文件复算得到的。

8. 报告纪律

每个数值结论绑定 run_id、场景/配置/输入/代码哈希、指标定义、单位、空间范围、时间窗与质量标志。报告使用“在给定模型、边界与参数下”的条件表达；相关性、敏感性和模型内消融不得自动提升为现实因果。

9. 有界合成时间/空间敏感性筛查（target-only）

第七轮新增 sensitivity_experiment_spec.schema.json 和 sensitivity_experiment_result.schema.json，把 V1 中“时间步减半、网格加密”的前置筛查写成 机器可读、失败关闭契约。它当前是 TARGET_DESIGN_NOT_RUNTIME_WIRED，不代表 CLI、API 或 experiments/sensitivity_r7 已接线，也没有提高验证等级。

主时间族必须关闭自动子步，以相同网格/总时长/seed/输入/强迫/物理参数比较 6 s 与 3 s； 若自动子步改变 effective internal dt，则只能作控制实验。主空间族必须使用平坦、均匀、 无建筑合成域，保持共同 physical extent 并整数加密；当前按网格重新随机生成的程序化建筑 不具备嵌套几何，只可作 input-pipeline robustness，不得用于空间收敛判断。

可比输出只包括最终空气/表面均温、累计蒸发面均和水/能量残差；逐 voxel 细节不直接比较。 阈值须在读结果前注册，不得事后调节。满足阈值只能标 SENSITIVITY_SCREEN_PASS/FAIL，仍是 engineering screen，不是 convergence proof、GCI、科学 验证或生产准入。完整语义和确定性 validator 待办见 docs/bounded_sensitivity_contract.md。