# test-mql-4 模型复核与输入修正（2026-09-11）

> 路径复核 / 2026-09-12：下文独立四路 XML 已删除。当前工程仍为 `tests/data/test-mql-4-corrected.json`；审计脚本从该 JSON 临时生成 XML，并在 `--check` 中独立核对 AME 参数与端口。历史 XML 哈希和生成记录保留为当时证据。 详见 [路径修复记录](2026-09-12-test-input-path-refresh.md)。

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

本次从 `tests/data/test_mql_4.ame` 的原始 `.cir` 图纸重新核对元件、参数和端口连接，生成了可导入网页的 `tests/data/test-mql-4-corrected.json`，并同步 `tests/fixtures/amesim/test-mql-4-corrected.xml`。两份输入均有 81 个元件、90 条连接、582 个公开参数，对应 64 个动态状态；生成结果的每个公开参数和连接端口均已按同一元件映射与 AME 图纸逐项比较。生成的 XML 通过后端语法和语义校验，无错误、无警告。

`native-python-reference.json` 是 50 个网络的冻结数值参考，`test-mql-4-amesim-reference.json` 是 72 条曲线、57 个时刻的 Amesim 结果参考，两者都不是可导入的工程 JSON。本次未覆盖或改写这两份参考数据。

## 新发现及修正

此前名为 corrected 的 XML 仍有一处参数不一致：`amesim_pnl00r_4` 对应 AME 的 `pneumatic`（图纸 `LINE` 索引 38、PNL00R）。AME 的相对粗糙度 `rr` 为 `1e-5`，旧 XML 为 `0.0032142857142857142`；本次改为 `1e-5`。该管径在前轮已改为 `0.01 m`，本次确认管长 `1 m` 也一致。此前报告列出的五处参数修正未覆盖这项遗留差异。

旧 XML 和 AME 的元件连接图同构，但有 25 条连线涉及等价端口编号或方向差异。本次 JSON/XML 直接采用 AME 的确切端口编号：

- 11 条连接涉及 P4NODE2 的非参考分支口重排，固定参考口 `port_2` 原本已匹配。
- 8 条连接涉及 PNCH012 的同一容腔端口重排。
- 4 条连接涉及 LMECHN1 的支路编号重排，公共机械端保持原对应关系。
- 2 条连接涉及 PNL00R 两端方向反转。它不增加容腔状态，但其带符号端口输出应按新端口对应关系解释。

PNL0001 的状态端未颠倒：AME 建模连线的 `OUTPUT_TYPE=1` 使用起点→模型端口 1、终点→端口 2；`OUTPUT_TYPE=2` 使用相反对应。组件端口索引从 0 起，PNVO001/FORC 的索引 0 映射为公开 `res`，STEP0/UD00 的索引 0 映射为 `out`，其他组件端口映射为 `port_(索引+1)`。

工程保留先前结果变量使用的组件 ID；显示名改为 AME 图纸别名。已有画布布局来自八路 JSON 中同 ID 元件的展示元数据，缺少的闭合管另行放置。变化端口的连接改用可见连线，避免把不再重合的端口继续标记为接触连接。布局、名称和绘图连线路径不作为物理一致性的依据。

后续真实浏览器导入发现，组件目录中的信号端口带有 `positiveFlowDirection: null`，而前端工程合同只接受省略此可选字段或值为 `intoComponent`。已修正交付 JSON 及生成器：没有方向值时省略该键。该修复仅涉及展示元数据，物理参数、连接端点及数值 XML 不变；审计 JSON 中的工程文件 SHA256 已同步更新。仅通过 XML 校验不足以证明工程 JSON 可被前端导入。

## 用户复核新增：P4NODE2 图形编号与朝向

用户直接打开 AME 后指出参考口看起来不同。这是实际的显示缺陷，前面的物理连接审计没有覆盖图形编号与朝向：导出工程的 80/81 个节点位置沿用了八路 JSON 中同 ID 的位置，闭合管 `amesim_pnl0002_10` 另放在 `(80, 900)`；工程布局并没有恢复为 AME 原图的坐标和连线路径。

重新直接读取 `.cir` 的 4 个 P4NODE2，均为 `COMP_GEOMETRY=1`，原始四个 `COMP_PORT/PORT_POS` 依次为 `(10,19)`、`(19,10)`、`(10,1)`、`(1,10)`。因此原图端口 1 朝下、参考口 2 朝右、端口 3 朝上、端口 4 朝左。前端原图标的 3/4 号锚点编号与该对应关系不符，而且四路 JSON 的第 2～4 节点未旋转，令参考粗线朝左。仅旋转原图标不能修正全部四口，因为对顶端口的编号也不同。

已交换通用 P4NODE2 图标的端口 3/4 锚点，并把四路工程的 4 个 P4NODE2 统一为旋转 180°、不镜像，使四口完整方位符合 AME；清除了 1 条相关连线的旧路由点。参考粗线与实际 `port_2` Handle 使用同一镜像/旋转变换，二者本身没有脱离。通用锚点修正也影响其他工程（包括八路 corrected）的 P4NODE2 显示方位，不改变其连接所引用的端口名称。

这次修复没有改变任何元件 ID、模型类型/版本、参数、连线 ID/端点或仿真设置，数值 XML 完全未改。审计 JSON 保留此前参数和连接修正记录，另记本次展示变化及最新工程哈希。

