Files
hmandWorkBuddy d1a70fd142
CloudLab CI/CD / 门禁 doctor (push) Failing after 39s
CloudLab CI/CD / 单元测试 (push) Skipped
CloudLab CI/CD / 归档完整性 (push) Skipped
CloudLab CI/CD / 构建站点与归档 (push) Skipped
CloudLab CI/CD / 部署到 lab.hdtime.space(rsync) (push) Skipped
CloudLab CI/CD / 构建镜像并推送 Gitea 容器仓库 (push) Skipped
CloudLab CI/CD / 容器部署到 lab.hdtime.space (push) Skipped
CloudLab CI/CD / 发布版本(Tag) (push) Skipped
fix(science): 实验与数据验证的真实性/可靠性修复
跨平台可复现性:
- 新增 cloudlab-platform/conftest.py,Windows 本地自动回退数据根到仓库
- runner 增加 app_data():兼容服务器 DATA/app/data 与本地 DATA/cloudlab-web/app/data
- audit_domains 清单 dataDir 固定为服务器规范路径,路径序列化统一 POSIX
- check_chem01_rdkit 数据根回退到仓库(parents[3]),RDKit 独立验证真正运行
  (reference harness 从 incomplete 变为 pass,10 项检查 0 跳过)

数据推演与基线:
- datasets.json 同步上架后的 9 个新架位路径与 1 个文件大小,16/16 数据集可解析
- 重建缺失的 站点清单.csv(官方脚本生成 3438 文件 / 280.8MB),
  同步 files.json / datasets.json 的大小
- cases.json 基线随新数据更新(数据行 7381、离群候选 1264、浮点残差 3.55e-15)
- 浮点比较改为科学容差:WLS 稳健 CI 逐元素比较、驻留残差 1e-12、
  maintenance_used delta=1e-10、NumPy 交叉校验 1e-10
- 历史 artifact 的环境字段改为自洽校验,不再强制与当前 NumPy 版本一致
- Windows ntpath 对 /var/... 的 isabs 误判改用 PurePosixPath

验证(分批):domains 13/13、reference harness 5/5、
reference_data01 9/9、其余 113 passed/575 subtests、fidelity 147/147

Co-Authored-By: WorkBuddy <noreply@workbuddy.ai>
2026-11-22 04:40:59 +08:00
..

validation/reference:独立求解器与参考数据交叉验证

本目录是 CloudLab 科研仿真平台的独立交叉验证套件,对应 P2 路线:对平台关键数值结果引入经验证的外部参考实现或独立数值方法复算,避免“平台自己算、自己断言”的自证循环。

1. 目的与边界

  • CHEM-01:用 RDKit(外部化学信息学库)独立计算 503 个 PubChem SDF 快照的 TPSA、HBD、HBA、可旋转键,与平台输出及 validation/cases.json 冻结期望对比。
  • BIO-02 / CHEM-04:用自写的高精度自适应积分器(Cash–Karp 5(4))和精确求积/求根,独立复算恒化器稳态、分批/补料分批动态、动态 PRCC,以及线性/正弦/阶跃环境 profile 的暴露指标。
  • 边界声明:只会验证“在给定模型方程、参数与输入数据下,实现是否算对”。它不验证模型本身是否符合真实生物/化学过程,也不把验证范围扩展到未抽样的分子、参数区域或其他实验操作。

2. 文件清单

文件 作用
check_chem01_rdkit.py CHEM-01 快照级 RDKit 交叉核对;JSON + 终端表格;已知分歧逐条解释
check_ode_independent.py BIO-02 动态 PRCC、CHEM-04 动态 profile 等 8 项独立数值复算;不导入平台代码
run_all.py 汇总两个 checker,写 latest.json;有 fail 时非零退出
latest.json 最近一次全量运行的机器可读快照(含版本、时间戳、逐项 pass/fail、max error)
README.md 本文件:版本、方法、容差、适用域、复现命令

3. 求解器、版本与许可

以下版本来自实际运行 python3 validation/reference/run_all.py 写入 latest.json 的 environment 字段:

组件 版本 许可 用途
CPython 3.11.2 PSF License 运行环境
RDKit 2022.09.3(Debian 包,/usr/lib/python3/dist-packages) BSD-3-Clause CHEM-01 的独立参考实现
NumPy 1.24.2 BSD-3-Clause 仅由 run_all.py 记录环境版本;验证脚本不直接使用
SciPy 未安装 — 见下

