SystemSimulationApp/docs/other/test-mql-8模型对照与修正-2026-09-11.md

# test-mql-8 模型对照与修正（2026-09-11）

目录整理补充：`tests/data` 的 JSON/XML 仅保留浏览器可导入的四路、八路 corrected JSON；参考曲线、旧工程和后端 XML 已迁到 `tests/baselines` / `tests/fixtures`，本文当前路径同步更新，文件内容及来源哈希不变。详见 [数据目录说明](../../tests/data/README.md)。

已依据 `tests/data/test_mql.ame` 的真实图纸生成 `tests/data/test-mql-8-corrected.json`，保留原 `test-mql-8.json` 供审计。修正版包含参数、逐端口连接和仿真最大步长的对齐。静态校验通过。rtol=1e-7 的首次求解在 120 s 限额内推进到 5.144858167 s 后超时；后续按用户确认的全局 rtol=1e-8，以同一执行模型和内核完成了完整 10 s 单次运行。本轮未运行 Amesim 官方程序，也未进行八路 Amesim 曲线对比。

## 来源与核查方法

AME 是可读取的 tar 归档。以 `test_mql_.cir` 的组件、接触连接、DIRECT 连接和带子模型的管线为模型来源，解析全局表达式、SI 单位和初始状态。压力字段按图纸保存的表压加 `101300 Pa` 转为公开模型的绝对压力。原始输入指纹：

- `tests/data/test_mql.ame`：21698560 字节，SHA256 `1ff0ea4284b9248260eeceb8b27cd0bc14dbccb43554ab8c0b49900d0b944c3d`。
- `tests/fixtures/legacy/test-mql-8.json`：272523 字节，SHA256 `4f1bf698519ba21429a11a83653adc7e52191f2d2b51fca943ee0b84f62feebd`。

图纸含 117 个组件、40 条带模型管线，展开后共 157 个元件（含介质）、178 条连接，与 JSON 的类型拓扑完全同构。映射以类型和完整邻接约束建立，再选端口修改数最少的对应关系，不使用组件显示名称猜测。类型拓扑的剩余对称候选具有相同 AME 参数；完整逐元件映射保存在审计文件中。

组件图纸端口索引从 0 开始；信号端按公开合同映射为 `res/out`。管线 `OUTPUT_TYPE=1` 时起点对应计算 port_1、终点对应 port_2；`OUTPUT_TYPE=2` 时相反。这个字段决定 PNL0001 的储气端，不能仅根据线段绘制方向推断。

1092 个公开参数全部核对，其中 1015 个可直接对应参数又与归档 `.param/.data` 逐值交叉核对，全部一致；这两份表均有 1170 行。两个 LMECHN1 的结构参数 `v1=8` 只在图纸中声明，其余公开补充参数按已有合同映射。归档结果未用于声称本轮已经重新运行 Amesim 或完成曲线一致性验证。

## 参数修正

以下四项均属于拓扑唯一对应的 `amesim_mecmas21_9`，AME 实体为 `component:35 / mass_friction_endstops_19`。

| 参数 | 原 JSON | AME 图纸与修正版 | `.param/.data` 行号 |
| --- | ---: | ---: | ---: |
| mass | 90000 kg | 100 kg | 364 |
| xmin | -0.72 m | -1 m | 373 |
| xmax | 0 m | 1 m | 377 |
| stoptype | 1 | 4 | 383 |

这不是只交换参考口的同数值优化；质量与限位配置的修正确实会改变系统行为。其余 1088 个参数已一致，保留原值及编辑器单位、表达式和显示设置。比较允许正常的浮点表达式舍入差异，不把 `15299999.999999998` 与 `15300000` 当作参数错误。

## 连接和仿真设置

所有 178 条边逐端口与 AME 对齐，共 62 条边各修改一个端点，元件之间的邻接关系保持一致：

| 类型 | 修改端点数 | 原因 |
| --- | ---: | --- |
| 8 个 P4NODE2 | 30 | 修正 7 个参考口的实际来源，并对齐其余支路的精确编号 |
| 8 个 PNCH012 | 16 | 对齐共享容腔的 port_2/port_3 编号 |
| 2 个 LMECHN1 | 16 | 对齐八条机械汇总支路的编号顺序 |

