65 lines
8.5 KiB
Markdown
65 lines
8.5 KiB
Markdown
# 优化验证的模型、数据和计时口径
|
||
|
||
文档版本：1.1.0；核对日期：2026-09-12；本次路径修订基线：`44b6ea7`。本轮补充实际计时字段和运行入口，保留用户指定的八路优先及精度要求。
|
||
|
||
本约定记录用户于 2026-09-11 明确的长期偏好，适用于后续仿真正确性检查与性能优化。
|
||
|
||
## 默认模型与退路
|
||
|
||
优先使用 `tests/data/test-mql-8-corrected.json`，Amesim 来源严格对应 `tests/data/test_mql.ame`。先核实当次文件与物理输入，不按显示名、目录名或历史报告标题认定为同一模型。原始旧工程仅保留审计用途，不重新作为活动输入。
|
||
|
||
2026-09-13 用户再次确认上述两份文件为后续八路默认输入。UD00 曾存在“数字相同、枚举含义不同”的错误；当前四路、八路 corrected JSON 及审计均已修复。AME 的 `1=不循环/2=循环` 转为公共模型的 `0=不循环/1=循环`，不能直接复制数字。历史冻结输入保留旧编码，不能用于证明当前语义正确。详见 [元件语义核查与修复](../other/Amesim元件语义核查与修复-2026-09-13.md)。
|
||
|
||
只有八路模型确实跑不通，而且短期内没有可行修复时，才退回 `tests/data/test-mql-4-corrected.json` 与 `tests/data/test_mql_4.ame`。报告必须记录八路失败的实际终点、诊断、已排查内容及退回原因；四路结果不能代替八路验收。
|
||
|
||
## 当前入口与历史基准隔离（2026-09-12 补充）
|
||
|
||
- 当前八路核对：`.venv/bin/python tools/audit_test_mql8_model.py --check`。读取 corrected JSON 与当前 AME，证据写入 `test/model-audit/mql8/`，不修改工程。模型参数与连接为强制检查；时间配置差异单独报告，需强制相同时增加 `--require-same-time-settings`。二者都不将 AME 积分器枚举等同于 CVODE BDF。
|
||
- 当前四路核对：`.venv/bin/python tests/model_audit/audit_mql4_model.py --check`。XML 从四路 JSON 在内存中生成，再独立对照 AME 的参数与精确端口连接，不依赖已删除的 XML 夹具。
|
||
- 当前八路运行：`.venv/bin/python -m unittest tests.test_current_mql8_simulation -v`。完整使用工程所存区间和配置，验证原生执行、事件、采样完整性与数值有限。该项代替已删除的高刚度 XML 测试，不宣称覆盖原 RK45 专项或证明与 Amesim 曲线一致。
|
||
- 2026 年 8 月冻结输入在 `tests/baselines/simulation/test_mql_8/sources/`，对应 `tests/data/AmesimModels/test_mql.ame`。其字节数、SHA 和数值配置仍按 manifest 校验；历史记录中的旧路径不作为活动入口。普通前端大型画布测试使用当前 corrected JSON，历史 Python 活动遥测回放保持显式启用。
|
||
|
||
Windows 对应使用 `.venv-win\Scripts\python.exe` 调用相同脚本；路径由仓库根解析。详细文件映射、报告来源及本次实际平台见 [路径修复记录](../other/2026-09-12-test-input-path-refresh.md)。
|
||
|
||
## 先核对实际数据，再计时
|
||
|
||
逐元件、逐端口、逐参数检查拓扑和物理量，尤其是参考口、表压与绝对压力、SI 换算、力和流量方向、初始化及信号时刻。完整区间实际结果、守恒、事件和所需曲线按明确口径核查。存在数值差异时仍可按用户要求测量并记录运行成本，但必须将其标为性能观察，不能据此宣布正确性验收通过。完成运行和数值有限只证明可运行，不能直接判定曲线一致。
|
||
|
||
AME 文件是归档。必须记录外层 SHA-256，并核实 `.cir`、编译 `.c`、`.param`/`.data`、`.modelinfo`、`.var`/`.results`、`.sim` 的子模型、参数布局、变量索引、初值和时间范围相互对应。图纸与缓存不同就不能使用缓存作为当前参考。冻结基准绑定的另一个 AME SHA 不能因为文件同名就移作当前数据。
|
||
|
||
曲线对照保留原始采样点和事件点，明确变量映射、单位、方向、插值方法与范围。按量纲报告全时点最大绝对误差、均方根误差及定义清楚的相对误差，并单独说明事件时刻差异。峰值归一化误差不冒称为逐点相对误差；不能删去异常点、平滑尖峰或只选常规采样点来宣称整条曲线一致。缺少同工况数据或验收阈值时，明确标记该项 `skip` 或“仅观察，未验收”。
|
||
|
||
Amesim 速度比较需要同模型、同设置、完整区间的真实 CPU/墙钟记录。`.ameperf` 内的仿真事件时间不是运行耗时，归档成员修改时间也不能推导运行耗时。缺少可信耗时则明确 `skip` 速度比较；仍可独立报告满足来源条件的已保存曲线观察。
|
||
|
||
## 固定精度与运行条件
|
||
|
||
当前用户已批准网页/API 默认 `rtol = 1e-8`，原生 Python CLI 也经同一设置入口；单独构造 `SolveIVPConfig()` 默认仍为 `1e-6`。同一性能比较中的精度必须固定，记录实际生效的 `rtol`、`atol`/状态误差下限、求解器、最大步长、输出间隔、起止时间、事件策略及雅可比策略。不能通过放宽精度、缩短区间、减少输出或改变物理参数制造加速结论。精度或模型变化后另建比较组，不能直接用旧组耗时计算优化比例。
|
||
|
||
正式计时记录源码版本、输入和原始结果 SHA、构建标识、编译器及积分库版本、硬件与运行环境。固定预热规则、缓存状态和重复次数，同机比较时避免并行求解、大编译等 CPU 干扰；报告逐次耗时及汇总口径。单次完整运行用于功能验证，不据此认定性能提升。
|
||
|
||
## 分阶段记录
|
||
|
||
分别记录输入加载/校验、代码生成、构建和缓存检查、进程启动、C 积分阶段 CPU/墙钟、结果整理/序列化/传输，以及网页接收、持久化、曲线展示和导出。只测到总耗时就称为总耗时，不能把差值未经测量地归于某个阶段。
|
||
|
||
每次运行保存实际设置、成功或失败状态、实际终点、采样数量、求值次数、接受/拒绝步数、雅可比/线性分解次数、事件诊断和守恒结果。报告链接到原始产物，明确哪些阶段未测量、哪些比较因数据不足而跳过。后续优化以通过正确性检查后的同口径数据为依据。
|
||
|
||
## 实现中已有的计时与缺失项
|
||
|
||
| 字段 / 事件 | 当前范围 | 不能如何使用 |
|
||
| --- | --- | --- |
|
||
| CLI `preparationSeconds` | 加载/规范化输入、校验、构造网络、生成 C | 不能单称前端预处理或 C 编译 |
|
||
| `buildSeconds` | 工具链与依赖检查、预处理、缓存验证、缺失单元编译、链接和部分清理 | 命中时仍非零；不是单纯编译耗时 |
|
||
| `buildDetails.preprocessSeconds` | 并行预处理段墙钟 | 不包含全部工具链/依赖检查 |
|
||
| `compileSeconds` / `compileWallSeconds` | 各编译子进程耗时之和 / 编译单元阶段墙钟（也包含复用与复制） | 前者不是 CPU 计时，二者不能相加 |
|
||
| `linkSeconds` | 链接命令墙钟 | 不含整个构建发布阶段 |
|
||
| C `solveSeconds` / `solveCpuSeconds` | `native_solve` 内积分调用的墙钟 / CPU，含积分中的采样和事件工作 | 不包含调用前的初始化、首次样本，以及之后的最终追加和 JSON 编码；不能叫完整仿真耗时 |
|
||
| `processWallSeconds` | Python 从准备启动子进程，到进程退出、日志收集、读取/解析结果结束 | 不是只测 C 程序进程存活时间 |
|
||
| `phase="complete"` / “正在汇总仿真结果” | runner 已读完结果，后续还有响应组装、传输、网页解析及持久化 | 该文案持续时间不能全部归到后端汇总 |
|
||
| IndexedDB 事务完成 / sessionStorage 指针发布 | 当前网页结果持久化完成 | 不等于 OS 下载文件落盘 |
|
||
|
||
CLI 默认 `--runs 3` 实际执行 1 次预热加 3 次计时运行，`medianSolveSeconds` 不含预热；`--solve-only` 不记录完整曲线，仅适于积分成本观察，不能作为“点击运行→结果可查看/保存”的总耗时或完整曲线验收。
|
||
|
||
当前 C/原生适配报告求值、步数、事件计数及 `njev/nlu`，但并未自动输出所有物理量的守恒误差，也没有完整逐试算活动遥测。心跳中的活动字段不等于每一项都被原生程序实时更新；缺少的指标需独立测量/计算，不能把空值或未更新的 0 当作已验证结果。
|
||
|
||
网页 CSV 默认在 Web Worker 本地生成；后端保留的 CSV 路由不代表网页实际使用该路由。图表还有按事件诊断分离部分孤立机械力样本的展示逻辑；正确性比较使用原始 series、结果文件或 CSV，并保留事件点，不能以图表截图代替原始数据。
|