SciPy 不可用:目标环境没有 scipy,且 apt-get install -y --no-install-recommends python3-scipy 在下载 43.1 MB 包时失败(E: Failed to fetch ... Unable to connect to deb.debian.org:http:);按任务 timebox 放弃安装,未使用 pip。因此 BIO-02/CHEM-04 使用本仓库自写的 Cash–Karp 5(4) 自适应积分器,而不是 SciPy 的 solve_ivp。Cash–Karp 系数取自 Cash & Karp, ACM TOMS 16(3):201–222 (1990),实现代码为本目录自写,不包含第三方 ODE 库代码。

4. 数值方法与容差

4.1 CHEM-01(check_chem01_rdkit.py)

  • RDKit 读取 AtomLab/data/_pubchem_raw/<molecule>_3d.sdf:
    • HBD:Chem.MolFromMolFile(..., removeHs=False) 后 CalcNumHBD,保留 SDF 中的显式 H;
    • TPSA:Chem.RemoveHs 后 CalcTPSA(mol, includeSandP=True)(含 S/P 贡献);
    • HBA:CalcNumHBA(RDKit Lipinski SMARTS,仅作独立参考/对照,不替代平台的 N+O 定义);
    • 可旋转键:CalcNumRotatableBonds(RDKit 默认严格度);
    • 另计 N/O 元素数,用于核对平台解析器。
  • 平台函数(parse_sdf_structure、sdf_tpsa、sdf_hbond_donors、sdf_lipinski_hba、sdf_rotatable_bonds)只作为被测对象导入;任何期望值都不由它们生成。
  • 计数型断言(503 快照、322/501/348/496 等)的容差为 None,因为断言的是“与文档声明计数一致”,不是数值容差;数值型 TPSA 对照容差 0.05 Ų。
  • 通过项的 maxError 统一按“扣除已解释分歧后的未解释误差”报告;details.maxErrorAll 保留含已知分歧的原始最大差,避免把已知适用域问题藏起来。

