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

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

状态：规划中
适用模型：AmesimModels/test_mql.ame / PythonModels.systems.test_mql
配套规范：component-model-authoring-spec-v1.md

目标

本文档把 test_mql 中的 AMESim 子模型族拆成可执行的迁移批次。它不是组件注册清单；只有完成公开模型契约、方程实现、最小 XML 编译/仿真测试后，子模型才能加入某个 library.py 的 models 清单并出现在前端组件库中。

当前原则：

• 不把现有固定拓扑 TestMqlSystem 整体注册为公开拖拽组件。
• 不把机械、信号、事件元件提前伪装成可由当前气动求解器仿真的公开组件。
• 可先公开当前 app.simulation 求解链路能承载的气动元件：储能、阻性、孔口、三通/四通、准稳态管段。
• 对 AMESim 精确语义尚未复刻的元件，允许先做内部模型或文档化候选，不能在目录中标记为完成。

当前求解器能力边界

app.simulation 当前支持：

• 物理域：pneumatic。
• 端口变量：p、m_flow、h_outflow。
• 流量符号：m_flow > 0 表示流入当前组件。
• 网络方程：连接压力相等、连接流量和为零、组件压力-流量残差、stream 焓传播。
• 动态：半显式 ODE，动态组件提供质量和内能状态导数。
• 暂不支持：机械端口、信号端口仿真、事件系统、一般高指数 DAE、AMESim 气体定义组件对全局 medium 的动态切换。

子模型族矩阵

AMESim 子模型	数量	AMESim 角色	当前公开状态	建议目标	先决条件 / 限制
PNCH023	4	固定容积气室，带换热	候选公开	amesim_pnch023，storage	可基于 ThermodynamicVolumeComponent；需按 AMESim cvol/extemp/kth/sth/gi 复核质量、能量、换热方程。
PNCH012	8	变容气室，带换热	暂不公开	内部 test_mql 模型；后续 amesim_pnch012	体积由机械/活塞运动耦合；公开前需要机械域或明确外部体积输入协议。
PNOR001	8	常系数气动孔口	候选公开	amesim_pnor001，flow	可基于 AlgebraicComponent；需按 AMESim cq/area/Cv/Kv/flowset/gi 复核双向流、零压差正则化和单位换算。
PNVO001	8	信号调制气动孔口	暂不公开	内部固定算例；后续 amesim_pnvo001	依赖信号端口和事件/阶跃控制；当前公开组件库不支持信号仿真。可先拆出无信号开度参数版本，但不得等同 AMESim PNVO001。
PN3NODE2	8	三端气动节点，压力温度由 port 2 固定	候选公开	amesim_pn3node2，junctions	当前 Tee 是通用三通近似；AMESim port 2 参考温压语义和 stream 混合需单独测试。
P4NODE2	8	四端气动节点，压力温度由 port 2 固定	候选公开	amesim_p4node2，junctions	需要新增四端 junction 基类/模型；复核 port 2 参考温压和多支路混合。
PNL00R	4	管路纯阻性摩擦段	候选公开	amesim_pnl00r，flow	可基于准稳态阻性管；需按 AMESim PNL00R 参数和摩擦公式复核。
PNL0001	20	C-R 动态管路	先内部	后续 amesim_pnl0001	含管内储气动态和摩擦耦合；当前 pipe 只是准稳态阻性模型，不能直接宣称等价。
PNL0002	8	R-C-R 动态管路	先内部	后续 amesim_pnl0002	需要多段动态状态和端口/中心阻力结构测试。
PNL0003	8	C-R-C 动态管路	先内部	后续 amesim_pnl0003	当前 test_mql 仍在诊断事件早期导数差异；公开前必须完成 AMESim baseline 对齐。
PNPL01	16	零气动流源	暂不公开	后续边界/源元件	当前网络要求物理端口连接并由组件/储能闭合；需设计一端口源/边界组件契约。
PNGD00	1	氦气气体定义	暂不公开	medium 配置，不是画布物理组件	应映射为系统/介质设置；不能作为普通可连接组件注册。
PNRP17	8	气动活塞与移动体耦合	暂不公开	内部固定算例；后续跨域组件	依赖气动端口和机械端口耦合；需要新增机械域、跨域状态和连接规则。
MECMAS21	10	一维平动质量	暂不公开	后续机械域组件	当前无机械端口、力/速度/位移连接规则和机械求解器。
LMECHN1	2	动态线性机械节点	暂不公开	后续机械域组件	同上。
LSTP00A	8	弹性接触/端止动	暂不公开	后续机械域组件	依赖机械接触和事件/非光滑力模型。
F000	16	零力源	暂不公开	后续机械边界组件	依赖机械域。
FORC	2	信号转力	暂不公开	后续信号-机械跨域组件	依赖信号端口与机械端口。
STEP0	8	阶跃信号源	暂不公开	后续信号源组件	当前公开求解器不支持信号端口仿真和事件。
UD00	2	分段线性信号源	暂不公开	后续信号源组件	同上。
DIRECT	44	直接连接	不注册为组件	System XML Connection	连接不是组件；物理连接必须保持无方向端点语义。

建议迁移批次

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

优先级最高，但仍需先补 AMESim 公式与测试：

• amesim_pnor001
• amesim_pnl00r
• amesim_pnch023
• amesim_pn3node2
• amesim_p4node2

完成定义：每个模型必须有 MODEL_TYPE/MODEL_VERSION/PORTS/PARAMETERS/RESULT_VARIABLES/DISPLAY/create()，并补目录、参数边界、残差、零流量/反向流、最小 XML 编译和短时仿真测试。

批次 2：动态管路

• amesim_pnl0001
• amesim_pnl0002
• amesim_pnl0003

这些模型是 test_mql 对齐工作的核心，公开前需要先在内部固定算例中完成 AMESim baseline 诊断闭环。不能用当前准稳态 pipe 替代动态管路并宣称等价。

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

• STEP0、UD00、PNVO001
• MECMAS21、LMECHN1、LSTP00A、F000、FORC、PNRP17

这些需要先设计新物理域或信号求解协议，包括端口变量、连接规则、XML 协议、前端连线兼容和最小闭合系统测试。

下一步执行建议

1. 先为 AMESim 公开组件建立独立库，例如 app.simulation.components.amesim，不要混入 experimental。
2. 先只登记一个完成度最高的气动代数组件，例如 PNOR001 或 PNL00R。
3. 每登记一个模型，都同步补充测试和目录校验，确认 /api/components/catalog、System XML 编译和最小仿真都通过。
4. 动态管路和机械/信号组件继续保留在内部 test_mql 路径，直到方程和求解能力补齐。