气动端口变量供需合同

本合同在 Python 编译阶段和前端建模阶段使用，数值计算仍由 C 执行。它不改变状态、输出键、积分器、雅可比策略或管流算法。

物理连接与计算供需

nominalRole=bidirectional 表示气体可双向流动，不表示温度、压力、流量都可以任意选择提供者。side、旋转和镜像只负责显示，也不改变计算供需。

端口新增 computation 字段，与已有 variables 物理合同分开：

{
  "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 节，先完成逐变量映射表，再实现和验证。

两种校验模式

fixed：固定计算接口。目前用于 Amesim 三通、四通节点。与其连接时，双方声明需要的量都必须由对端声明提供，否则拒绝。参考口不能接阀门的压力/温度输入端；普通支路口不能接储气端来替代参考口。
equation：保留通过连接方程联合确定变量的能力。供需描述是该部件局部计算接口，不能仅凭两个局部输入相接就断言系统无解。两端均为此模式时，仍交由现有方程与能力检查处理，例如阻力串联和已支持的储气容腔耦合。

这一区分避免把所有物理网络当作定向信号线。局部供需校验通过，不保证全系统可以顺序计算。当前 C 生成器已对内置模型的气动计算增加依赖排序与局部循环划分，依据实际计算关系安排执行；它与本节的端口连接合同职责不同，见 C 求值排序规范。

节点支路的 referencePort: "port_2" 声明其 p/T 来源。模型校验会沿这种别名关系追溯，允许多级节点串接到真实储气状态，拒绝没有实际来源的参考环和中途中断的参考链。检查过程复用已确认的来源，不依赖 Python 递归深度。

一致的入口和提示

权威定义是组件类的 PORTS，从注册表发布到组件目录。JSON 中保存的端口信息只是快照，加载时使用当前目录恢复，执行 XML 也不接受工程自定义供需规则。

画布：供需不匹配的目标口不会作为可连接目标；接触吸附使用同一规则。悬停显示需要/提供的量和不兼容原因。
旧工程：保留供需不匹配的现有连线供检查、修改，不自动交换参考口或删线。原有的无效端口、重复占用等结构损坏处理不变。
检查模型及运行仿真：报告具体部件、端口和缺少的量，错误未处理前不启动求解。
JSON/XML/API/直接构造网络：后端独立检查，不能靠删除或伪造前端快照绕过。
两条 C 生成入口：在生成前再次检查连接及参考来源。

错误码：CONNECTION_VARIABLE_SUPPLY_MISSING、REFERENCE_SUPPLY_CYCLE、REFERENCE_SUPPLY_UNCONNECTED。

开发与验证

供需数据结构与后端检查位于 app/simulation/core/port_computation.py，前端对应实现位于 frontend/src/portComputation.ts。新增固定接口应在模型 PORTS 中声明，并提供合法连接、供需冲突、流向/连线顺序反转和参考链的测试。

本次没有修改浏览器工程、正式 test-mql-8.json 或历史数值基准。旧节点 smoke 测试改为将参考口接到储气状态；另保留明确的错误接线拒绝测试。历史 50 个冻结网络仍能通过新合同并执行原 C 数值对照。

浏览器测试从实际 Python 组件目录读取供需信息，覆盖目标筛选、悬停原因、错误旧连线保留和仿真前拦截，防止前后端合同不一致。

7.5 KiB Raw Blame History Unescape Escape