# test_mql

本目录记录 AMESim 模型 `test_mql.ame` 向 `PythonModels` 迁移时使用的源模型信息、结果对齐约定和当前进度。

## 目标

迁移目标不是复制 AMESim `.results` 中的观测值，而是建立真实的 Python 仿真链路：

`组件方程 -> SimulationNetwork/系统装配 -> closure -> snapshot/端口写回 -> RHS -> solver -> reporting/comparison`

Python 输出只有通过 AMESim baseline 对比后才能作为数值一致性依据。duplicate、反号或派生观测可以用于验证端口方向，但不能替代组件方程和网络闭合。

## 模型与源数据

- AMESim 源模型：`AmesimModels/test_mql.ame`
- Python 系统类：`PythonModels.systems.test_mql.TestMqlSystem`
- 结构运行入口：`PythonModels/scripts/run_test_mql.py`
- 132 状态比较入口：`PythonModels/scripts/run_test_mql_full_state_comparison.py`
- AMESim 组件数：117
- LINE 连接数：84
- 连续状态数：132
- 离散状态数：24
- 全局参数：`D1=20`、`D2=20`、`D3=14`、`P0=153`、`Pdq=1`、`V=15`、`cf=0.45`

`.ame` 文件是 tar 包，迁移和校验主要使用其中的：

- `test_mql_.cir`：组件、连接、参数表达式和生成代码线索。
- `test_mql_.param` / `test_mql_.data`：参数和结果配套数据。
- `test_mql_.modelinfo` / `test_mql_.sim`：状态数和仿真设置。
- `test_mql_.var` / `test_mql_.results`：AMESim `Data_Path` 目录和 baseline 时序。

当前结果解析器可读取 1002 个时间点和 1116 个保存变量，无需先转换成 CSV。

## 当前实现

当前已经完成：

- AMESim 组件、LINE 连接、直接组件接触、全局参数和变量目录解析。
- 氦气 Peng-Robinson 物性；内部使用绝对压力，AMESim `press` 按相对 `101300 Pa` 的表压输出。
- `PNCH023 / PNCH012 / PNOR001 / PNVO001` 气动组件。
- `PNL0001 / PNL0002 / PNL0003 / PNL00R` 管路动态或阻性关系。
- `PN3NODE2 / P4NODE2` 代数节点、真实邻接拓扑、canonical flow 和端口写回。
- `PNRP17 / MECMAS21 / LSTP00A / LMECHN1 / UD00 / FORC` 当前工况可确认的机械行为。
- 112 个气动状态和 20 个机械状态组成的 132 状态总闭包。
- 活塞运动学、变容气室机械反馈、气动力、外力、端止动和质量约束耦合。
- 关键 `Data_Path` 序列导出、schema validation、AMESim 插值 comparison、误差排序、端点诊断和变容气室 RHS 拆解。

主要实现位置：

- `PythonModels/systems/test_mql.py`
- `PythonModels/systems/test_mql_closure.py`
- `PythonModels/systems/test_mql_pneumatic.py`
- `PythonModels/systems/test_mql_mechanical.py`
- `PythonModels/systems/test_mql_lines.py`
- `PythonModels/components/amesim_pneumatic.py`
- `PythonModels/components/amesim_mechanical.py`
- `PythonModels/reporting/amesim_results.py`
- `PythonModels/reporting/test_mql_comparison.py`
- `PythonModels/scripts/run_test_mql_full_state_comparison.py`

## 当前对比结果

默认 comparison 使用 `0 -> 1e-5 s` 的短时域，目的是在数值误差扩散前检查初值、RHS 和局部耦合。

当前已确认：

- 最大绝对误差路径是 `press@pn_c1_8`。
- 初值已对齐：Python 约 `-1300 Pa`，AMESim 约 `-1300 Pa`。
- `t=1e-5 s` 时 Python 约 `-1290.75976 Pa`，AMESim 约 `-1299.98825 Pa`，末值绝对误差约 `9.22849 Pa`。
- `pn_c1_8` 的边界体积功只有约 `0.026 W`，端口焓流约 `32722 W`；当前偏差主要不像是活塞体积功导致。

这表明 132 状态仿真链路已经能够暴露真实偏差，但 PNL0001、节点流量、孔口或 PNCH012 方程仍需数值标定，尚不能声称已经达到 AMESim parity。

## 下一步

下一步只围绕当前最大偏差推进：

1. 导出 Python 的 `p4_port3_remote_chamber_to_line_flow`。
2. 与 AMESim 的 `dm1@pneumatic_69` 比较，先做 `g/s -> kg/s` 单位转换并确认符号方向。
3. 比较 `t=0` 和 `t=1e-5 s`，并用 `mgas1@pn_c1_8` 的有限差分交叉验证质量导数。
4. 若流量偏差明显，检查 `pneumatic_69` 的 PNL0001 `resistance_mass_flow`、参数和 `pnnode4_16` 节点平衡。
5. 若流量吻合，再校准 PNCH012 焓流、氦气物性以及质量/能量到压力导数的换算。

`pn_c1_8` 的直接主线是 `pneumatic_69`。`pneumatic_96` 属于 `pn_node3_8 -> pn_general_chamber` 固定气室支路，不是本轮流量诊断对象。

## 运行与验证

运行默认短时域 comparison：

```bash
python3 -m PythonModels.scripts.run_test_mql_full_state_comparison
```

运行相关测试：

```bash
python3 -m unittest tests.test_run_test_mql_full_state_comparison tests.test_test_mql_pnl0001_segment
```

运行全量测试：

```bash
python3 -m unittest discover -s tests -t .
```

## 对齐约定

- 组件 alias 和输出名优先保持 AMESim 原名及 `Data_Path`。
- `PortState.m_flow > 0` 表示流入当前组件。
- closure 先定义 canonical flow，再按各组件端口方向写回 `m_flow`。
- AMESim 管路质量流量通常以 `g/s` 保存，Python 内部统一使用 `kg/s`。
- CSV 是人工检查和交换格式，不是读取 AMESim baseline 的前置条件。
- 未完成真实 Python 输出对比前，不使用“与 AMESim 完全一致”之类结论。