Merge model-development into main

app/simulation/README.md

@@ -2,9 +2,9 @@
 
 `app.simulation` 是 SystemSimulationApp 的仿真子包，用于承接模型定义、系统装配、数值求解和结果导出。
 
-目标不是把 `.mo` 文件逐行翻译成 Python，而是建立一个可运行、可对比、可逐步逼近 `OpenModelica` 行为的 Python 仿真框架。
+目标不是逐行翻译源模型，而是建立可运行、可测试、可导出，并能与 OpenModelica 或 AMESim baseline 对比的 Python 仿真框架。
 
-当前状态不是“只有骨架”，而是“`Testmodel` 已有一版可运行的 ODE 近似实现，并具备基础结果导出与对比能力”。
+当前包含两条模型线：`Testmodel` 已有可运行的 ODE 近似和 OpenModelica 对比能力；`test_mql` 已形成 132 状态气动机械总闭包，正在按 AMESim baseline 做数值校准。
 
 ## 当前目录
 
@@ -14,9 +14,11 @@
 - `components/experimental/storage/`: 气瓶和贮箱等储能元件。
 - `components/experimental/flow/`: 对外注册的阻性管道和孔板等流动元件。
 - `components/experimental/junctions/`: 三通等连接节点。
+- `components/amesim/`: AMESim 气动、信号和机械组件原语。
 - `systems/`: 通用仿真网络与 XML 驱动系统装配。
-- `examples/testmodel/`: 固定 TestModel、专用闭合逻辑和运行入口。
-- `reporting/`: CSV、SVG、运行报告和 Modelica 对比结果导出。
+- `examples/testmodel/`: 固定 TestModel、专用闭合逻辑、基线运行入口，以及 test_mql 当前迁移过程中的系统装配和诊断脚本。
+- `examples/test_mql/`: AMESim `test_mql` 的前端调用运行入口。
+- `reporting/`: CSV、SVG、运行报告、Modelica 对比结果、AMESim 结果读取和诊断报告导出。
 - `registry.py`: 从已启用库清单受控发现、校验和实例化组件。
 - `paths.py`: 项目、运行产物、基准和 Modelica 参考结果路径。
 
@@ -35,17 +37,21 @@ RESULT_VARIABLES / DISPLAY / create()`，再把类路径加入库清单。完整
 
 当前关键文件：
 
-- `core/medium.py`: 理想气体近似介质 `IdealGasMedium`
-- `core/medium.py`: 温度相关的空气近似介质 `IdealGasMedium`
+- `core/medium.py`: 温度相关的理想气体近似介质 `IdealGasMedium`
+- `core/peng_robinson.py`: `test_mql` 使用的氦气 Peng-Robinson 物性
 - `systems/network.py`: `SimulationNetwork`，负责组件注册、连接拓扑和状态向量拼装
 - `solvers/solver.py`: `integrate_ode()`，优先走 `SciPy solve_ivp`，缺依赖时回退到内置 RK4，并支持 `t_start == t_stop` 的零时长返回
 - `examples/testmodel/dynamic_pipe.py`: TestModel 专用单阻容管道近似，入口压降 + 出口直连内容腔
 - `components/experimental/junctions/tee.py`: 三通的最小 stream 混合 helper
 - `examples/testmodel/system.py`: `Testmodel` 的系统装配壳与外部运行入口
 - `examples/testmodel/closure.py`: `Testmodel` 当前专用的闭合、初始化投影、分支求解与端口回写
+- `examples/testmodel/test_mql.py`: `test_mql` 系统装配、132 状态总闭包和关键输出映射
+- `examples/testmodel/test_mql_closure.py`: `test_mql` 气动网络 closure、snapshot、流量计算和端口写回
 - `reporting/testmodel_outputs.py`: `Testmodel` 的 CSV/SVG/对比摘要导出
-- `examples/testmodel/run.py`: 基线运行与程序化执行入口
-- `tests/`: 当前组件契约、XML、通用系统和结果导出测试
+- `reporting/amesim_results.py`: AMESim 结果读取入口
+- `examples/testmodel/run_test_mql_full_state_comparison.py`: `test_mql` 短时域 AMESim comparison 和诊断入口
+- `examples/testmodel/run_test_mql.py`: test_mql 基线运行与程序化执行入口
+- `tests/`: 当前组件契约、XML、通用系统、AMESim 迁移和结果导出测试
 
 ## 当前阶段进度
 
@@ -279,7 +285,35 @@ print(result.used_modelica_reference)
 
 这说明在当前基线工况下，Python 版主变量已经能较好贴近 OpenModelica 结果。
 
-## 当前架构判断
+## AMESim test_mql 当前进度
+
+`test_mql` 是从 `AmesimModels/test_mql.ame` 新增迁移的 AMESim 模型，当前只在独立路径下推进，不修改旧 `testmodel`。新增命名保持 AMESim 原始别名和 `Data_Path`，方便后续逐变量对齐。
+
+当前已经完成：
+
+- 解析 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 项拆解。
+
+当前确认的关键细节：
+
+- `PNRP17` 活塞腔体积使用环形有效面积 `piston_area - rod_area`。
+- `LSTP00A` 的 `gap` 观测单位是 mm，计算接触力前必须转换为 m。
+- `PNCH023` 固定气室初始压力来自 `P0=153 bar` 的绝对压力；AMESim `press` 输出为相对 `101300 Pa` 的表压。
+- `PNCH012` 变容腔初始压力对齐 AMESim 的 `1 bar` 绝对压力，`vol` 输出单位为 cm3，且末端体积等于基础死容积加对应活塞 `vol1`。
+- `MECMAS21` 的 `x1dup / v1dup / acc1dup` 是第二机械端口观测，相对 `x1 / v1 / acc1` 为反号，不是重复同值。
+- 本算例中 `MECMAS21` 的 `Fmin / Fmax / Fvisc / Ffric` 在 AMESim 结果里为零；当前只把这一工况能验证的部分写入测试，没有硬猜未激活碰撞/摩擦状态机。
+
+当前默认 `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 当前架构判断
 
 如果按“组件正确 -> 网络闭合 -> 积分可跑 -> 结果对齐 -> 去近似”来看，当前大致处于：
 
@@ -293,7 +327,7 @@ print(result.used_modelica_reference)
 
 `Testmodel` 已有一版可运行、可导出、可对比的 Python 近似实现。
 
-## 已知限制
+## Testmodel 已知限制
 
 当前最主要的限制可以直接理解成下面几条：
 
@@ -319,7 +353,7 @@ print(result.used_modelica_reference)
 - 作为最终工程结论的唯一依据
 - 直接扩展到更复杂拓扑而不补通用连接器语义
 
-## 文件级现状
+## Testmodel 文件级现状
 
 按代码现状逐项看：
 
@@ -342,7 +376,7 @@ print(result.used_modelica_reference)
 - `tests/baselines/simulation/`: 是当前稳定基线，不应该随着日常运行频繁改动。
 - `app/data/simulation-runs/`: 是默认运行产物目录，不是手写源代码，也不应该提交。
 
-## 当前主技术债
+## Testmodel 当前主技术债
 
 目前最主要的技术债，可以直接理解成下面 4 件事：