Replace Python numerical kernels with native C execution
This commit is contained in:
ljz committed
1 parent
48da6be21c
commit
3b38f73fe0
227 files changed
+16801
-75499
No files matched your search
@@ -2,6 +2,7 @@
|
||||
|
||||
> 文档状态：待评审实施方案
|
||||
> 建立日期：2026-09-02
|
||||
> 补充日期：2026-09-09；第 10 节结合最新实测，细化 XML → 系统专用 C → 原生 EXE 路线。前九节保留原阶段方案与历史评估；本次仅补充设计，未完成生产内核替换。
|
||||
> 适用分支：`model-development`
|
||||
> 关联文档：[求解器性能优化任务清单](求解器性能优化任务清单.md)、[后端求解逻辑与效率优化调研](后端求解逻辑与效率优化调研.md)
|
||||
> 范围：后端数值执行内核；不包含前端重写，也不主张把整个 Python 后端改写为 C
|
||||
@@ -404,3 +405,137 @@ Numba 可以在完整数组 IR 后用于 1–2 周的架构验证，但不作为
|
||||
6. 评审通过后，再建立最小 C ABI 和纵向切片。
|
||||
|
||||
第一批的退出条件不是“已经写了多少 C”，而是：当前基准可信、同一计算能被无回调 IR 完整表达、差异能定位到具体阶段和槽位。只有达到这个条件，后续 C 工作才具有可预测的收益和可控的回滚成本。
|
||||
|
||||
## 10. 2026-09-09 补充：XML 自动生成系统专用 C / EXE
|
||||
|
||||
### 10.1 新证据与本次目标
|
||||
|
||||
用户本次希望解析 XML 后，自动生成对应系统的 C 求解程序。建议把“模型专用代码生成 + 原生积分运行”作为目标架构；开发时仍保留“相同输入逐阶段比较”和“相同 SciPy 积分器仅替换完整 RHS/Jacobian”的诊断阶段，用来分别测量执行语言与积分算法的影响。后者是验证手段，不是最终交付边界。
|
||||
|
||||
最新证据不能把速度差异全部归因于 Python：
|
||||
|
||||
- 先前特定模型的完整 C EXE 求解仍约 44.82 s；C 剖析中模型求值占 97.07%，雅可比构造占 87.17%。雅可比包含模型求值，两项不能相加。
|
||||
- 该 C 版本采用 132 状态的逐列差分，每次雅可比约需 133 次完整 RHS，累计 124,089 次。这个结论针对测试 C 实现；当前 Python 引擎已经有稀疏结构、着色和部分半解析路径，不能把它也描述成始终采用全稠密差分。
|
||||
- Amesim 仅关闭 optimized solver，进程 CPU 从 2.890625 s 增至 13.890625 s，结果文件字节、函数/雅可比计数、成功步数均相同。这证明执行优化层本身很重要，但没有揭示其专有优化实现。
|
||||
- C 管流中的固定次数二分及频繁未收敛退出是已知热点，不能作为成熟组件内核直接复制到生产生成器。
|
||||
|
||||
依据：[C 剖析报告](../../test/native-mql8-profile/performance-analysis.md)、[Amesim 优化开关对照](../../test/native-mql8-profile/amesim-optimizer-comparison.json)。这是特定模型对照，不是受控的生产 Python/C 语言收益测量，也不保证新引擎达到 Amesim 的速度。
|
||||
|
||||
### 10.2 最终执行边界
|
||||
|
||||
```text
|
||||
网页导出 System XML
|
||||
→ Python：协议校验、组件版本/参数/连接校验
|
||||
→ ModelIR：方程/可信组件原语、连续状态、代数变量、事件、依赖
|
||||
→ 结构编译：合并等价变量、确定计算顺序、划分代数环、生成稀疏结构
|
||||
→ C emitter：model.c + model.h + manifest.json
|
||||
→ 编译并链接：组件 C 库 + 原生积分运行库
|
||||
→ 独立 native worker / 模型 EXE：完成初始化、积分、事件、数值采样
|
||||
→ Python：读取结果、任务状态、现有 API 编码
|
||||
```
|
||||
|
||||
编译和 EXE 均在后端机器执行。Python 可以继续完成低频管理工作；一次积分中的 RHS、代数闭合、物性、Jacobian、Newton 和事件处理全部留在原生进程，不能在每次求值时回调 Python。
|
||||
|
||||
首个交付可生成模型专用 EXE，便于独立运行、复现和隔离崩溃。之后如实测编译或启动成本成为问题，再用通用 worker 加载缓存模型 DLL；DLL 同样加载在隔离进程中。原生运行时与组件库预先编译，每个新拓扑只生成和编译模型装配部分。
|
||||
|
||||
### 10.3 XML 不包含完整方程，必须建立 C 组件库
|
||||
|
||||
现行 XML 保存组件类型、版本、参数和连接，不包含各组件的物理公式。自动编译依赖一份可信映射：
|
||||
|
||||
```text
|
||||
(model_type, model_version, 支持的结构选项)
|
||||
→ 参数校验 + 状态/端口布局 + 方程或 C kernel + 局部导数 + 事件/reset
|
||||
```
|
||||
|
||||
`app/simulation/registry.py` 的注册定义可以继续作为编译前端的数据来源，逐个增加原生能力描述。普通公式可用受限表达式 IR 表达，同时生成数值计算和导数；复杂物性与非线性管流使用经过验证的手写 C 原语，并声明完整输入输出及导数合同。不要依赖自动翻译任意 Python 类。
|
||||
|
||||
例如“气室 A—管道—气室 B”编译后固定为状态和参数数组下标：求两边物性、算这根管道的流量、按端口方向累加质量/能量导数。运行时不再寻找组件对象、端口名称或连接边。系统专用代码可以直接调用 `pipe_kernel(...)`，无需把物性库和积分器源码重复展开进每一个模型。
|
||||
|
||||
现有 `EquationResidual` 保存变量名称及已经计算出的 `value`，并没有保存完整公式表达式；`causal_ir.py` 提供部分结构基础，但其执行绑定仍有 Python 回调。因此需要补齐完整数值 IR。当前 `app/simulation/ir/` 仅发现缓存文件，不能视为已有可维护的完整 IR 源码。
|
||||
|
||||
`test/native-mql8-bdf/generate_model.py` 是验证原型：仍限定特定阀动作、机械组件编号、部分参数和连接形式，并拒绝某些循环闭合。正式编译器应由拓扑和能力合同推导这些内容，不能直接把这份脚本改成 XML 读入便宣称通用。
|
||||
|
||||
### 10.4 编译器要提前完成的计算
|
||||
|
||||
| 编译工作 | 运行时收益或正确性要求 |
|
||||
| --- | --- |
|
||||
| 合并等压、等速度等别名变量；组装流量/力平衡 | 消除多余未知量，统一端口方向与 SI 单位 |
|
||||
| 对方程和未知量做匹配，将相互依赖部分划成小块 | 能顺序计算的直接计算，仅对真正代数环迭代；无法配平时定位到组件 |
|
||||
| 固定状态、代数变量、参数、工作区和输出下标 | 每次求值使用连续数组，避免字典、字符串查找和临时分配 |
|
||||
| 编译 stream 图及受温度影响的物理子网 | 保留现有无环传播和局部闭合能力，避免退回每轮全网重算 |
|
||||
| 计算各入口的依赖集合与所有支持模式的稀疏结构 | RHS、事件、Jacobian 和输出按需计算；求 RHS 不自动附带所有输出 |
|
||||
| 提取几何常量、公共表达式和物性状态包 | 参数不变的部分只初始化一次；相同精确输入下共享结果 |
|
||||
| 声明事件、离散模式、缓存失效和状态复位 | 阀门跳变、流向切换、接触不依赖碰巧足够小的积分步长 |
|
||||
|
||||
跨积分调用的缓存必须按输入和模式有效性管理，不能仅以时间为键；同一时间可能存在多个 Newton 试探状态或雅可比扰动。试探工作区与已接受状态分开，拒绝步与事件回退不得提交试探产生的模式或缓存。
|
||||
|
||||
### 10.5 积分库与代数环的选择
|
||||
|
||||
当前引擎在 RHS 内闭合代数变量，对外给出 ODE。第一版原生全流程建议使用 **SUNDIALS CVODE 的 BDF 模式**。CVODE 提供 C 接口、1–5 阶变阶变步长 BDF，以及稠密、带状、稀疏线性求解接口。它的 Adams/BDF 由调用方选择，不能将其描述成 Amesim/LSODA 那样自动切换两种方法。[CVODE 数学方法](https://sundials.readthedocs.io/en/latest/cvode/Mathematics_link.html)
|
||||
|
||||
生成器负责模型方程、结构和导数，成熟积分库负责步长/阶数、误差控制和求解器历史。不要为每份 XML 重新生成一套 BDF 算法。先锁定可复现的 SUNDIALS 版本、C 接口、构建工具和依赖；Windows 用原生 C 构建链产出 EXE，Linux 对应 ELF 程序。
|
||||
|
||||
稀疏矩阵可配合 KLU，但先提供正确稀疏 Jacobian，再根据模型规模比较稀疏与稠密线性代数；132 状态案例的 LU 仅占约 2.19%，只换 LU 库难以改变总体耗时。[CVODE 线性求解选择](https://sundials.readthedocs.io/en/latest/cvode/Mathematics_link.html)
|
||||
|
||||
如果某类代数环难以可靠消去，可另行建立 `F(t, y, ydot) = 0` 的 DAE 后端，评估 C 接口的 IDA。此时必须处理代数变量、一致初始化和系统指数；高指数约束不能直接交给 IDA 期待自动解决。[IDA 官方介绍](https://sundials.readthedocs.io/en/latest/ida/Introduction_link.html)
|
||||
|
||||
消去代数变量后，Jacobian 不能只拼接相邻组件的直接偏导。对
|
||||
|
||||
```text
|
||||
ydot = f(t, y, z)
|
||||
0 = g(t, y, z)
|
||||
```
|
||||
|
||||
在当前光滑分支、`g_z` 可逆时，需通过线性求解得到 `g_z * dz/dy = -g_y`，再组装 `J = f_y + f_z * dz/dy`，无需显式计算逆矩阵。这样才包含“状态变化 → 代数环重新平衡 → 导数变化”的影响。结构编译也要考虑此过程产生的新依赖。
|
||||
|
||||
第一版可用保守结构着色差分建立正确基线，再逐类增加局部解析导数或自动微分。旧实测的非零图和 27 色只是某次运行观察，不能直接当作全部流向/接触模式的可靠结构。迭代求解器的导数应针对其收敛方程，不宜把固定次数迭代轨迹直接当作物理方程导数。
|
||||
|
||||
### 10.6 项目接入点和生成产物
|
||||
|
||||
| 位置 | 具体接入方式 |
|
||||
| --- | --- |
|
||||
| `app/system_xml.py` | 复用现有校验和 `SystemXmlDocument`；补充明确的误差设置传递合同 |
|
||||
| `app/main.py:compile_system_xml_network` | 抽取共同的版本、参数、介质与连接规范化前端；避免 Python/C 分别解释模型 |
|
||||
| `app/simulation/solvers/causal_ir.py` 与现有分块/stream 计划 | 复用结构分析结果，转换为无 Python 回调的数值计划 |
|
||||
| 建议新增 `app/simulation/native_codegen/` | 完整数值 IR、组件原生能力注册、结构编译、C emitter、编译缓存 |
|
||||
| 建议新增 `native/runtime/`、`native/components/`、`native/include/` | CVODE 适配、代数求解、组件与物性原语、版本化 C ABI |
|
||||
| 建议新增 `app/simulation/backends/` | Python 与原生 worker 的统一运行接口、结果适配和诊断 |
|
||||
| `app/main.py:_run_system_xml_simulation_profiled` | 在现有任务/进度/取消接口内选择后端，保持结果变量标识和单位一致 |
|
||||
|
||||
每个模型的缓存目录建议包含：
|
||||
|
||||
```text
|
||||
<build-key>/
|
||||
model.c / model.h # 状态、端口布局和模型专用计算入口
|
||||
manifest.json # 来源、版本、布局、组件映射、支持能力、构建哈希
|
||||
model.exe # 链接原生运行库的可执行模型
|
||||
```
|
||||
|
||||
每次运行另建目录，保存数值参数、运行选项、结果和诊断。模型 ABI 至少区分 `initialize`、`rhs/residual`、`jacobian`、`roots`、`apply_event`、`outputs`，通用运行库提供 `run`。RHS 返回导数，事件函数返回零点函数值，输出函数只在需要物理投影时调用。每个运行拥有独立 context，禁止共享可变全局状态。
|
||||
|
||||
缓存键包括规范化拓扑、组件/介质实现版本、结构参数、IR/ABI 版本、精度、平台、编译器和编译选项。普通数值参数以数组传入，时长、容差、最大步长与输出间隔由运行选项传入；这些修改通常无需重新编译。改变端口数量、状态数量或方程分支结构的参数必须触发重新编译。若把某个普通参数特化进源码，也必须将其值纳入缓存键。
|
||||
|
||||
生成器只输出可信原语与合法数值，用户组件 ID 通过映射表定位，不作为任意 C 源码或编译命令片段。未支持的组件、模式或算法在编译/启动阶段明确报告；强制原生测试不得静默改用 Python。
|
||||
|
||||
### 10.7 精度、采样与性能口径
|
||||
|
||||
本次检查发现两个实际差异：
|
||||
|
||||
- 网页入口 `app/main.py` 的 `rtol` 当前写死为 `1e-6`；此前测试 C 为 `1e-7`。XML v3 尚无 `rtol/atol` 字段，应通过明确的协议演进同时更新 XSD、解析、导出和执行设置，不可只修改某一后端。
|
||||
- 当前 `tests/data/test-mql-8.xml` 仍为 `maxStep=0.001`，而此前 JSON 测试副本使用过 `1e30` 和 `0.02`。后续应由同一份规范化模型与独立运行配置驱动比较，不能用文件同名推断设置相同。
|
||||
|
||||
`rtol` 相同也不等于总体精度相同：需同时固定每类状态的 `atol`、单位/缩放、代数闭合容差、初始化及事件处理。首阶段保持状态定义和方程一致；改变质量/内能为压力/温度等状态形式属于单独的数值方案。
|
||||
|
||||
`sampleStep` 与内部积分步长分开：使用积分库的插值能力取得输出采样点，不为每个输出点重新启动求解器。已知不连续时刻仍要显式分段，状态事件要定位零点并执行复位/重启。`maxStep=1e30` 只放宽上限，不会使求解器忽略精度或事件自动迈大步。
|
||||
|
||||
主指标单列求解墙钟与求解 CPU；XML 解析、代码生成、冷编译、初始化、输出投影、文件写入和 HTTP 序列化分别计时。性能模式只计推进所需的求值与事件定位，不计绘图及额外结果投影；正确性模式另行采样曲线验证。积分器要求的初始 RHS/Jacobian 也计入求解工作量，避免从计时中漏掉。
|
||||
|
||||
### 10.8 推荐实施顺序
|
||||
|
||||
1. **冻结一份共同输入和运行配置。** 以 `test-mql-8.xml` 为首个完整目标，列出其全部组件类型/模式、公式与原生能力；对齐当前 Python、旧 C 原型和 Amesim 的参数、单位、状态与事件差异。
|
||||
2. **完成一条闭环支路的完整 IR 和 C kernel。** 以同一 `t/y/mode/parameters` 比较初始化、物性、闭合、RHS、Jacobian 与事件左右值；覆盖正常、反向流、近零压差和接触状态。
|
||||
3. **生成该支路的 C 并链接 CVODE，跑通独立 EXE。** 同时以“相同 SciPy + Python/C RHS”作为执行开销对照，分开判断 C 迁移收益与更换积分器的影响。
|
||||
4. **覆盖首个完整模型，并接入现有 API 的显式原生选项。** 将当前 Python 的结构消元、stream 局部执行、事务回滚和稀疏能力迁入；优先修复管流收敛与雅可比重复求值，再考虑低占比线性代数优化。
|
||||
5. **验证通用性和再逐步默认启用。** 用组件重命名、连线变化、不同支路数量、反向流和其他受支持参数模式证明生成器不依赖原测试拓扑；按现有物理验收合同检查 Amesim 投影、事件时刻和守恒残差。
|
||||
|
||||
首个交付应能由任意命名、符合已声明支持范围的 XML 稳定生成可运行 EXE，同时报告实际后端、求解器版本、模型/二进制哈希、计时及求值/迭代计数。本次文档没有执行这项迁移，也没有新增性能测试；提速倍率需待上述共同输入对照完成后报告。
|
||||
Reference in new issue
Block a user