更新test_mql迁移状态文档

PythonModels/README.md

@@ -1,23 +1,23 @@
 # PythonModels
 
-`PythonModels` 用于承接 `ModelicaModels` 的 Python 平台移植。
+`PythonModels` 用于承接 Modelica 和 AMESim 模型的 Python 平台移植。
 
-目标不是把 `.mo` 文件逐行翻译成 Python，而是建立一个可运行、可对比、可逐步逼近 `OpenModelica` 行为的 Python 仿真框架。
+目标不是逐行翻译源模型，而是建立可运行、可测试、可导出，并能与 OpenModelica 或 AMESim baseline 对比的 Python 仿真框架。
 
-当前状态不是“只有骨架”，而是“`Testmodel` 已有一版可运行的 ODE 近似实现，并具备基础结果导出与对比能力”。
+当前包含两条模型线：`Testmodel` 已有可运行的 ODE 近似和 OpenModelica 对比能力；`test_mql` 已形成 132 状态气动机械总闭包，正在按 AMESim baseline 做数值校准。
 
 ## 当前目录
 
 - `core/`: 通用基础设施
   包含组件基类、状态与端口数据结构、介质模型、网络装配、积分入口。
 - `components/`: 元件级 Python 实现
-  目前有 `Cylinder`、`Tank`、`Pipe`、`Orifice`、`Tee` 五类元件。
+  包含 `Cylinder`、`Tank`、`Pipe`、`Orifice`、`Tee`，以及 AMESim 气动和机械组件原语。
 - `systems/`: 系统级装配与闭合
-  当前只有 `TestModelSystem`，对应 `ModelicaModels/Testmodel.mo`。
+  包含旧 `TestModelSystem`，以及当前主线 `TestMqlSystem` 的配置、拓扑、closure、snapshot、端口写回和 RHS。
 - `reporting/`: 结果导出与对比
-  当前承接主变量 CSV、温度 CSV/SVG、Python 对 OpenModelica 的对比表与误差摘要导出。
+  承接 OpenModelica 对比，以及 AMESim 结果读取、`Data_Path` schema validation、comparison 和诊断报告。
 - `scripts/`: 运行脚本
-  当前入口是 `run_testmodel.py`。
+  包含 `run_testmodel.py`、`run_test_mql.py` 和 `run_test_mql_full_state_comparison.py`。
 - `baselines/`: 提交进仓库的稳定基线
   当前承接 Python 主变量基线和 Python 对 Modelica 的误差摘要基线。
 - `runs/`: 每次实际运行的默认输出目录
@@ -25,15 +25,18 @@
 
 当前关键文件：
 
-- `core/medium.py`: 理想气体近似介质 `IdealGasMedium`
-- `core/medium.py`: 温度相关的空气近似介质 `IdealGasMedium`
+- `core/medium.py`: 温度相关的理想气体近似介质 `IdealGasMedium`
+- `core/peng_robinson.py`: `test_mql` 使用的氦气 Peng-Robinson 物性
 - `core/network.py`: `SimulationNetwork`，负责组件注册、连接拓扑和状态向量拼装
 - `core/solver.py`: `integrate_ode()`，优先走 `SciPy solve_ivp`，缺依赖时回退到内置 RK4，并支持 `t_start == t_stop` 的零时长返回
 - `components/pipe.py`: 单阻容管道近似，入口压降 + 出口直连内容腔
 - `components/tee.py`: 三通的最小 stream 混合 helper
 - `systems/testmodel.py`: `Testmodel` 的系统装配壳与外部运行入口
 - `systems/testmodel_closure.py`: `Testmodel` 当前专用的闭合、初始化投影、分支求解与端口回写
+- `systems/test_mql.py`: `test_mql` 系统装配、132 状态总闭包和关键输出映射
+- `systems/test_mql_closure.py`: `test_mql` 气动网络 closure、snapshot、流量计算和端口写回
 - `reporting/testmodel_outputs.py`: `Testmodel` 的 CSV/SVG/对比摘要导出
+- `scripts/run_test_mql_full_state_comparison.py`: `test_mql` 短时域 AMESim comparison 和诊断入口
 - `scripts/run_testmodel.py`: 基线运行与程序化执行入口
 - `tests/test_pythonmodels_regression.py`: 当前 Python 基线回归测试
 
@@ -256,7 +259,7 @@ print(result.used_modelica_reference)
 ## 基线结果
 
 当前基线对比摘要来自：
-[testmodel_modelica_comparison_summary.txt](/home/lujz/projects/pressurization-transfer-system/PythonModels/baselines/testmodel/testmodel_modelica_comparison_summary.txt)
+[testmodel_modelica_comparison_summary.txt](baselines/testmodel/testmodel_modelica_comparison_summary.txt)
 
 当前四个主变量的最大误差为：
 
@@ -273,13 +276,14 @@ print(result.used_modelica_reference)
 
 当前已经完成：
 
