90 lines
6.7 KiB
Markdown
90 lines
6.7 KiB
Markdown
# AMESim 子模型公开组件迁移矩阵
|
||
|
||
状态：规划中
|
||
适用模型：`AmesimModels/test_mql.ame` / `PythonModels.systems.test_mql`
|
||
配套规范：[`component-model-authoring-spec-v1.md`](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` 路径，直到方程和求解能力补齐。
|