102 lines
8.7 KiB
Markdown
102 lines
8.7 KiB
Markdown
# 气动端口变量供需合同
|
||
|
||
文档版本：1.1.1
|
||
修订日期：2026-09-12
|
||
核对代码基线：`22579e5`；本次版本号仅标注文档，不改变模型版本或协议版本。
|
||
|
||
本合同在 Python 编译阶段和前端建模阶段使用，数值计算仍由 C 执行。它不改变状态、输出键、积分器、雅可比策略或管流算法。
|
||
|
||
## 物理连接与计算供需
|
||
|
||
`nominalRole=bidirectional` 表示气体可双向流动，不表示温度、压力、流量都可以任意选择提供者。`side`、旋转和镜像只负责显示，也不改变计算供需。
|
||
|
||
端口新增 `computation` 字段，与已有 `variables` 物理合同分开：
|
||
|
||
```json
|
||
{
|
||
"name": "port_2",
|
||
"computation": {
|
||
"mode": "fixed",
|
||
"inputs": ["p", "T"],
|
||
"outputs": ["m_flow", "H_flow"]
|
||
}
|
||
}
|
||
```
|
||
|
||
四个量分别是压力（Pa）、温度（K）、质量流率（kg/s）和能量流率（W）。`H_flow` 是用于接口校验的能量传递量，不是比焓 `h_outflow`（J/kg），不增加新的运行时端口字段。当前 C 内核仍使用质量流率与比焓计算能量传递。
|
||
|
||
`inputs` 是该接口从对端取得的量；`outputs` 是该接口向对端提供的量；输出不必全部被对端使用，例如堵头只提供零流量，不读取节点传出的温度。
|
||
|
||
## 当前声明范围
|
||
|
||
| 端口 | 需要 | 提供 |
|
||
| --- | --- | --- |
|
||
| PN3NODE2/P4NODE2 的 port_2 | p、T | m_flow、H_flow |
|
||
| PN3NODE2/P4NODE2 的其他口 | m_flow、H_flow | p、T（来自 port_2） |
|
||
| PNCH023/012、PNL0003、实验气瓶/气罐的储气口 | m_flow、H_flow | p、T |
|
||
| PNL0001 的 port_2 | m_flow、H_flow | p、T |
|
||
| PNL0001 的 port_1、PNL0002 两端、阀门、孔口及阻力管 | p、T | m_flow、H_flow |
|
||
| PNRP17 的气动口 | p、T | m_flow、H_flow（零） |
|
||
| PNPL01 堵头 | 无 | m_flow、H_flow（零） |
|
||
| 实验 Tee | 由连接方程共同确定 | 无固定的参考温度来源声明 |
|
||
|
||
本次覆盖上述四类气动量。容积、容积变化率、机械连接和信号连接继续使用原有校验及方程；不将其默认为已经完成逐变量供需校验。
|
||
|
||
## 与 Amesim 接口的一致性边界
|
||
|
||
2026-09-10 对照本机 Amesim 2404 的子模型端口变量表。下表比较的是变量接口，不能据此推断所有数值公式、默认参数和完整仿真结果均已一致。
|
||
|
||
| 模型 | 已对齐部分 | 尚未完整表达或有意不同的部分 |
|
||
| --- | --- | --- |
|
||
| PNOR001、PNVO001、PNL00R | 两侧 p/T 输入、质量和能量流率输出的方向 | 输出之间的符号反转/别名、每个输出的全部依赖尚未作为通用元数据声明 |
|
||
| PNL0001/2/3、PNCH023 | 对应端口四个核心量的供需方向 | Amesim 的温度/压力状态在本实现中由质量/内能状态换算，接口表示并非逐字段相同 |
|
||
| PNCH012 | 四个核心气动量方向 | 各端口的容积、容积变化率输入及默认零值尚未纳入 `computation` |
|
||
| PN3NODE2、P4NODE2 | port_2 参考输入，其他端口 p/T 别名，质量/能量汇总方向 | 容积及容积变化率的输入、汇总与默认值尚未纳入 `computation` |
|
||
| PNRP17 | 气动 p/T 输入和零质量/能量流率输出的方向 | 扫掠容积、容积变化率输出、机械端各变量的供需未纳入新合同；零流量性质目前写在模型说明而非通用常量字段 |
|
||
| PNPL01 | 不需要温度/压力输入，提供零质量/能量流率 | Amesim 还提供零容积、零容积变化率；常量来源及这两个量尚未纳入 `computation` |
|
||
| F000、FORC、MECMAS21、LSTP00A、LMECHN1 | 保留现有机械变量与 C 连接方程 | 尚未逐变量声明完整因果关系；MECMAS21 原端口含加速度，当前统一机械端口仅含 x/v/f；原模型取反别名还需在映射中明确坐标变换 |
|
||
| STEP0、UD00、PNVO001/FORC 控制信号 | 现有信号输入/输出方向检查 | 尚无统一的状态/常量/别名/公式依赖描述，不能把所有信号的物理量和单位视为已完整对齐 |
|
||
| PNVO001 固定开度变体 | 气动侧四量方向 | 本项目用开度参数替代原 PNVO001 的控制信号，是有意设计的变体 |
|
||
| 实验组件、介质定义组件 | 使用本项目自己的模型/介质注册合同 | 不作为 Amesim 原子模型完整接口的等价证明 |
|
||
|
||
本项目所有气动端口都带有通用的 `volume/volume_flow` 物理字段，不代表每个元件都按 Amesim 同样方式读取和提供它们；是否存在字段与是否有正确供需声明需要分别核对。
|
||
|
||
依据为本机 `F:/amesim2404/amesim/` 下 `libpn/submodels/`、`libpcd/submodels/`、`libmec/submodels/`、`libsig/submodels/` 中对应编号的 `.c` 文件。新增元件应遵守 [组件模型建模规范第 7 节](component-model-authoring-spec-v1.md#7-端口建模规范)，先完成逐变量映射表，再实现和验证。
|
||
|
||
## 两种校验模式
|
||
|
||
- `fixed`：固定计算接口。目前用于 Amesim 三通、四通节点。与其连接时，双方声明需要的量都必须由对端声明提供，否则拒绝。参考口不能接阀门的压力/温度输入端；普通支路口不能接储气端来替代参考口。
|
||
- `equation`：保留通过连接方程联合确定变量的能力。供需描述是该部件局部计算接口，不能仅凭两个局部输入相接就断言系统无解。两端均为此模式时，仍交由现有方程与能力检查处理，例如阻力串联和已支持的储气容腔耦合。
|
||
|
||
这一区分避免把所有物理网络当作定向信号线。局部供需校验通过，不保证全系统可以顺序计算。当前 C 生成器已对内置模型的气动计算增加依赖排序与局部循环划分，依据实际计算关系安排执行；它与本节的端口连接合同职责不同，见 [C 求值排序规范](native-evaluation-schedule.md)。
|
||
|
||
节点支路的 `referencePort: "port_2"` 声明其 p/T 来源。模型校验会沿这种别名关系追溯，允许多级节点串接到真实储气状态，拒绝没有实际来源的参考环和中途中断的参考链。检查过程复用已确认的来源，不依赖 Python 递归深度。
|
||
|
||
## 一致的入口和提示
|
||
|
||
权威定义是组件类的 `PORTS`，从注册表发布到组件目录。JSON 中保存的端口信息只是快照，加载时使用当前目录恢复，执行 XML 也不接受工程自定义供需规则。
|
||
|
||
- 画布：供需不匹配的目标口不会作为可连接目标；接触吸附使用同一规则。悬停显示需要/提供的量和不兼容原因。
|
||
- 旧工程：保留供需不匹配的现有连线供检查、修改，不自动交换参考口或删线。原有的无效端口、重复占用等结构损坏处理不变。
|
||
- 检查模型及运行仿真：报告具体部件、端口和缺少的量，错误未处理前不启动求解。
|
||
- XML 语义、JSON 执行入口及直接构造网络：后端独立检查，不能靠删除或伪造前端快照绕过。工程 JSON 的保存/加载接口仅做存储结构检查，不执行完整供需检查。
|
||
- 两条 C 生成入口：在生成前再次检查连接及参考来源。
|
||
|
||
错误码：`CONNECTION_VARIABLE_SUPPLY_MISSING`、`REFERENCE_SUPPLY_CYCLE`、`REFERENCE_SUPPLY_UNCONNECTED`。
|
||
|
||
## 开发与验证
|
||
|
||
供需数据结构与后端检查位于 `app/simulation/core/port_computation.py`，前端对应实现位于 `frontend/src/portComputation.ts`。新增固定接口应在模型 `PORTS` 中声明，并提供合法连接、供需冲突、流向/连线顺序反转和参考链的测试。
|
||
|
||
当前正确性/性能活动输入按[优化基准模型约定](optimization-benchmark-model.md)使用修正八路文件。历史 50 个冻结网络是独立回归基准，不是四路工程，不能替代当前 AME/JSON 的逐项核对。
|
||
|
||
浏览器测试从实际 Python 组件目录读取供需信息，覆盖目标筛选、悬停原因、错误旧连线保留和仿真前拦截，防止前后端合同不一致。
|
||
|
||
## 注册与工程导入边界（2026-09-12 修订）
|
||
|
||
供需规则以当前注册表为准，但工程快照首先必须通过浏览器结构解析。目录返回的信号端口可能带 `positiveFlowDirection: null`，工程解析器不接受该值；生成快照时省略此字段，不用目录对象直接替代工程对象，见[目录协议](component-library-spec-v1.md)。
|
||
|
||
动态端口须同时实现后端有效端口和前端参数变更/连线处理；当前 LMECHN1 有专用逻辑，供需合同不自动提供通用动态端口能力。注册演练的信号源不涉及气动固定参考口，不能用该演练代替参考链或逆流验收。
|
||
|
||
当前 XML/后端网络允许信号输出扇出，网页模型检查仍限制每个显示端口恰好一条连接。后端对普通未接活动端口的 XML 警告、原生模型的必接要求及前端错误提示应分别测试，不能以一个入口的允许行为推断其他入口。
|