前端进度条性能优化、仿真结束后后处理优化；后端C代码生成流程优化：先识别来源，再按照已知未知量需求排序，最后局部求解
This commit is contained in:
ljz committed
1 parent
0dcb465d84
commit
91bd9fb252
77 files changed
+11223
-551
No files matched your search
@@ -3,6 +3,7 @@
|
||||
状态：2026-09-10 更新为 Python 声明、C 数值实现
|
||||
适用对象：人工开发者、代码生成工具和 AI 编程助手
|
||||
配套读取规范：[组件库分类、发现与读取规范 v1](component-library-spec-v1.md)
|
||||
端口供需规范：[气动端口变量供需合同](port-computation-contract.md)
|
||||
|
||||
## 1. 文档目标
|
||||
|
||||
@@ -147,9 +148,12 @@ def create(
|
||||
PortDefinition.pneumatic(
|
||||
"port_a",
|
||||
nominal_role="bidirectional",
|
||||
computation=THERMODYNAMIC_SUPPLY,
|
||||
)
|
||||
```
|
||||
|
||||
上例适用于提供温度/压力的储气端，`THERMODYNAMIC_SUPPLY` 从 `core.port_computation` 导入。阀门或管道阻力端应按实际模型选择 `FLOW_SUPPLY`；不能给所有气动端口套用同一个供需模板。
|
||||
|
||||
气动端口包含：
|
||||
|
||||
| 变量 | 角色 | 连接规则 | SI 单位 |
|
||||
@@ -157,12 +161,14 @@ PortDefinition.pneumatic(
|
||||
| `p` | `effort` | `equal` | `Pa` |
|
||||
| `m_flow` | `flow` | `sumToZero` | `kg/s` |
|
||||
| `h_outflow` | `stream` | `streamMix` | `J/kg` |
|
||||
| `volume` | `signal` | `directed` | `m3` |
|
||||
| `volume_flow` | `signal` | `directed` | `m3/s` |
|
||||
|
||||
必须遵守：
|
||||
|
||||
- `m_flow > 0` 表示质量流入当前组件。
|
||||
- `nominal_role` 只用于界面和默认布局，不限制实际流向。
|
||||
- 物理连接是非因果的，连接线端点顺序不代表流向。
|
||||
- 物理连接的端点顺序不代表流向；具体子模型仍可规定固定的变量供需，例如 PN3NODE2 的参考口。
|
||||
- 所有声明端口必须使用 `register_declared_port()` 创建。
|
||||
- `DISPLAY.ports` 必须与 `PORTS` 名称集合完全一致。
|
||||
- 分支连接使用三通等连接元件，不能让一个物理端口直接连接多条边。
|
||||
@@ -174,6 +180,49 @@ PortDefinition.pneumatic(
|
||||
- 把 `port_a` 固定解释为真实入口、把 `port_b` 固定解释为真实出口。
|
||||
- 直接绕过端口状态读写其他组件对象。
|
||||
|
||||
### 7.1 新元件先写逐变量接口表
|
||||
|
||||
新模型必须先在模型说明中列明每个端口的下列信息，再写元数据和 C 代码：
|
||||
|
||||
| 信息 | 必须回答的问题 |
|
||||
| --- | --- |
|
||||
| 物理含义、机器名、SI 单位 | 传递的是温度还是比焓？能量还是能量流率？ |
|
||||
| 提供方/使用方 | 该变量由本部件提供、从对端取得，还是需要连接方程共同确定？ |
|
||||
| 提供方式 | 来自当前状态、固定值、另一个端口的别名，还是由公式计算？ |
|
||||
| 计算依赖 | 计算该输出具体需要哪些输入、状态和参数？不要只写“依赖某部件”。 |
|
||||
| 符号与坐标 | 正号代表流入还是流出？机械量采用什么方向？映射原模型时是否取反？ |
|
||||
| 必需性及默认值 | 缺少对端变量时能否用有物理依据的默认值？何时应当报错？ |
|
||||
| 条件变化 | 参数是否改变可用端口、输入输出关系？反向流、零流量或切换时怎样处理？ |
|
||||
|
||||
固定参数放在 `PARAMETERS`，例如管径、长度、初始温度 `T0`；随仿真变化的端口量放在接口定义中，例如当前温度 `T`。固定开度变体可以有意用参数代替开度信号，但应使用独立模型类型并说明差异。
|
||||
|
||||
### 7.2 供需声明与当前实现边界
|
||||
|
||||
`PORTS` 是权威来源。当前 `PortComputation` 的 `inputs/outputs` 支持 `p`、`T`、`m_flow`、`H_flow` 四个气动量；`reference_port` 只表达 p/T 从另一个端口输入复制的关系。前端目录与 JSON/XML 校验从注册表恢复这些声明，工程快照不能覆盖它们。
|
||||
|
||||
`H_flow` 表示能量流率（W），只用于当前接口供需检查，不能当作已经存在的 C 运行时端口字段；运行时仍使用 `h_outflow` 和质量流率。两种表达的单位、符号及零流量处理必须在 C 方程中正确转换。
|
||||
|
||||
- `mode="fixed"` 表示该子模型的接口供需是固定要求；它不表示输出数值为常量，也不是固定积分步长。
|
||||
- `mode="equation"` 表示允许连接方程联合确定变量。必须有相应 C 求解能力支持，不得为了绕过错误接线而随意改为此模式。
|
||||
- 新移植部件如有明确的固定输入输出，应按原始接口声明并验证。现有非节点部件采用 `equation` 是本阶段保留已有联合求解能力的策略，不能把它当作所有 Amesim 子模型的原始接口定义。
|
||||
- 新模型需要声明容积、机械量、任意输出依赖或可选输入默认值时，应先同步扩展供需数据结构、注册器、目录 schema、前后端检查与测试。当前四变量接口尚不能完整承载这些信息，不得只在注释或 JSON 中添加编译器不读取的字段。
|
||||
|
||||
### 7.3 从 Amesim 移植时的对照要求
|
||||
|
||||
以明确的 Amesim 版本和**子模型编号**为依据读取端口变量表及其实现；图标相同或端口数量相同不足以证明模型等价。每个原始变量都应有映射记录：保留、换名、单位/符号变换、由其他量导出、仅保留默认值，或明确不支持。
|
||||
|
||||
既要记录普通输入/输出，也要记录状态、固定输出、别名、取反别名、可选输入及默认值。例如 PNCH012 的容积输入和 MECMAS21 的加速度端口量，不能因为当前四变量气动模板没有对应字段就不作说明。
|
||||
|
||||
接口方向对齐、局部公式对齐和完整仿真曲线对齐是三项不同的验证；不能用其中一项替代其他两项。实验组件及自行简化的变体，不应宣称与 Amesim 原子模型一比一相同。
|
||||
|
||||
### 7.4 为计算排序准备元件步骤
|
||||
|
||||
元件说明和 C 接入应区分：状态/物性输出、连接量与局部代数计算、状态导数、展示输出。例如储气元件先由当前状态提供温度和压力，得到流量后再算导数，不能把整个元件当作一个不可拆分的步骤。
|
||||
|
||||
端口供需合同不承载任意计算步骤的依赖图。当前扩展 C 生成器使用 `Computation` 记录内置气动方程的输入、输出与 C 语句，再自动排序及划分局部循环。新模型须显式接入这些计算关系；只注册 `PORTS/PARAMETERS` 不会自动生成数值方程。参考值复制与能量汇总应拆开，多输出 C 调用必须正确列出读取参数与写出结果，见 [C 求值排序规范](native-evaluation-schedule.md)。
|
||||
|
||||
新增或修改接口至少验证：合法连接、输入无人提供、冲突连接、参考链及参考环、反向/零流量、可选输入默认值、单位/符号映射，以及独立解析或外部基准下的 C 结果。没有对应机制的能力必须标记为尚未支持。
|
||||
|
||||
## 8. 参数建模规范
|
||||
|
||||
所有用户可配置输入必须使用 `ParameterDefinition`：
|
||||
|
||||
@@ -0,0 +1,54 @@
|
||||
# C 求值的依赖排序与局部求解
|
||||
|
||||
本文说明当前内置模型的扩展 C 生成路径。Python 仅在编译时整理计算关系，运行时仍由独立 C 程序完成物性、连接量、局部迭代和积分。没有恢复旧 Python 数值内核或旧 IR 包。
|
||||
|
||||
## 执行过程
|
||||
|
||||
1. 从当前状态、参数和时间信号准备机械位置/速度、容积及储气物性。压力和焓的储气来源在此确定；可变容积仍使用当前机械状态，不把加速度或下一时刻状态当作已知量。
|
||||
2. 将气动连接计算记录为独立条目，每条列明输入、输出和 C 语句。参考口的别名传递与节点能量汇总分开，管路/阀门流量与储气状态导数分开。
|
||||
3. 根据生产者与使用者关系自动排序。没有循环的关系执行一次；互相依赖的关系组成局部块，先完成该块，再计算使用其结果的关系。
|
||||
4. 计算机械力平衡、状态变化率和结果输出，再由原有 RK45/BDF 推进时间。
|
||||
|
||||
这里的“一次”指一次 `model_eval` 系统状态求值。积分器为误差控制、数值差分或步长重试而进行的多次求值仍然必要，不能把它们当作重复调用删掉。
|
||||
|
||||
紧凑的储气锚定生成路径已经直接按依赖执行，继续保留。扩展路径使用同一套图算法处理不同内置组件组合，不依据模型名称、实例名称、画布位置或固定流向写特例。
|
||||
|
||||
## 编译结构
|
||||
|
||||
`app/simulation/native_codegen/schedule.py` 提供：
|
||||
|
||||
- `Computation`：稳定标识、输出、输入、C 语句、计算类别，以及压力平衡残差（适用时）。
|
||||
- `EvaluationSchedule`：检查来源与重复提供者，划分相互依赖的块，并按依赖排序。
|
||||
- `emit()`：生成直接计算语句和局部 C 求解函数。
|
||||
- `report()`：输出来源、输入输出关系及循环块清单，保存到构建清单的 `evaluationSchedule`。
|
||||
|
||||
连接流量的常系数线性消元仍在编译阶段完成；消元得到的中间表达式也参加排序，不把整组连接方程作为不可拆分的大步骤。图遍历不用 Python 递归，长参考链不会受递归深度限制。
|
||||
|
||||
`knownSources` 记录进入该阶段前已准备好的来源；`blocks` 给出执行顺序、输入、输出、来源和未知压力；`operations` 给出逐条关系。循环初值不算作已知来源。缺少输入来源、重复输出提供者、没有热力来源的纯别名环在编译时拒绝。
|
||||
|
||||
## 局部循环规则
|
||||
|
||||
- 未知压力仅使用该块已有的压力边界确定试算范围。单个压力试算只刷新其质量平衡所需的流量关系；不调用全网流量函数。
|
||||
- 一个块内存在多个相互影响的压力时，保留现有逐压力二分与扫掠方法，最多 256 轮扫掠，每次二分 48 轮，质量平衡阈值仍为 1e-11 kg/s。
|
||||
- 焓传播确有循环时，从该块外已经提供的焓值初始化该块；只检查本块输出变化。相对变化阈值仍为 1e-12，轮数上限为 `max(64, 4×本块待更新焓值数量)`。
|
||||
- 压力与焓同时互相依赖时，在这个局部块内保留嵌套求解。迭代到上限仍未满足条件，或出现非有限数值，返回求值失败；不把未完成的局部闭合当作成功。
|
||||
- 条件表达式记录所有可能分支的依赖，覆盖反向与零流量。此做法较为保守：某个特定工况下能进一步简化的关系仍可能留在小循环内。本版没有实现运行时分支特化。
|
||||
|
||||
管路自身的摩擦/流量求根属于元件内部计算。本轮没有改其算法或 16/64/48 轮上限，也没有改积分器或雅可比策略。系统循环的来源检查和局部划分不代表任意新非线性方程都已得到数值求解支持。
|
||||
|
||||
## 新模型如何接入
|
||||
|
||||
除了模型的物理接口表，还要在 C 生成实现中拆出能独立执行的关系：
|
||||
|
||||
```python
|
||||
operations.append(Computation.assignment(
|
||||
f'alias:{component.name}.port_1', target_h, reference_h, 'alias'))
|
||||
```
|
||||
|
||||
单个赋值的输入从编译器生成的受控表达式中提取。提取器只识别本生成器的 `p/h/q/w/fb` 数组与气体物性字段，不解析用户输入的 C 代码。调用写出多个结果的 C 函数时，必须显式列出实际读取的参数和写出的结果；把输出指针误当作输入，会制造虚假循环。
|
||||
|
||||
没有依赖流量的参考值复制必须单独列出，不能与需要流量的能量计算合并为一个条目。共享状态、机械/信号准备和气体物性阶段仍需要在现有 C 接入中实现；仅注册 `PORTS/PARAMETERS` 不会自动产生方程。
|
||||
|
||||
新增能力至少检查：来源缺失、多个提供者、长参考链、组件与连接顺序打乱、正反流和零压差、两个独立循环互不重算、耦合压力/混合循环的质量能量守恒，以及独立数值基准。当前自动排序对象是已接入的内置方程，不接受任意外部 C 代码。
|
||||
|
||||
对应测试：`tests/test_native_schedule.py`、`tests/test_native_catalog.py`。本轮模型对照记录见 [计算排序验证记录](../other/C计算依赖排序验证-2026-09-10.md)。
|
||||
@@ -0,0 +1,89 @@
|
||||
# 气动端口变量供需合同
|
||||
|
||||
本合同在 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 也不接受工程自定义供需规则。
|
||||
|
||||
- 画布：供需不匹配的目标口不会作为可连接目标；接触吸附使用同一规则。悬停显示需要/提供的量和不兼容原因。
|
||||
- 旧工程：保留供需不匹配的现有连线供检查、修改，不自动交换参考口或删线。原有的无效端口、重复占用等结构损坏处理不变。
|
||||
- 检查模型及运行仿真：报告具体部件、端口和缺少的量，错误未处理前不启动求解。
|
||||
- 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 组件目录读取供需信息，覆盖目标筛选、悬停原因、错误旧连线保留和仿真前拦截，防止前后端合同不一致。
|
||||
@@ -192,6 +192,7 @@ XML 不能通过写一个新端口名来扩展组件，也不能通过修改字
|
||||
- 两端同为物理端口或同为信号端口；
|
||||
- 两端 `domain` 和完整变量合同一致；
|
||||
- 信号连接恰好连接一个 `output` 和一个 `input`；
|
||||
- 固定气动接口的变量供需互补，节点参考温度/压力来源没有闭合引用环；详见 [气动端口变量供需合同](port-computation-contract.md)；
|
||||
- 一个信号输出可以驱动多个输入，但每个信号输入只能有一个驱动；
|
||||
- 同一物理端口只使用一次；分支必须使用显式 Tee/节点组件；
|
||||
- 不允许自连接或重复端点对。
|
||||
|
||||
Reference in new issue
Block a user