AME 自带预览图以及重新直接读取的原始图纸均显示四支路：4 个 PNRP17 活塞、4 个 PNCH012 气室、4 个 PNVO001 阀、4 个 STEP0 输入、4 个 LSTP00A 接触元件；4 个支路质量块另与 2 个公共质量块连接，因此 MECMAS21 总数为 6。图中气动管线有 18 条作为子模型的 LINE，在网页中显示为独立管路元件，这也是两种画法的计数观感不同之处。

独立图形证据保存在 `tests/model_audit/p4node2-ame-geometry.json`，直接记录原始 AME 端口坐标和归档哈希。新增前端回归以这组独立坐标检查实际 DOM Handle 的相对方位，并检查镜像后粗线仍指向 `port_2`；它不直接复制前端锚点常量作为判断依据。两项定向浏览器测试（既有 PN3/P4 图形检查及新增 AME 四口/镜像检查）均通过，共 9.4 s；测试没有请求仿真。

## 独立原始参数复核

为避免共享参数转换代码造成共同漏检，另用 `tests/model_audit/independent_mql4_parameter_check.py` 直接解析 AME 原始字段和表达式，独立求值及换算，没有调用原审计的 `_expected_parameters` 或其字段转换辅助函数。582 项分为 543 个 AME 原生字段、32 个公开容积/容积变化输入的零默认值，以及 7 个适配字段（4 个阀开度回退值、2 个由图形方向映射的力方向、1 个氦气物性选择）；公开额外字段不冒充 AME 原生参数。

当前 JSON 的 582 项均与各自来源或明确的适配规则相符。独立核对包括 26 个表压转绝压、58 个 mm→m、8 个 mm²→m²、6 个 L→m³，以及各 12 个刚度和阻尼从每毫米转为每米的换算。脚本已从可提交路径实际运行通过；逐字段表达式、原值、原单位、目标单位与比较结果输出到 `test/solver-newton-20260911/mql4/visual-recheck/independent-parameters.json`。

## 仿真设置及参考边界

生成输入为 BDF、0～10 s、输出间隔 0.01 s、最大步长 `1e30 s`；本轮初始核查阶段网页后端默认 `rtol=1e-7`，后续精度核查后已调整为 `1e-8`；JSON 不保存该后端默认值，实际运行值应以结果诊断为准。原 AME `.sim` 的原始两行数值保存在审计 JSON 中。前轮官方 API 核查记录该归档保存的是固定步长设置，而用于既有参考数据的是官方重新编译后改用 Standard 变步长、误差限 `1e-7`、最大步长 `1e30` 的四路运行。本次没有重新运行 Amesim，也不把 native BDF 与 Amesim Standard 自动算法称为同一积分器。

原 AME 归档内的图纸和编译/结果缓存不一致，不能直接把包内 `.results` 当作本次四路参考：

- `.cir` 有 63 个组件、18 条建模管线、26 条直接连线和 28 对接触连接，得到 81 个公开元件、90 条连接、64 个动态状态。
- `.modelinfo` 仍记载 132 个状态，`.ameperf` 包含 LSTP00A 第 1～8 实例，属于旧八路运行。
- `.results` 声明 1116 个保存变量，而当前 `.var` 只有 640 行；这两份缓存不能作为相互一致的结果集合使用。

既有 `test-mql-4-amesim-reference.json` 的来源声明为 2026-09-11 官方重编译四路模型，包含 72 条状态物理量及阀流量曲线、57 个选定时刻。它的原始 AME SHA256 与当前归档一致；其 `xmlSha256` 绑定的是修改前 XML，故本次修正后不再与该字段相等。这个历史字段和曲线数据保持不变，不能为通过校验而改写来源哈希。

该参考可用于本次曲线差异评估，但不表示本次重新运行了 Amesim，也不覆盖接触事件力峰或全部 1001 个常规采样点。新修改的粗糙度应作为本次输入差异明确记录，不能继续沿用“此前 corrected XML 已逐参数完全对齐”的结论。

## 复现与文件

在仓库根目录执行只读核查，不生成或改写工程与审计文件：

```sh
.venv/bin/python tests/model_audit/audit_mql4_model.py --check
```

该模式检查生成端口可选字段的规则，并逐组件比较 JSON/XML 的模型类型、版本、参数、全部连接端点与仿真设置；不启动求解器。当前交付通过，内存中人为加入 `positiveFlowDirection: null`、修改参数或连接端点均被拒绝。它是针对交付输入的轻量检查，不替代完整前端解析与真实浏览器导入。

需要重新生成 corrected JSON/XML 及审计文件时执行：

```sh
.venv/bin/python tests/model_audit/audit_mql4_model.py
```

脚本只静态读取 AME 图纸和注册组件合同，生成/核对 corrected JSON/XML，并输出 `tests/model_audit/test-mql-4-audit.json`。参数和单位转换复用仓库 `tests/test_test_mql_ame_contract.py` 的明确映射，脚本不依赖 `test/` 中的程序。首次运行时将其输入 XML 备份到 `test/solver-newton-20260911/mql4/legacy-corrected-input.xml`，另在该目录保存展开后的源模型和过程审计；修改前 XML 的 SHA256 为 `7b67e61f791f33bf2a4a0045d151d7fd6a418e63a5ea7f3472d474fd4eff9c86`。

原 AME SHA256：`99a071896671d634d651a7b21f487662dd7c122af8fd3d60ead404a5afa53ed4`。完整成员哈希、元件映射、25 条连接变化和生成文件哈希保存在审计 JSON 中。本报告记录输入及图形复核，不记录求解性能或本轮数值曲线结论。