Replace Python numerical kernels with native C execution

docs/other/C内核第一版实施记录.md

@@ -0,0 +1,66 @@
+# C 内核第一版实施计划与记录
+
+> 本文记录迁移当时的阶段结果；Python 参考实现已于 2026-09-10 退役，当前入口与保留范围见 [退役记录](Python数值实现退役记录.md)。
+
+2026-09-09。状态：第一版已完成并验证；尚未将全组件库切换为原生默认后端。
+
+## 分步计划
+
+| 顺序 | 工作 | 第一版交付 | 状态 |
+| --- | --- | --- | --- |
+| 1 | 冻结边界与模型合同 | skill-test 的组件能力表、输入与运行设置、共同 XML 前端 | 已完成 |
+| 2 | 开发 C 组件内核与模型编译器 | 由 XML 拓扑生成状态、端口、计算顺序及系统 C 源码；不依赖固定组件编号 | 已完成 |
+| 3 | 接入原生积分执行 | 独立 EXE，RK45 与 CVODE BDF；进度、取消、错误、结果和编译缓存 | 已完成 |
+| 4 | 接入 Python 并精简重复代码 | 统一后端分派；保留模型定义、有效的 Python 参考与兼容路径，移除被替代的重复入口逻辑 | 已完成 |
+| 5 | 验证第一版 | 同状态 Python/C 方程对照、拓扑通用性、API 回归、skill-test 完整求解与计时 | 已完成 |
+
+## 本版范围
+
+- 首批覆盖 skill-test 使用的 12 类组件：氦气介质、PNCH023、PNCH012、PNVO001、PNPL01、STEP0、UD00、FORC、PNRP17、MECMAS21、F000、LSTP00A。具体支持的参数模式由编译器检查，不将组件类型覆盖误报为所有模式覆盖。
+- Python 负责 XML 校验、网络检查、代码生成、编译缓存与任务管理；生成程序中的物性、流量、机械、积分与事件处理不回调 Python。
+- 用户要求本轮不调整雅可比：现有 Python 雅可比、着色与切向代码保持不变；原生 BDF 使用本机 SUNDIALS 7.4.0 默认稠密数值雅可比，不添加自定义雅可比或矩阵优化。
+- `test/skill-test.json` 是前次 RK45 / maxStep=0.001 s 测试副本；下载原件是 BDF / maxStep=0.02 s。本轮分别标注两组设置，不混用时间；仿真均为 0–10 s，仅数值验证，无绘图。
+- C 组件从现有 Python 方程及已验证的 C 原型迁移，核对单位、符号、事件和模式；不直接复制原型中的固定模型连接或编号。
+- 本版能力以显式后端开关启用。不支持的模型在积分开始前给出明确诊断；默认 Python 路径继续服务尚未迁移的组件。
+
+## 后续版本
+
+1. 扩大到管路、分支节点、更多物性和摩擦/接触模式；增加通用代数环执行。
+2. 完善参数与结构分离缓存、跨平台发布和更大模型验收。
+3. 用户另行授权后开展雅可比、稀疏矩阵和局部导数优化。
+
+## 实施结果
+
+### 代码与精简内容
+
+- 新增 `app/simulation/native_codegen/`：JSON/XML 输入适配、能力检查、模型 C 生成、构建缓存、隔离运行与 CLI。
+- 新增 `native/components/`、`native/runtime/`、`native/include/`：物性/阀流量/信号/接触/端挡原语，RK45 与 CVODE BDF，事件、采样和结果输出。
+- `app/main.py` 改为共用后端分派，移除入口内重复的求解器配置与 Python 系统构造。
+- 将通用结果和准备错误合同从 `generic.py` 抽到 `results.py`，C 结果适配不再为获取数据类型而导入整个 Python 求解系统；原模块保留导入兼容性。
+- 活动跟踪器增加原生汇总进度接口，直接接收真实 RHS/接受步计数，避免每次 C 求值都回调 Python。
+- Python 组件定义、仍在使用的示例 API 和参考求解器继续保留；没有把被其他模型调用的代码误判为无用代码删除。
+- 现有 Python 雅可比、着色、切向和矩阵求解逻辑未修改。
+
+### 验证
+
+执行 `python -m unittest tests.test_native_codegen tests.test_generic_system_xml_simulation tests.test_system_xml_v3 -q`，33 项测试全部通过。覆盖组件方程、逆向流、端挡试探、组件重命名/重排、增加独立支路、缓存、移除 Python PATH 后独立运行 EXE、取消、XML API 和既有 Python 路径。
+
+当前 Python 的完整 0–10 s RK45 对照已重跑；175 个变量、502 个时间点及求值次数、接受步、事件数全部与 C 对应，序列比较采用 `rtol=1e-9, atol=1e-9`。所有样本有限、系统质量守恒检查通过。
+
+首轮通用接口测试中的毫秒级心跳用例曾出现一次 Windows 时序波动；独立复核通过，最终上述完整 33 项测试也通过。未修改生产心跳行为或放宽断言。
+
+### skill-test 求解时间
+
+同机、预热一次后测三次取中位数，关闭轨迹采样与绘图；初始化、编译、结果投影和文件写入不计入求解时间。
+
+| 配置 | 最大步长 | rtol | 求解中位时间 | RHS 次数 |
+| --- | --- | --- | ---: | ---: |
+| 原生 RK45 | 0.001 s | 1e-6 | 0.2947735 s | 60,200 |
+| 原生 CVODE BDF | 0.02 s | 1e-6 | 0.0222788 s | 3,915 |
+| 原生 CVODE BDF，收紧精度检查 | 0.02 s | 1e-8 | 0.0152101 s | 3,097 |
+
+BDF 默认设置相对更细 RK45 参考的最大压力偏差约 2.38 kPa、温度偏差 0.0863 K、位移偏差 2.04e-7 m；收紧到 `rtol=1e-8` 后分别降至约 3.09 Pa、2.83e-5 K、1.72e-8 m。本例收紧误差限同时减少了求值/拒绝步，不能据此推广“越严格越快”。
+
+第一版尚未声称覆盖全部物理模式或与 Amesim 所有曲线一致。BDF 使用另一种积分实现，不能把它的耗时与 Python RK45 相除后归因于语言。
+
+使用说明见 [native/README.md](../../native/README.md)，完整证据见 [第一版测试报告](../../test/native-v1/report.md)。