SystemSimulationApp/docs/amesim-component-migration-matrix.md

AMESim 子模型公开组件迁移矩阵

状态：22 个模型已在临时 AMESim 库完成第一版公开，持续校准中

适用模型：AmesimModels/test_mql.ame / app.simulation.examples.test_mql.system

配套规范：component-model-authoring-spec-v1.md

目标

本文档记录 test_mql 中 AMESim 子模型族的公开状态和后续校准批次。实际注册清单以 app/simulation/components/amesim/library.py 为准。

当前原则：

• 不把现有固定拓扑 TestMqlSystem 整体注册为公开拖拽组件。
• 第一版公开只表示模型契约、目录、XML 编译和最小仿真链路已接通，不表示 AMESim 精确语义已完成复刻。
• 气动、标量信号和一维机械模型按当前求解链路能力公开；PNRP17 已打通首个实时气动—机械跨域闭合，事件和更一般跨域 DAE 仍保留明确限制。
• 固定算例专用的校准原语留在 examples/test_mql/，不与公共组件目录混为同一实现。

当前求解器能力边界

app.simulation 当前支持：

• 物理域：pneumatic、标量 signal 和一维 mechanical。
• 端口变量：气动 p/m_flow/h_outflow 及定向 volume/volume_flow、信号 signal、机械 x/v/f。
• 流量符号：m_flow > 0 表示流入当前组件。
• 网络方程：气动连接压力相等、流量和为零、组件压力-流量残差、stream 焓传播和移动边界容积传播；标量信号传播；机械 x/v 等值和 f 平衡。
• 动态：半显式 ODE，动态组件提供质量和内能状态导数。
• 暂不支持：完整事件系统、一般高指数 DAE、任意多域连接变量，以及从 PNGD00 自动批量导入其他气体。公共编译链已经支持“介质 + 物性计算方法”定义元件：gi=0 使用内置空气理想气体，gi=1..99 引用画布中的显式介质物性实例；介质定义内部通过 property_model 下拉接口选择计算方法。氦气已提供 Peng-Robinson 首版。

子模型族矩阵

AMESim 子模型	数量	AMESim 角色	当前公开状态	建议目标	先决条件 / 限制
PNCH023	4	固定容积气室，带换热	第一版公开	amesim_pnch023，storage	已基于 ThermodynamicVolumeComponent 接入公开契约；仍需按 AMESim cvol/extemp/kth/sth/gi 复核质量、能量、换热方程。
PNCH012	8	变容气室，带换热	实时变容第一版公开	amesim_pnch012，storage	保留 vol1..4/dvol1..4 SI 参数，并可从 PNRP17 经气动端口接收实时外部容积与变化率；已完成代表性联合仿真，仍需完整 test_mql baseline 校准。
PNOR001	8	常系数气动孔口	第一版公开	amesim_pnor001，flow	已接入代数组件公开契约；仍需按 AMESim cq/area/Cv/Kv/flowset/gi 复核双向流、零压差正则化和单位换算。
PNVO001	8	信号调制气动孔口	第一版公开	amesim_pnvo001，flow	已接入名为 res 的标量信号输入端口，可由 amesim_step0 驱动开度；精确事件语义和 AMESim baseline 仍留后续修模。固定开度变体 amesim_pnvo001_fixed 继续保留。
PN3NODE2	8	三端气动节点，压力温度由 port 2 固定	第一版公开	amesim_pn3node2，junctions	已接入三端等压、流量守恒基础版；AMESim port 2 参考温压语义和 stream 混合仍需单独测试。
P4NODE2	8	四端气动节点，压力温度由 port 2 固定	第一版公开	amesim_p4node2，junctions	已接入四端等压、流量守恒基础版；仍需复核 port 2 参考温压和多支路混合。
PNL00R	4	管路纯阻性摩擦段	第一版公开	amesim_pnl00r，flow	已接入准稳态阻性管公开契约；仍需按 AMESim PNL00R 参数和摩擦公式复核。
PNL0001	20	C-R 动态管路	第一版公开	amesim_pnl0001，flow	已按公开契约接入两状态管内容积 + port 1 摩擦残差 + mode 2 换热项；仍需后续按 AMESim baseline 复核 pn2pipefr_ 和 mode 1 多方语义。
PNL0002	8	R-C-R 动态管路	第一版公开	amesim_pnl0002，flow	已按公开契约接入中心两状态容积 + 两端半长摩擦残差 + mode 2 换热项；仍需后续按 AMESim baseline 复核 pn2pipefr_ 和 mode 1 多方语义。
PNL0003	8	C-R-C 动态管路	第一版公开	amesim_pnl0003，flow	已按公开契约接入两端四状态容积 + 中心摩擦流 + mode 2 换热项；大压差动态闭合和 AMESim baseline 误差仍留后续修模。
PNPL01	16	零气动流源	第一版公开	amesim_pnpl01，boundary	当前实现一端零流边界，只约束端口质量流量为 0；压力源/外部边界语义留后续扩展。
PNGD00	1	氦气气体定义	氦气 Peng-Robinson 首版公开	amesim_helium_medium，media	已映射源模型 fluidType=12/eosType=6；密度和压力使用 PR EOS，热量学暂用手册参考点的定比热闭合。完整压力相关残余焓、比热和真实气体临界流仍待状态相关物性接口。
PNRP17	8	气动活塞与移动体耦合	第一版公开	amesim_pnrp17，mechanical	已接入 1 个气动端口和 4 个一维机械端口，按 dp/dr/x0/gi 计算环形有效面积、扫掠容积、容积变化率和表压作用力；已与 PNCH012、双质量块跑通 System XML 联合仿真，完整事件语义和 AMESim baseline 仍待校准。
MECMAS21	10	一维平动质量	第一版公开	amesim_mecmas21，mechanical	已接入一维机械端口 x/v/f、双端质量状态和基本摩擦/限位项，并跑通零力源与信号力源最小 System XML；完整 AMESim 接触/事件语义仍留后续对齐。
LMECHN1	2	动态线性机械节点	第一版公开	amesim_lmechn1，mechanical	已接入 9 端一维机械节点、端口位移/速度等值和节点力平衡，并跑通 FORC -> LMECHN1 -> MECMAS21 最小 System XML；端口朝向/符号细节留后续 AMESim baseline 对齐。
LSTP00A	8	弹性接触/端止动	第一版公开	amesim_lstp00a，mechanical	已接入两端一维机械端口、相对位移/速度接触力和最小 System XML 仿真；当前是连续罚函数基础版，完整 AMESim 事件/非光滑接触语义留后续 baseline 对齐。
F000	16	零力源	第一版公开	amesim_f000，mechanical	已作为一端机械零力边界公开，约束端口力为 0。
FORC	2	信号转力	第一版公开	amesim_forc，mechanical	已接入信号输入 res 到机械端口力源，可由 STEP0/UD00 驱动质量组件。
STEP0	8	阶跃信号源	第一版公开	amesim_step0，signals	已接入标量信号输出端口和求解时信号传播；当前是基础阶跃，不含更复杂事件调度语义。
UD00	2	分段线性信号源	第一版公开	amesim_ud00，signals	已接入标量信号输出端口、8 段 start/end/t 参数、循环模式和 System XML signal connection；当前按迁移实现语义处理最后一段外推，AMESim baseline 仍留后续复核。
DIRECT	44	直接连接	不注册为组件	System XML Connection	连接不是组件；物理连接必须保持无方向端点语义。