4.2 BIO-02 / CHEM-04(check_ode_independent.py)

  • 积分器:Cash–Karp 5(4) 嵌入式 RK 对;6 阶段;误差估计 |y5-y4|,按 sqrt(mean_j(((y5-y4)/(atol+rtol*max(|y|,|y5|)))^2)) 归一化;步长因子 0.9*err^-0.2(接受时上限 5、下限 0.2;拒绝时上限 1、下限 0.1);hmax=0.5 h,输出网格处精确截断。
  • 默认 rtol=1e-9、atol=1e-12;恒化器长期积分用 rtol=1e-10;PRCC 轨迹用 rtol=1e-8、atol=1e-11(与平台 rtol=1e-6 明显更严)。
  • 非负钳制:分批/恒化器状态在每步接受后取 max(0, y);补料分批不钳制(保持体积/底物可积)。
  • 独立第二参考:稳态用解析式;环境 profile 用自适应 Simpson(eps=1e-12)+ 密采样/黄金分割求极值 + 二分求根求 γ=0.5 穿越;动态 PRCC 用独立平均秩、Gauss–Jordan 求逆、偏秩相关与 2000 次置换(p=(1+#{|ρ_perm|≥|ρ_obs|})/(B+1),最小 p=0.0005)。
  • 容差来自 validation/cases.json 的 tol:CHEM-04 环境 2e-4;动态 profile 1e-3;BIO-02 恒化器/分批 1e-3;PRCC 2e-3。所有 case 的期望字段逐项核对,任一超差即 fail。

5. 适用域与已知限制

  1. 仅覆盖 503 个有 SDF 的 PubChem 快照。数据目录另有 119 个只有属性 JSON、没有 3D SDF 的分子,不在本套件范围内。
  2. PubChem 缓存不是理论真值。缓存值来自 CACTVS,TPSA/HBA/可旋转键定义与 RDKit/平台均可能不同;chem01.tpsa_vs_cache 断言的是“平台与缓存按文档口径一致”,不是“平台与理论值一致”。
  3. TPSA 的 S/P 与芳香性启发式是主要分歧源。平台使用紧凑 Hückel 判芳香,RDKit 使用自身芳香性模型;5 个分歧分子已逐条记录(见 docs/VERIFICATION.md),不修改平台实现。
  4. HBD 语义差异:平台只统计带显式 H 的 N/O/S;CACTVS 缓存把 HF/HCl 的卤素 H 也算供体,RDKit 对 HF/HCl/H2O/H2S 均返回 0。三套口径不可混用。
  5. 平台 HBA 是刻意的 N+O 定义,与 CACTVS/RDKit 的 Lipinski SMARTS 不同;本套件核对“平台 N+O 与 RDKit 元素计数一致”,不宣称 HBA 数值与缓存一致。
  6. 可旋转键是上界启发式:平台单键非环且两端重原子度 ≥2 的规则会多计 7 个已知分子;与 RDKit 默认定义也不完全相同(469 相等/27 平台多/7 平台少)。
  7. BIO-02/CHEM-04 验证的是同一模型方程的另一个实现,不是模型与实验数据的拟合优度;只覆盖 cases.json 指定参数区域,不覆盖其他 op、产物抑制、氧气限制等未激活分支。
  8. 动态 profile 的 γ<0.5 时长 是平台 121 点离散口径:独立连续解与平台离散值可差最多约一个网格步长(0.05 h 量级),本套件同时报告 belowContinuous 供解释。
  9. PRCC 的次级参数对输出量化敏感:平台把 0.5 h 采样点 round 到 6 位小数并用 S<=1e-9 判耗尽,耗尽时间因此被量化到 0.5 h 网格附近;默认 rtol=1e-6 的求解器噪声会改变 Ks/Y 的次级 PRCC。最强参数 μmax 的结论可独立复现,但次级参数不应被宣称为已完全独立验证(详见 docs/VERIFICATION.md §5.3)。
  10. 不覆盖:服务端/队列/复现逻辑、其他实验 op、全量测试套件、3D 构象/量化计算、质谱同位素包络的独立验证。

6. 复现命令

在 cloudlab-platform 仓库根目录运行(命令中的相对路径即仓库内路径):

# 1) 快速回归测试(约 5 s,缺 RDKit/数据目录时 skip)
python3 -m unittest tests.test_reference_harness -v

# 2) 单独跑 CHEM-01(约 0.7 s,503 分子)
python3 validation/reference/check_chem01_rdkit.py --json /tmp/chem01.json

# 3) 单独跑 BIO-02/CHEM-04(约 5 s;--no-prcc 约 0.2 s)
python3 validation/reference/check_ode_independent.py --json /tmp/ode.json
python3 validation/reference/check_ode_independent.py --no-prcc

# 4) 汇总并刷新 latest.json(约 5.7 s)
python3 validation/reference/run_all.py

可选参数:

  • run_all.py --quick:CHEM-01 只取 60 个分子并跳过 PRCC,适合开发时快速检查;
  • run_all.py --no-prcc:跳过两个 PRCC 案例;
  • run_all.py --json <path>:写到指定 JSON(默认覆盖本目录 latest.json);
  • 数据目录默认 /var/www/cloudlab,可用 CLOUDLAB_DATA=<path> 覆盖;脚本不接受也不硬编码本机仓库绝对路径。

退出码:0 全部通过;1 有 fail;2 有依赖缺失/跳过项(incomplete,不得当作已独立验证)。

7. latest.json 结构

{
  "schema": "cloudlab-reference-validation/1",
  "generatedAt": "UTC ISO8601",
  "durationSeconds": 5.7,
  "status": "pass",              // pass | fail | incomplete
  "environment": { "python": "...", "rdkit": "...", "numpy": "...", "scipy": null, "dataDir": "..." },
  "summary": { "totalChecks": 17, "pass": 16, "fail": 0, "skip": 0, "info": 1 },
  "checks": [
    { "id": "chem01.tpsa_vs_rdkit", "status": "pass", "maxError": 0.0, "tolerance": 0.05, ... }
  ]
}

checks[] 的 maxError 对数值型检查是“扣除已解释分歧后的最大绝对误差”;计数型检查的 tolerance 为 null,表示该项断言的是计数而非数值容差。details 中保留逐分子/逐字段证据与已知分歧说明。