-- 结构目录：组件清单、连接拓扑、全局参数、仿真设置和变量目录。
-- 结果读取：可直接解析 `.ame` 包内 `test_mql_.var` 和 `test_mql_.results`，并按 AMESim `Data_Path` 索引时序数据。
-- 物性：`test_mql` 使用氦气，物性库已补 Peng-Robinson 状态方程入口。
-- 气动装配：已装配 `PNCH023 / PNCH012 / PNOR001 / PNVO001` 参数目录和首版气动原语；气室内部使用绝对压力计算氦气 PR 密度，对外按 AMESim `press` 表压对齐。
-- 管路装配：已整理 `PNL0001 / PNL0002 / PNL0003 / PNL00R` 连接目录，保留源/目标组件和端口。
-- 机械装配：已整理 `PNRP17 / MECMAS21 / LSTP00A / LMECHN1 / F000 / FORC` 参数目录。
-- 机械原语：已补 `AmesimPistonGeometry`、`AmesimElasticEndstop`、`AmesimMassFrictionEndstops`，并用 AMESim 结果校验活塞几何、弹性端止动力和质量端口观测方向。
+- 解析 117 个组件、84 条 LINE 连接、直接组件接触、全局参数、仿真设置以及 AMESim 变量目录。
+- 直接读取 `.ame` 包内 `test_mql_.var` 和 `test_mql_.results`；baseline 包含 1002 个时间点和 1116 个保存变量。
+- 使用氦气 Peng-Robinson 物性，内部统一使用绝对压力，对外按 AMESim 表压和原始单位输出。
+- 实现 `PNCH023 / PNCH012 / PNOR001 / PNVO001`，以及 `PNL0001 / PNL0002 / PNL0003 / PNL00R` 管路和 `PN3NODE2 / P4NODE2` 节点语义。
+- 完成气动真实拓扑装配、canonical flow、端口写回、snapshot 和 112 状态气动 RHS。
+- 实现 `PNRP17 / MECMAS21 / LSTP00A / LMECHN1 / UD00 / FORC` 当前工况可确认的机械行为，并形成 20 状态机械闭包。
+- 将气动和机械部分组合成 132 状态总闭包，接入活塞体积反馈、气动力、外力、端止动和质量约束，可通过现有 solver 短时积分。
+- 建立关键 `Data_Path` 序列导出、output schema、validation、AMESim 插值比较、误差排序、端点诊断和 PNCH012 RHS 项拆解。
 
 当前确认的关键细节：
 
@@ -290,9 +294,11 @@ print(result.used_modelica_reference)
 - `MECMAS21` 的 `x1dup / v1dup / acc1dup` 是第二机械端口观测，相对 `x1 / v1 / acc1` 为反号，不是重复同值。
 - 本算例中 `MECMAS21` 的 `Fmin / Fmax / Fvisc / Ffric` 在 AMESim 结果里为零；当前只把这一工况能验证的部分写入测试，没有硬猜未激活碰撞/摩擦状态机。
 
-当前还不能宣称 `test_mql` 的 Python 时域仿真已经和 AMESim 全局一致。下一步应继续补气动网络动态方程和机械网络闭合，再用 `reporting/test_mql_comparison.py` 对 AMESim `Data_Path` 做全变量误差统计。
+当前默认 `0 -> 1e-5 s` comparison 已定位最大偏差为 `press@pn_c1_8`：初值对齐，但末值绝对误差约 `9.22849 Pa`。RHS 拆解显示边界体积功约 `0.026 W`，端口焓流约 `32722 W`，因此当前首要工作是比较 Python 的 `p4_port3_remote_chamber_to_line_flow` 与 AMESim 的 `dm1@pneumatic_69`，检查单位、符号、PNL0001 阻力和 `pnnode4_16` 节点平衡。
 
-## 当前架构判断
+当前还不能宣称 `test_mql` 的 Python 时域仿真已经和 AMESim 全局一致。完整说明、运行命令和下一步校准路径见 `AmesimModels/test_mql/README.md`。
+
+## Testmodel 当前架构判断
 
 如果按“组件正确 -> 网络闭合 -> 积分可跑 -> 结果对齐 -> 去近似”来看，当前大致处于：
 
@@ -306,7 +312,7 @@ print(result.used_modelica_reference)
 
 `Testmodel` 已有一版可运行、可导出、可对比的 Python 近似实现。
 
-## 已知限制
+## Testmodel 已知限制
 
 当前最主要的限制可以直接理解成下面几条：
 
@@ -332,7 +338,7 @@ print(result.used_modelica_reference)
 - 作为最终工程结论的唯一依据
 - 直接扩展到更复杂拓扑而不补通用连接器语义
 
-## 文件级现状
+## Testmodel 文件级现状
 
 按代码现状逐项看：
 
@@ -355,7 +361,7 @@ print(result.used_modelica_reference)
 - `baselines/`: 是当前稳定基线，不应该随着日常运行频繁改动。
 - `runs/`: 是当前默认运行产物目录，不是手写源代码，也不应该当作提交基线使用。
 
-## 当前主技术债
+## Testmodel 当前主技术债
 
 目前最主要的技术债，可以直接理解成下面 4 件事：