建议迁移批次

批次 1：已进入当前气动求解器的公开组件

以下模型已完成第一版公开，后续重点是 AMESim 公式和 baseline 精修：

• amesim_pnor001
• amesim_pnl00r
• amesim_pnch023
• amesim_pn3node2
• amesim_p4node2

这些模型已有 MODEL_TYPE/MODEL_VERSION/PORTS/PARAMETERS/RESULT_VARIABLES/DISPLAY/create() 契约和目录、XML、最小仿真测试；第一版状态不代表数值对齐完成。

批次 2：动态管路

• amesim_pnl0001：已第一版公开，保留后续 baseline 精修。
• amesim_pnl0002：已第一版公开，保留后续 baseline 精修。
• amesim_pnl0003：已第一版公开，保留后续 baseline 精修。

这些模型是 test_mql 对齐工作的核心。当前已先按动态组件契约公开，后续仍需要在固定算例和 AMESim baseline 上复核摩擦、换热、多方模式和大压差动态闭合；不能用准稳态 pipe 替代这些动态管路并宣称等价。

批次 3：信号、事件、机械和跨域组件

• STEP0：已第一版公开。
• PNVO001：已第一版公开，保留固定开度变体。
• UD00：已第一版公开。
• MECMAS21、F000、FORC、LSTP00A、LMECHN1：已第一版公开。
• PNRP17：已第一版公开，并完成 PNCH012 + 双质量块跨域闭合测试。

当前已具备一对一标量信号传播、一维机械端口基础闭合、弹性接触基础件、9 端机械节点，以及针对移动边界的气动容积定向传播与二次代数闭合。下一阶段重点是完整 test_mql 拓扑和 AMESim baseline 校准。

下一步执行建议

1. 以 app.simulation.components.amesim.library 的 22 个模型为公开清单唯一来源。
2. 优先校准 PNCH023 / PNOR001 / PN3NODE2 / P4NODE2 / PNL00R 与动态管路的 AMESim baseline 误差。
3. 每次调整模型都同步补充目录校验、参数边界、System XML 编译和最小仿真测试。
4. 用完整或代表性的 test_mql 画布校准 PNRP17 + PNCH012 的压力、力、位移和容积轨迹，并补齐事件边界语义。