From 42026cd01eab641981c22c99807b484f4607a0fc Mon Sep 17 00:00:00 2001 From: Xiao Chen Date: Sat, 12 Sep 2026 08:59:37 +0800 Subject: [PATCH] docs: add typical reproduction program guide --- README.md | 3 +- README_zh-CN.md | 3 +- manifests/FILE_INVENTORY.md | 10 +- manifests/sha256-manifest.json | 28 ++- reproducibility/README.md | 1 + reproducibility/TYPICAL_PROGRAMS.md | 111 ++++++++++ reproducibility/TYPICAL_PROGRAMS_zh-CN.md | 234 ++++++++++++++++++++++ 7 files changed, 376 insertions(+), 14 deletions(-) create mode 100644 reproducibility/TYPICAL_PROGRAMS.md create mode 100644 reproducibility/TYPICAL_PROGRAMS_zh-CN.md diff --git a/README.md b/README.md index 31aa0cc..77b0f4b 100644 --- a/README.md +++ b/README.md @@ -81,7 +81,8 @@ The dataset is too small for industrial or universal molecular generalization. D | [`manuscripts/`](manuscripts/README.md) | Evidence matrix and bilingual publication positioning; no pre-submission manuscript drafts are included | | [`ai4s-agent/`](ai4s-agent/README.md) | Agent architecture, capabilities, evaluation, governance, and limitations | | [`software/`](software/README.md) | Public LFMO/conditional-SCF implementation and 69 focused tests | -| [`reproducibility/`](reproducibility/README.md) | Runtime instructions and WSL 2 platform boundaries | +| [Typical reproduction programs](reproducibility/TYPICAL_PROGRAMS.md) | Select evidence checks, conditional-SCF tests, or downloadable QM reruns by cost, with step-by-step computation notes | +| [`reproducibility/`](reproducibility/README.md) | Full runtime instructions, environments, and WSL 2 platform boundaries | | [`figures/`](figures/README.md) | Project-authored overview figure | | [`science-v0.2/`](science-v0.2/README.md) | Self-contained `v0.2.0` configurations, selected machine results, decisions, reports, rebuild scripts, tests, and hashes | | [`science-v0.3/`](science-v0.3/README.md) | Published seven-work-package `v0.3.0` scientific-closure package; preserves `v0.1.x`, `v0.2.0`, and P01-P14 unchanged | diff --git a/README_zh-CN.md b/README_zh-CN.md index 61a5d8b..aeb12a8 100644 --- a/README_zh-CN.md +++ b/README_zh-CN.md @@ -81,7 +81,8 @@ AI4OrgChem是一个面向有机结构基础理论独立计算重构与证据评 | [`manuscripts/`](manuscripts/README.md) | 证据矩阵和双语发布定位 | | [`ai4s-agent/`](ai4s-agent/README.md) | Agent架构、能力、评估、证据治理和限制 | | [`software/`](software/README.md) | LFMO/条件SCF公开核心实现和69项测试 | -| [`reproducibility/`](reproducibility/README.md) | 复现说明和WSL 2平台边界 | +| [典型程序复算入口](reproducibility/TYPICAL_PROGRAMS_zh-CN.md) | 按计算难度选择证据核验、条件SCF测试和可下载QM复算，并查看逐步计算说明 | +| [`reproducibility/`](reproducibility/README.md) | 完整复现说明、运行环境和WSL 2平台边界 | | [`figures/`](figures/README.md) | 项目自行生成的总览图 | | [`science-v0.2/`](science-v0.2/README.md) | 自包含`v0.2.0`配置、精选机器结果、判定、报告、重建脚本、测试与哈希 | | [`science-v0.3/`](science-v0.3/README.md) | 已发布的七工作包`v0.3.0`科学闭合包；保持`v0.1.x`、`v0.2.0`及P01-P14不变 | diff --git a/manifests/FILE_INVENTORY.md b/manifests/FILE_INVENTORY.md index b98e76d..272434c 100644 --- a/manifests/FILE_INVENTORY.md +++ b/manifests/FILE_INVENTORY.md @@ -2,7 +2,7 @@ 本清单记录GitHub洁净仓库中的实质内容文件。生成型SHA清单和本文件自身不反向列入表格。 -- 实质内容文件：562 +- 实质内容文件：564 - 状态：版本化发布快照；内容变更后必须重新生成并验证 | 文件 | 角色 | 字节 | SHA-256 | @@ -164,16 +164,18 @@ | `project/RESEARCH_ITEMS_zh-CN.md` | project-narrative | 1939 | `508c64832f3b075a9d073e33badd35be764012eebb94624fc7966fa2b03b143f` | | `project/RESEARCH_VALUE_zh-CN.md` | project-narrative | 1319 | `7308230ee6f5dd7009de88e0483b3ff298baa2a438d8f99fc010103e24b80c5b` | | `project/V0.3.0_POST_RELEASE_ERRATUM_2026-09-08.md` | project-narrative | 7037 | `2ea92085a7bab6b235f75ca06bb27b97162d00656395f879309da42a48df3c9d` | -| `README.md` | repository-root | 23487 | `357775c4f596c2b62e819d2d6ff615e9d97550e21c3d91f2e0adcbf55cda89e5` | -| `README_zh-CN.md` | repository-root | 9897 | `7e51c54b7b3fdd8b9fd406da18423abd00bdea31d5fbf1775874a91bcce86cc8` | +| `README.md` | repository-root | 23700 | `4fc35159d35c2fa78636e8c37c3b3a913ab8e0b111c7f268ebc71dcc0f46f090` | +| `README_zh-CN.md` | repository-root | 10096 | `410b441037c67283cafa4b170a774ff0437ce620d3143087a6710727d17689bb` | | `RELEASE_NOTES_v0.3.1.md` | repository-root | 4739 | `1ff7d081ebf80aff8fd08b670b0117b2f5416268ee08e972572a2942635b56b0` | | `reproducibility/conda-linux-64.explicit.txt` | reproducibility | 18332 | `543abce03ee369526d83016126d7a0b7a82de48e0ef3356d3877289af90f5637` | | `reproducibility/environment.yml` | reproducibility | 214 | `13ae5c398dd95bf2d841fe89c4180cdd98d6d8360618de98ac3f68df27be50a6` | | `reproducibility/PLATFORM_MATRIX_EN.md` | reproducibility | 1963 | `1ea2cc5909ef145c93c5dcdc9c3bfaefb1726bc4c51ea47f57134fefcb5141cd` | | `reproducibility/PLATFORM_MATRIX_zh-CN.md` | reproducibility | 1773 | `60cd3af1c440d40f30ef58b54b35bec5c7ae764faec54ef9dbc70bb32863fa88` | -| `reproducibility/README.md` | reproducibility | 1054 | `176c783f5614c0f0bf2d61f42a02fc1dce2f782980120ab9cd0320ca81b03274` | +| `reproducibility/README.md` | reproducibility | 1259 | `89117413d55dfeeb8887e444c8bd85715d701a94e4a416cc5c9b579bee73da39` | | `reproducibility/RUNBOOK_EN.md` | reproducibility | 2854 | `2c7831ca9ee5f18ca597c66897f2f5d5e79cf766157442ee7d8e19706b5c9335` | | `reproducibility/RUNBOOK_zh-CN.md` | reproducibility | 3133 | `eeb5267031e04c8bc3f3585a2934000773c0ea966395c146c0c8a5a2fe7a43e8` | +| `reproducibility/TYPICAL_PROGRAMS.md` | reproducibility | 8079 | `112593abdaa36bdf8cb598f210f894f3d4533ec1cb64c540b8ea251740f495dd` | +| `reproducibility/TYPICAL_PROGRAMS_zh-CN.md` | reproducibility | 9696 | `630556aecb43051c26ee03b08a1ca51e9f566b9c528062add50b9b02ab8ed13f` | | `reproducibility/wsl/activate-ai4orgchem-public.sh` | reproducibility | 1475 | `5361fab00ebc6c614dfc191fffb4fb5c1eb0690ab862ad27000359347709cb2e` | | `reproducibility/wsl/ai4orgchem-verify` | reproducibility | 929 | `7eec73ec0269e9549a238707c6edf792a3bbae8161b72d714ba84abe3c43dc92` | | `reproducibility/wsl/README.md` | reproducibility | 1742 | `afb4d76e6f525e4b55036a446867d6ecc47b1657d7f17f6303062f4031ad832c` | diff --git a/manifests/sha256-manifest.json b/manifests/sha256-manifest.json index c2f8945..95413cf 100644 --- a/manifests/sha256-manifest.json +++ b/manifests/sha256-manifest.json @@ -870,8 +870,8 @@ { "path": "manifests/FILE_INVENTORY.md", "artifact_role": "repository-root", - "bytes": 89442, - "sha256": "c88bf28a90ea9669fbfcfb85eba24c4256f31141ce06b09548dd701df87f1f29" + "bytes": 89721, + "sha256": "969ef3e554c3388a71138d1c775a8ee6335fcdf08db7c13e08f8ecc3759240bf" }, { "path": "manuscripts/P01-P14_evidence_matrix_zh-CN.md", @@ -954,14 +954,14 @@ { "path": "README.md", "artifact_role": "repository-root", - "bytes": 23487, - "sha256": "357775c4f596c2b62e819d2d6ff615e9d97550e21c3d91f2e0adcbf55cda89e5" + "bytes": 23700, + "sha256": "4fc35159d35c2fa78636e8c37c3b3a913ab8e0b111c7f268ebc71dcc0f46f090" }, { "path": "README_zh-CN.md", "artifact_role": "repository-root", - "bytes": 9897, - "sha256": "7e51c54b7b3fdd8b9fd406da18423abd00bdea31d5fbf1775874a91bcce86cc8" + "bytes": 10096, + "sha256": "410b441037c67283cafa4b170a774ff0437ce620d3143087a6710727d17689bb" }, { "path": "RELEASE_NOTES_v0.3.1.md", @@ -996,8 +996,8 @@ { "path": "reproducibility/README.md", "artifact_role": "reproducibility", - "bytes": 1054, - "sha256": "176c783f5614c0f0bf2d61f42a02fc1dce2f782980120ab9cd0320ca81b03274" + "bytes": 1259, + "sha256": "89117413d55dfeeb8887e444c8bd85715d701a94e4a416cc5c9b579bee73da39" }, { "path": "reproducibility/RUNBOOK_EN.md", @@ -1011,6 +1011,18 @@ "bytes": 3133, "sha256": "eeb5267031e04c8bc3f3585a2934000773c0ea966395c146c0c8a5a2fe7a43e8" }, + { + "path": "reproducibility/TYPICAL_PROGRAMS.md", + "artifact_role": "reproducibility", + "bytes": 8079, + "sha256": "112593abdaa36bdf8cb598f210f894f3d4533ec1cb64c540b8ea251740f495dd" + }, + { + "path": "reproducibility/TYPICAL_PROGRAMS_zh-CN.md", + "artifact_role": "reproducibility", + "bytes": 9696, + "sha256": "630556aecb43051c26ee03b08a1ca51e9f566b9c528062add50b9b02ab8ed13f" + }, { "path": "reproducibility/wsl/activate-ai4orgchem-public.sh", "artifact_role": "reproducibility", diff --git a/reproducibility/README.md b/reproducibility/README.md index a631261..c13cf5e 100644 --- a/reproducibility/README.md +++ b/reproducibility/README.md @@ -2,6 +2,7 @@ 本目录提供平台中立的CPU环境和明确运行手册： +- [`TYPICAL_PROGRAMS_zh-CN.md`](TYPICAL_PROGRAMS_zh-CN.md) / [`TYPICAL_PROGRAMS.md`](TYPICAL_PROGRAMS.md)：按成本选择典型程序，并逐步解释输入、计算、输出、门禁和科学边界； - `environment.yml`：Python、NumPy、SciPy、PyYAML、pytest及PySCF的最小环境； - `conda-linux-64.explicit.txt`：2026-08-12权威WSL科研环境的Conda层显式包URL与哈希快照；本地路径已脱敏，且不冒充后续GPU环境或pip层的完整锁； - `RUNBOOK_EN.md` / `RUNBOOK_zh-CN.md`：冻结证据验证、公开软件测试和适用边界； diff --git a/reproducibility/TYPICAL_PROGRAMS.md b/reproducibility/TYPICAL_PROGRAMS.md new file mode 100644 index 0000000..d995eef --- /dev/null +++ b/reproducibility/TYPICAL_PROGRAMS.md @@ -0,0 +1,111 @@ +# Typical Reproduction and Evidence-Verification Programs + +[中文](TYPICAL_PROGRAMS_zh-CN.md) + +This page gives chemistry, quantum-chemistry, and computational-chemistry readers controlled entry points into the AI4OrgChem workflow: **scientific question → frozen protocol → electronic-structure calculation → numerical gates → machine result → scoped conclusion**. + +> “Verification” here is not certification of the monograph. `PASS` means only that a specified computation or consistency check satisfied its registered inputs, methods, and tolerances. + +## Choose a level + +| Level | Entry point | QM executed | Typical resources | Status | +|---|---|---:|---|---| +| L0 | Frozen P01–P14 evidence verification | No | Standard Python; seconds | **Runnable** | +| L1 | P09 conditional-SCF core tests | Small tests | CPU; usually minutes | **Runnable** | +| L2 | P14 fixed-geometry technical smoke | Yes, STO-3G | WSL2; 8 threads | **Runnable** | +| L3 | P14 fixed-geometry scientific-level reproduction | Yes, B3LYPG/6-31G(d) | WSL2; 8 threads; adequate memory | **Runnable** | +| L4 | P14 five-parameter production optimization | Yes; expensive | WSL2; 8 threads; at least 13 GiB available memory | **Runnable; advanced** | + +P09 cyclobutadiene smoke, the P10 benzene BLA scan, and the complete P09 aromatic-energy reproduction are the next public packaging targets. They are not shown with pretend commands before isolated output handling, dependency completion, and clean-clone execution pass. + +## Common setup + +The canonical scientific platform is **WSL 2 / Ubuntu 24.04**. From the repository root: + +```bash +micromamba create -f reproducibility/environment.yml # only if absent +source reproducibility/wsl/activate-ai4orgchem-public.sh +cd software +python -m pip install -e ".[science,test]" +cd .. +``` + +See the [English runbook](RUNBOOK_EN.md) and [platform matrix](PLATFORM_MATRIX_EN.md). Reproduction outputs belong under the Git-ignored `runs/reproduction/`; they must never overwrite frozen files under `evidence/`. + +## L0 — frozen P01–P14 evidence verification + +Purpose: verify that all fourteen published machine records can be read and that proposition IDs, verdicts, citations, key boundary states, and aggregate counts are internally consistent. No QM is rerun. + +Process: enumerate P01–P14 → validate JSON/JSONL structure → compare frozen verdicts with the master statistics → check key P11/P12/P14 states → emit counts and status. + +```bash +python software/scripts/validate_public_evidence.py +python software/scripts/validate_evidence_navigation.py +``` + +Expected output includes `status: PASS`, `propositions_checked: 14`, and `propositions_navigated: 14`. This verifies the published evidence package, not the physical correctness of the underlying calculations or peer-review status. + +## L1 — P09 conditional-SCF core tests + +Purpose: test the source-aligned infrastructure used by P09/P14: AO sigma/pi identity, fragment boundaries, Fock/overlap masking, exchange-integral classes, conditional SCF, and independent energy assembly. + +Process: construct test matrices or PySCF AO objects → classify sigma/pi AOs → attach pi-fragment labels → zero registered cross-fragment Fock/overlap blocks → apply the frozen 15 exchange-integral classes → iterate conditional SCF → assemble one-electron, Coulomb, exchange, and nuclear terms → test electron count, energy closure, generalized commutator, and density idempotency. + +```bash +cd software +python -m pytest -p no:cacheprovider \ + tests/test_p09_conditional_scf.py \ + tests/test_p09_energy_assembly.py \ + tests/test_p09_eri_mask.py +cd .. +``` + +All tests must pass. These are mathematical-contract tests, not a complete molecular reproduction of benzene ESE or cyclobutadiene ADE. + +## L2 — P14 fixed-geometry technical smoke + +Purpose: use the small STO-3G basis to establish that C12H6 geometry reconstruction, AO classification, conditional SCF, and the energy ledger execute on the user's machine. + +Process: reconstruct planar D3h G/PLG source-proxy geometries from five published descriptors → ordinary closed-shell RKS at G → ordinary RKS anchor at PLG → sigma/pi classification and fragment mapping → conditional PLG SCF → technical endpoint → gates for 78 electrons, SCF convergence, reconstructed geometry, energy closure, commutator, and idempotency. + +```bash +python software/scripts/run_p14_benzotricyclobutadiene_smoke.py +``` + +Outputs are written under `runs/reproduction/p14/`. `smoke_gate_verdict` should be `PASS`, but the STO-3G value is implementation evidence only and is ineligible for the P14 scientific verdict. + +## L3 — P14 fixed-geometry scientific-level reproduction + +Purpose: recompute the P14 fixed-geometry endpoint at B3LYPG/6-31G(d) on the public G/PLG source-proxy geometries and compare it with the frozen `67.086899 kcal/mol` value. + +Process: hash public inputs → verify five-parameter reconstruction, atom order, planarity, and 78 electrons → ordinary G state → ordinary PLG density anchor → source-aligned conditional PLG state → direct-versus-memory-controlled energy equivalence → endpoint assembly → method, basis, SCF, electron-count, closure, commutator, idempotency, and memory gates. + +```bash +python software/scripts/run_p14_benzotricyclobutadiene_source_level_fixed_geometry.py +``` + +See the [P14 input identity statement](../evidence/P01-P14/P14/inputs/README.md). These are reconstructed source-proxy coordinates because the historical Cartesian coordinates were not published. + +## L4 — P14 five-parameter production optimization + +Purpose: optimize the five planar D3h parameters independently for ordinary G and conditional PLG, then test both the structural response `dDelta-r(GP)` and the optimized endpoint. + +Process: require at least 13 GiB available memory → generate frozen starts → optimize ordinary G at B3LYPG/6-31G(d) → qualify termination, gradient, and active bounds → optimize conditional PLG → repeat SCF, 78-electron, gradient, boundary, and conditional-state checks → calculate structure response and endpoint → issue `production_gate_verdict: PASS` only when every eligibility gate passes. + +```bash +python software/scripts/run_p14_benzotricyclobutadiene_production_optimization.py +``` + +Frozen references are `dDelta-r(GP) = 0.172204 Å` and `67.679719 kcal/mol`. Numeric proximity alone is insufficient: method, basis, convergence, gradient, bounds, electron count, and energy closure must all qualify. The calculation covers only the registered planar D3h five-parameter subspace. + +## Activation gates for the next entries + +- **P09 cyclobutadiene smoke:** fixed planar rectangle → ordinary G-like RKS → sigma/pi classification → two-fragment DSI SCF → 15 exchange classes → independent ledger → numerical gates. It is not the final VDE/ADE. +- **P10 benzene BLA scan:** same-protocol P09 G/GL endpoints → `delta Ee`/`delta EN` decomposition → fixed mean C–C and C–H distances → ordinary RKS at `delta=0, 0.01, 0.02, 0.04, 0.06 Å` → independent nuclear Coulomb sum → curvature and plus/minus symmetry checks. It supports only the tested pathway. +- **Complete P09 reproduction:** cyclobutadiene G/DSI and conditional GL paths → VDE/ADE; benzene G/three-fragment DSI → restricted GL/GE1 optimizations → `ESE=delta EA-3 delta EA1` → blind comparison with frozen anchors. + +Before activation, each entry must be included with its complete script and configuration, write only to `runs/reproduction/`, include geomeTRIC where required, contain no private paths or credentials, document resources, pass unit tests, pass a WSL2 clean-clone run, and reproduce the frozen evidence within registered tolerances. + +## Reporting an independent reproduction + +Include the repository tag or commit, OS, Python/PySCF versions, thread count, memory, exact command, SHA-256 of output JSON, `PASS/FAIL` status, and residual from the frozen result. Failed reproductions are scientifically useful and should not be discarded or replaced by success-only screenshots. diff --git a/reproducibility/TYPICAL_PROGRAMS_zh-CN.md b/reproducibility/TYPICAL_PROGRAMS_zh-CN.md new file mode 100644 index 0000000..e473e2d --- /dev/null +++ b/reproducibility/TYPICAL_PROGRAMS_zh-CN.md @@ -0,0 +1,234 @@ +# 典型程序复算与证据核验入口 + +[English](TYPICAL_PROGRAMS.md) + +本页帮助化学、量子化学和计算化学读者选择一个可控入口，观察AI4OrgChem如何把**科学问题、冻结协议、电子结构计算、数值门禁、机器结果和范围化结论**连接成可审计流程。 + +> 本页中的“核验”不表示认证原著理论。`PASS`只表示指定程序在登记输入、方法和容差内完成了相应计算或一致性检查。 + +## 先选择运行层级 + +| 层级 | 入口 | 是否运行QM | 典型资源 | 当前状态 | 适合读者 | +|---|---|---:|---|---|---| +| L0 | P01–P14冻结证据核验 | 否 | 普通Python，数秒 | **可运行** | 所有读者 | +| L1 | P09条件SCF核心测试 | 小型测试 | CPU，通常数分钟 | **可运行** | 方法与程序审查者 | +| L2 | P14固定几何技术烟测 | 是，STO-3G | WSL2、8线程 | **可运行** | 首次QM体验 | +| L3 | P14固定几何科学层级复算 | 是，B3LYPG/6-31G(d) | WSL2、8线程、充足内存 | **可运行** | 量子化学复核 | +| L4 | P14五参数生产优化 | 是，高成本 | WSL2、8线程、至少13 GiB可用内存 | **可运行；高级** | 深度独立复算 | + +P09环丁二烯烟测、P10苯BLA扫描和P09完整芳香能复算是下一批公开封装对象。它们的科学设计已冻结，但在完成独立输出目录、依赖补齐和洁净克隆实跑前，本页不提供可能误导用户的伪命令。 + +## 统一准备 + +权威科学平台是 **WSL 2 / Ubuntu 24.04**。从GitHub克隆或下载Release完整包后，在仓库根目录执行： + +```bash +micromamba create -f reproducibility/environment.yml # 仅在环境不存在时 +source reproducibility/wsl/activate-ai4orgchem-public.sh +cd software +python -m pip install -e ".[science,test]" +cd .. +``` + +环境创建、平台差异和安全边界见[中文运行手册](RUNBOOK_zh-CN.md)与[平台矩阵](PLATFORM_MATRIX_zh-CN.md)。所有复算输出写入被Git忽略的`runs/reproduction/`；不得覆盖`evidence/`中的冻结证据。 + +--- + +## L0：P01–P14冻结证据核验 + +### 科学目的 + +确认十四项公开结果文件可以被读取，命题编号、判定、证据引用和关键状态彼此一致。该入口不重新运行量子化学，不证明计算物理正确，只检查发布证据包的内部完整性。 + +### 计算过程 + +1. 枚举P01–P14机器结果； +2. 检查JSON/JSONL结构和命题编号； +3. 检查冻结分类与总表统计； +4. 检查P11、P12、P14等关键边界状态； +5. 输出命题数、通过数和总状态。 + +### 运行 + +```bash +python software/scripts/validate_public_evidence.py +python software/scripts/validate_evidence_navigation.py +``` + +### 预期输出与判读 + +预期包含`status: PASS`、`propositions_checked: 14`和`propositions_navigated: 14`。若失败，应先阅读错误指出的具体文件，不得通过修改验证器来迁就结果。 + +### 边界 + +该入口核验的是**已经发布的证据记录**，不是原始量子化学复算，也不是同行评审。 + +--- + +## L1：P09条件SCF核心实现测试 + +### 科学目的 + +检查P09/P14所用source-aligned条件SCF基础设施是否按定义处理AO的σ/π身份、片段边界、Fock/overlap屏蔽、交换积分类别和独立能量组装。 + +### 计算过程 + +1. 构造小型测试矩阵或PySCF AO对象； +2. 根据分子平面和AO方向把基函数分类为σ或π； +3. 给π轨道附加局域片段标签； +4. 将登记的跨片段Fock和overlap块置零； +5. 应用冻结的15类交换型二电子积分规则； +6. 迭代条件SCF； +7. 独立组装单电子、库仑、交换和核排斥分量； +8. 检查电子数、能量闭合、广义对易子和密度幂等性。 + +### 运行 + +```bash +cd software +python -m pytest -p no:cacheprovider \ + tests/test_p09_conditional_scf.py \ + tests/test_p09_energy_assembly.py \ + tests/test_p09_eri_mask.py +cd .. +``` + +### 预期输出与判读 + +pytest应全部通过。失败表示公开核心算法、运行库或平台出现差异，不能据此继续解释P09/P14科学结果。 + +### 边界 + +单元测试证明代码满足登记的局部数学合同；它不等同于苯ESE或环丁二烯ADE的完整分子复算。 + +--- + +## L2：P14固定几何技术烟测 + +### 科学目的 + +用较小的STO-3G基组确认C12H6体系、几何重建、AO分类、条件SCF和能量账本可以在用户机器上完整执行。 + +### 计算过程 + +1. 从原著公开的五个结构参数分别重建G和PLG的平面D3h `source-proxy`几何； +2. 在G几何运行普通闭壳层RKS； +3. 在PLG几何运行普通RKS，获得条件态初始密度； +4. 对PLG执行AO σ/π分类和片段映射； +5. 应用条件Fock/overlap及交换积分规则并收敛条件SCF； +6. 计算`E(ordinary@G)-E(conditional-PLG@PLG)`技术端点； +7. 检查78电子、SCF收敛、几何重建、能量闭合、对易子和幂等性。 + +### 运行 + +```bash +python software/scripts/run_p14_benzotricyclobutadiene_smoke.py +``` + +默认输出： + +- `runs/reproduction/p14/p14_benzotricyclobutadiene_fixed_geometry_smoke_v0.1.json` +- `runs/reproduction/p14/p14_benzotricyclobutadiene_fixed_geometry_smoke.md` + +### 预期输出与判读 + +`smoke_gate_verdict`应为`PASS`。数值可以用于检查实现和平台，但**不得**作为P14科学定判值，因为STO-3G不是登记的生产层级。 + +--- + +## L3：P14固定几何科学层级复算 + +### 科学目的 + +在B3LYPG/6-31G(d)层级，对公开的G/PLG `source-proxy`几何重算P14固定几何端点，并把用户结果与冻结值`67.086899 kcal/mol`比较。 + +### 计算过程 + +1. 读取并哈希公开G、PLG输入； +2. 验证五参数重建、原子顺序、平面性和78电子； +3. 计算普通G态； +4. 计算普通PLG锚点并形成初始密度； +5. 计算source-aligned条件PLG态； +6. 独立复核直接实现和内存受控实现的总能等价性； +7. 组装固定几何端点； +8. 检查方法、基组、SCF、电子数、能量闭合、对易子、幂等性和内存门禁。 + +### 运行 + +```bash +python software/scripts/run_p14_benzotricyclobutadiene_source_level_fixed_geometry.py +``` + +默认输出位于`runs/reproduction/p14/`。公开冻结输入及其身份说明见[P14输入说明](../evidence/P01-P14/P14/inputs/README.md)。 + +### 预期输出与判读 + +只有全部门禁通过时，该复算才可与冻结固定几何端点比较。小的末位差异应结合PySCF、BLAS和数值积分版本报告，不得静默改写容差。 + +### 边界 + +原著未公开完整历史Cartesian坐标；这里复算的是公开五参数重建的`source-proxy`，不是历史原厂程序身份复现。 + +--- + +## L4：P14五参数生产优化 + +### 科学目的 + +分别优化普通G态和条件PLG态的五个平面D3h结构参数，检查结构响应`dΔr(GP)`和优化能量端点是否同时满足P14资格门禁。 + +### 计算过程 + +1. 检查至少13 GiB可用内存和单任务运行约束； +2. 从冻结五参数生成G、PLG初始结构； +3. 在B3LYPG/6-31G(d)层级优化普通G态； +4. 检查优化终止原因、最大梯度和活动边界； +5. 在同一层级优化条件PLG态； +6. 再次检查SCF、78电子、最大梯度、活动边界和条件态数值闭合； +7. 计算`dΔr(GP)`及优化端点； +8. 只有全部资格项通过，才生成`production_gate_verdict: PASS`。 + +### 运行 + +```bash +python software/scripts/run_p14_benzotricyclobutadiene_production_optimization.py +``` + +该程序具有检查点，默认结果和报告写入`runs/reproduction/p14/`。运行期间不要并行启动其他中高内存QM作业。 + +### 预期输出与判读 + +冻结参考为： + +- `dΔr(GP) = 0.172204 Å`； +- 优化端点`67.679719 kcal/mol`。 + +数值接近并不自动等于通过；方法、基组、收敛、梯度、边界、电子数和能量闭合必须全部合格。 + +### 边界 + +该优化只覆盖登记的平面D3h五参数子空间，不宣称完成全笛卡尔频率、更宽对称性搜索、19分子面板或普遍应变芳香规律。 + +--- + +## 下一批入口的启用门禁 + +以下三个程序具有很高的展示价值，但只有完成全部门禁后才会在本页标记为“可运行”： + +### P09环丁二烯固定几何烟测 + +流程：固定平面矩形几何 → 普通G-like RKS → AO σ/π分类 → 两片段条件DSI SCF → 15类交换积分处理 → 独立能量账本 → 12项数值门禁。它只检验同一几何上的实现闭合，不替代最终VDE/ADE。 + +### P10苯BLA—核排斥扫描 + +流程：读取同协议P09 G/GL端点 → 分解`ΔEe`与`ΔEN` → 固定平均C–C及C–H长度 → 在`δ=0、0.01、0.02、0.04、0.06 Å`计算普通RKS → 独立核间库仑和 → 曲率与正负δ对称性检查。它支持受测路径上的机制分析，不单独证明普遍“核排斥主导”。 + +### P09完整苯/环丁二烯复算 + +流程：环丁二烯G优化与同几何DSI → 条件GL优化 → VDE/ADE组装；苯G优化与三片段DSI → GL与GE1受限优化 → `ESE=ΔEA-3ΔEA1` → 与盲冻结锚点比较。完整程序必须保留检查点、单任务资源限制和失败即停止策略。 + +启用前必须满足：脚本和配置进入精选包、所有输出重定向到`runs/reproduction/`、补齐geomeTRIC依赖、无私有路径或密钥、运行时资源说明完整、单元测试通过、WSL2洁净克隆实跑通过、结果与冻结证据在登记容差内一致。 + +## 如何提交独立复算结果 + +提交Issue时请附：仓库标签或提交哈希、操作系统、Python/PySCF版本、CPU线程、内存、实际命令、输出JSON的SHA-256、`PASS/FAIL`状态及与冻结值的残差。失败结果同样有科学价值，不应删除或只提交成功截图。