后两项属于现有共享状态/汇总端口的编号对齐，不应解释成 32 处独立物理机制错误。15 条受影响边原带有几何接触标记，端点变化后清除该标记，使连接以普通边显示；不删除任何物理连接，也不移动组件。

AME `.sim` 首行保存 `0 10 0.01 1e30 1e-7 ...`。修正版保持 0～10 s、输出间隔 0.01 s，最大积分步长由原 JSON 的 0.02 s 对齐为 1e30 s。公开模型仍采用 BDF；没有将 AME 的内部求解器编号等同于 CVODE BDF。AME 归档相对误差限为 1e-7，首次原生核验采用同值。后续经用户确认，全局网页/API 默认值调整为 1e-8；JSON 协议本身不新增误差限字段，后续执行按实际后端设置记录。

## 验证与复现

修正版通过工程载荷解析、XML 导出、端口供需与网络校验，以及正式 C 代码生成：132 个动态状态、1784 个输出、484 条气动计算关系、0 个系统代数循环块。编辑器保存的参数表达式在单独的执行副本中解析为数值，与浏览器导出行为一致。此项静态验证之后进行了下述一次真实数值执行；管流求根修改的其他模型性能对照由独立验证记录说明。

复现：在仓库根目录执行 `.venv/bin/python tools/audit_test_mql8_model.py`。脚本复用现有 `tests/test_test_mql_ame_contract.py` 中的 AME 表达式、单位和公开参数映射辅助函数，不执行该历史测试类。

脚本写入修正版 JSON，以及 Git 忽略目录 `test/solver-newton-20260911/mql8/` 中的 `audit.json`（157 个实体映射、1092 项参数、178 条连接、1015 项归档参数交叉证据和来源指纹）与 `corrected.xml`。它不修改原 JSON、AME 或冻结基准。

本轮实际求解与手工网页验收均显式使用修正版 `tests/data/test-mql-8-corrected.json`，作为后续用户运行的交付文件。原 JSON 仅保留为审计来源；旧 `simulation-live-mql8.spec.ts` 记录 2026-08-18 的 Python 后端活动心跳流程并写入该日基准文件，不作为本轮原生验收入口，未覆盖其历史证据。`fit-view.spec.ts` 的旧模型视图检查和 `tests/baselines/` 也保持原始输入。

## 单次真实 C 执行

使用修正版 JSON，经正式输入加载、C 生成和本机静态 SUNDIALS 7.4.0 构建后，直接调用一次 `execute_native`；未预热、未重复计时，也未更改物理参数、精度、积分器或库。请求 BDF/CVODE、0～10 s、rtol=1e-7、最大步长 1e30 s、采样间隔 0.01 s，执行限额 120 s。质量等状态的实际绝对误差限仍由当前生成器按物理量生成。

| 指标 | 单次运行结果 |
| --- | ---: |
| 完成状态 | failed，执行超时 |
| 实际推进终点 | 5.144858167417297 s |
| 纯求解墙钟 | 120.000105 s |
| 模型求值次数 | 1530472 |
| 接受步数 / 拒绝步数 | 77649 / 2590 |
| 输出采样数 | 517（含事件和退出时刻） |
| 气体质量状态数 | 56 |
| 初始气体总质量 | 5.5668930151375235 kg |
| 已返回采样的总质量最大漂移 | 1.62537e-13 kg |

所有已返回采样数值均有限。结果明确报告 `Native solve exceeded its time limit.`；超时后 RHS 拒绝求值产生的 CVODE Jacobian/setup 错误日志不能单独作为另一个雅可比故障的证据。这次运行证明修正模型能生成、构建并实际推进，不能表述为完整 10 s 回归通过，也不支持性能加速结论。未为取得完成标记放宽设置或追加运行。

材料保存在 `test/solver-newton-20260911/mql8/native-run/`：`input.xml`、`model-manifest.json`、`summary.json`、`execution/result.json` 和 `execution/worker.log`。构建键为 `403eb3539384555d3d2eb48951d2416f4754a7b1466f5c001a12879b4928eb7a`，该次执行时修正版 JSON 的 SHA256 为 `d034938422cc35e4e49183c76e900ad09ebbca250624fe3706fed76064e25038`，对应下述 P4 显示修复之前的工程。单次执行脚本是同目录上级的 `run_native_once.py`；复现必须改用新的运行目录，不能覆盖现有结果。

## P4 端口显示对齐

后续逐口复核发现，原通用 P4 符号的 port_3/port_4 方位与 AME 编号不一致。通用符号修正为默认 port_1 上、port_2 左、port_3 下、port_4 右后，对八路图纸逐个读取 `COMP_GEOMETRY` 和 `COMP_PORTS`：8 个 P4 均为 geometry 1，口位依次为下、右、上、左。因此修正版统一设为 `rotation=180`、`mirrored=false`，同时清理关联边上 6 组过期 `routePoints`；生成脚本保存了这项处理与每个原图端口的证据。

修复前后通过正式 `load_input` 导出的 XML **逐字节完全一致**，SHA256 为 `2804b33f04cabb3c10fcc3cc0843c35de17efbe1b6ee5e5e821edd9a5515a23d`；这次仅改变显示方位和旧路径缓存，没有改变物理端点、参数或执行设置。当前修正版 JSON 的 SHA256 为 `670977bef67e62d9c66e8af497bada208bd72a7301be45128d185d47282cf288`。验证记录在 `test/solver-newton-20260911/mql8/p4-display-verification.json`，此前的运行输入和结果保持原样。

## 全局 rtol=1e-8 的单次完整运行

用户确认全局网页/API 默认相对误差限改为 1e-8 后，对当前显示修正后的 JSON 再执行一次。脚本从正式 `simulation_config` 读取设置，并在运行前断言其确为 1e-8，未通过命令行或局部配置覆盖默认值。使用 BDF/CVODE 7.4.0、0～10 s、最大步长 1e30 s、采样间隔 0.01 s；执行限额仍为 120 s，无预热或重复运行。

| 指标 | 单次运行结果 |
| --- | ---: |
| 完成状态 | success=true，completed |
| 实际推进终点 | 10 s |
| 纯求解墙钟 / CPU | 5.907054 s / 5.906099 s |
| 模型求值次数 | 74265 |
| 接受步数 / 拒绝步数 | 6974 / 454 |
| 雅可比求值 / LU 次数 | 475 / 1656 |
| 状态转换 / 求解器启动次数 | 1 / 4 |
| 返回采样数 / 范围 | 1002 / 0～10 s |
| 气体质量状态数 | 56 |
| 气体总质量最大漂移 | 1.15463e-14 kg |

全部返回采样均为有限数值，132 个动态状态、1784 个输出和 0 个系统代数循环块保持一致。此次命中与 rtol=1e-7 运行相同的构建键 `403eb3539384555d3d2eb48951d2416f4754a7b1466f5c001a12879b4928eb7a`；P4 显示修复不改变执行 XML，相对误差限是运行时设置。两次运行精度条件不同，而且本轮与轻量前端检查并行，不能根据这两次时间记录宣称管流优化的加速倍数。

本轮证明当前修正版在全局 rtol=1e-8 下可以完整运行 10 s；不以此替代八路模型与 Amesim 曲线的独立一致性核验。此前 rtol=1e-7 超时记录保留，不改写为通过。

材料位于 `test/solver-newton-20260911/mql8/native-run-rtol1e8/`，包含 `input.xml`、`model-manifest.json`、`summary.json`、`execution/result.json` 和 `execution/worker.log`。执行脚本为其上级 `run_native_rtol1e8.py`，只有传入 `--execute` 才启动求解，且要求新的运行目录。输入 JSON SHA256 为 `670977bef67e62d9c66e8af497bada208bd72a7301be45128d185d47282cf288`。

## 八路真实网页补验

通过本次 `127.0.0.1:8011` 正式网页，直接导入最终 `test-mql-8-corrected.json`，以全局 `rtol=1e-8` 完整运行到10 s。曲线显示、CSV和结果文件下载、刷新后恢复均成功，无浏览器脚本异常。网页原始曲线和最终输出与独立原生八路运行逐值相同；CSV的1785列、1002行逐单元与原始数据相同。最后一轮为功能补验，不计入四路速度基准。

完整证据在 `test/solver-newton-20260911/browser-mql8-final/`：`summary.json`、`verification.json`、输入快照、原始/恢复后的`.simresult`、CSV和网页截图。初轮自动化曾因写死四路独有组件ID而在选择曲线时失败，应用求解已完成且无pageerror；脚本改为从当前工程选择真实存在的PNL0002后，上述流程全部通过。