旧版前端工程文件导入时版本对比查验、审阅与仿真时部分阻挡功能实现；前端参数输入格式统一规范
This commit is contained in:
lujingze committed
1 parent
22579e51c9
commit
44b6ea74ab
32 files changed
+2087
-322
No files matched your search
@@ -1,5 +1,7 @@
|
||||
# System XML v3 协议
|
||||
|
||||
文档版本：1.1.0；核对日期：2026-09-12；代码基线：`22579e5`。此版本标注文档修订，不改变 XML Schema 3。
|
||||
|
||||
System XML v3 是 SystemSimulationApp 当前唯一的 XML 求解输入格式。它只描述可执行模型，不再承担 ReactFlow 画布存档职责。
|
||||
|
||||
机器可读结构见 [`schemas/system-simulation-v3.xsd`](../../schemas/system-simulation-v3.xsd)。当前校验、解析、编译和仿真接口固定按 v3 处理，不会根据 `schemaVersion` 自动切换到 v1 或 v2。
|
||||
@@ -28,7 +30,7 @@ XML 不保存：
|
||||
|
||||
## 2. 完整结构示例
|
||||
|
||||
下面的例子包含一条信号连接和一条机械连接，展示 v3 的全部结构元素：
|
||||
下面的例子包含一条信号连接和一条机械连接，展示 v3 的全部结构元素。它通过 XML 语义校验，但不是可求解算例：机械组没有惯性锚点，原生生成会报 `mechanical group has no inertia anchor`。实际仿真应增加符合方程的质量/惯性连接；不要用结构校验通过代替原生能力验收。
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
@@ -103,7 +105,9 @@ System
|
||||
| `tStop` | 仿真结束时刻 | 必须有限且大于 `tStart` |
|
||||
| `sampleStep` | 结果相邻采样点的时间间隔 | 必须大于 0；不设置固定的采样点数上限 |
|
||||
| `maxStep` | 自适应积分器单个内部步的上限 | 必须大于 0 |
|
||||
| `method` | 积分方法 | `RK45/RK23/DOP853/Radau/BDF/LSODA` |
|
||||
| `method` | 积分方法 | 当前语义校验及 C 执行仅接受 `RK45`、`BDF` |
|
||||
|
||||
XSD 的枚举仍包含 `RK23/DOP853/Radau/LSODA`，但它们会被 `app/system_xml.py::SUPPORTED_SOLVER_METHODS` 在语义层以 `SIMULATION_METHOD_UNSUPPORTED` 拒绝。不能将 XSD 的结构允许集合当成运行能力。XML 当前没有 `rtol/atol/firstStep` 属性；网页和 XML API 由 `backends.simulation_config()` 设置 `rtol=1e-8`，绝对误差采用生成的逐状态尺度，见[求值与精度规范](native-evaluation-schedule.md)。
|
||||
|
||||
`sampleStep` 和 `maxStep` 不是一回事：
|
||||
|
||||
@@ -138,7 +142,7 @@ v3 不保存 `name/componentType/x/y/rotation/mirrored`。其中：
|
||||
|
||||
### 5.2 `Parameter`
|
||||
|
||||
平台压力统一采用绝压，默认显示单位为 `Pa`，可切换为 `kPa`、`MPa` 或 `bar`。这些显示单位只作比例换算，不增加或减去大气压偏移，`1 bar = 100000 Pa`。工程 JSON 中的数值参数保存 SI 值，`parameterUnits` 保存显示单位；表达式按保存的显示单位求值后换算到 SI。例如输入 `2.5 bar` 时，XML 的压力参数值为 `250000`。后端仿真输入与压力结果均使用绝压 Pa。
|
||||
平台压力统一采用绝压，默认显示单位为 `Pa`，可切换为 `kPa`、`MPa` 或 `bar`。这些显示单位只作比例换算，不增加或减去大气压偏移，`1 bar = 100000 Pa`。工程 JSON v2 中数值和表达式均按 `parameterUnits` 解释，统一换算为 SI；v1 兼容保留旧数值的 SI 含义。例如输入 `2.5 bar` 时，XML 的压力参数值为 `250000`。后端仿真输入与压力结果均使用绝压 Pa。
|
||||
|
||||
```xml
|
||||
<Parameter name="direction" value="-1"/>
|
||||
@@ -153,6 +157,8 @@ v3 不保存 `name/componentType/x/y/rotation/mirrored`。其中：
|
||||
|
||||
前端和后端导出器会先用注册默认值补齐工程 JSON 中省略的参数，再写入 XML。XML 解析器本身不替缺失参数猜默认值。
|
||||
|
||||
网页、HTTP 和 CLI 的 JSON 输入均在适配层计算受限数学表达式并按格式版本换算到 SI。v2 的 `p0: 2.5`、`p0: "2.5"`、`p0: "=2.5"` 配合 `bar` 均为 250000 Pa；v1 数字仍为旧 SI 存档含义，不可直接更改格式版本。组件旧版本在 JSON 输入层警告后采用当前模型生成 XML，XML 本身继续严格检查版本及有限 SI 数字。完整规则见[接口规范](backend-interface-version-spec-v1.md#61-工程存储与执行入口)。
|
||||
|
||||
### 5.3 AMESim 介质引用
|
||||
|
||||
介质仍用普通参数表达，不增加额外 XML 层级：
|
||||
@@ -195,7 +201,7 @@ XML 不能通过写一个新端口名来扩展组件，也不能通过修改字
|
||||
- 两端 `domain` 和完整变量合同一致；
|
||||
- 信号连接恰好连接一个 `output` 和一个 `input`；
|
||||
- 固定气动接口的变量供需互补，节点参考温度/压力来源没有闭合引用环；详见 [气动端口变量供需合同](port-computation-contract.md)；
|
||||
- 一个信号输出可以驱动多个输入，但每个信号输入只能有一个驱动；
|
||||
- XML 与后端网络允许一个信号输出驱动多个输入，但每个输入只能有一个驱动；当前网页模型检查仍要求每个显示端口恰好一条边，不能据此承诺网页也已支持扇出；
|
||||
- 同一物理端口只使用一次；分支必须使用显式 Tee/节点组件；
|
||||
- 不允许自连接或重复端点对。
|
||||
|
||||
@@ -229,7 +235,7 @@ XML 不能通过写一个新端口名来扩展组件，也不能通过修改字
|
||||
| `useFriction` | 不启用摩擦 | 启用摩擦 |
|
||||
| `strib` | 不使用 Stribeck 效应 | 使用 Stribeck 效应 |
|
||||
|
||||
工程 JSON v1 和 System XML v3 都直接保存上述值。后端不会把 `0/1` 自动换算成
|
||||
工程 JSON v1/v2 和 System XML v3 都直接保存上述值。后端不会把 `0/1` 自动换算成
|
||||
`1/2`，也不会根据缺失的兼容标记猜测工程含义；不在目录选项集合内的值会被拒绝。
|
||||
|
||||
## 8. 工程 JSON 与 System XML 的分工
|
||||
@@ -238,9 +244,9 @@ XML 不能通过写一个新端口名来扩展组件，也不能通过修改字
|
||||
| --- | --- | --- |
|
||||
| 组件实例 ID、模型类型 | 保存 | 保存 |
|
||||
| 模型版本 | 每个节点显式保存并与目录核对 | 每个组件显式保存 |
|
||||
| 数值参数 | 保存编辑值及显示信息 | 保存完整 SI 数值 |
|
||||
| 数值参数 | v2 数值和表达式均按所选单位；v1 数字兼容 SI | 保存完整 SI 数值 |
|
||||
| 组件显示名、坐标、旋转、镜像 | 保存 | 不保存 |
|
||||
| 端口快照、`side/order` | 保存供编辑器使用 | 不保存 |
|
||||
| 端口快照与 `side` | 保存供编辑器使用；目录 `order` 不保证原样留在快照中 | 不保存 |
|
||||
| ReactFlow `source/target/handle` | 保存 | 转成两个 `Endpoint` |
|
||||
| 端口物理合同 | 目录快照用于前端检查 | 不重复保存，由注册表恢复 |
|
||||
| 参数表达式、显示单位 | 保存 | 不保存 |
|
||||
@@ -268,7 +274,9 @@ XML 不能通过写一个新端口名来扩展组件，也不能通过修改字
|
||||
|
||||
`POST /api/reactflow/system-xml` 可将工程 JSON 导出为 v3；当前前端也能在浏览器中直接生成同一结构。
|
||||
|
||||
通过 XML/XSD/语义校验只说明输入合同正确。完整仿真前仍会检查动态储能锚点、未连接物理端口、方程结构和不允许的理想储能直连等可求解条件。物理连通岛只由物理组件和物理连接构成；控制信号扇出不会把两个独立气路或机械网络合并成一个物理岛。
|
||||
通过 XML/XSD/语义校验只说明输入合同正确。`compile-model` 构造的是 Python 网络和接口信息，不编译 C 可执行文件；仿真时还要通过具体原生生成路径的状态/惯性来源、必接端口、方程及输出映射检查。紧凑路径不支持的部分拓扑会转入扩展路径，不应把紧凑路径的储气直连限制写成全系统统一禁令。信号源可使用无物理状态的内部占位状态，不是所有模型都必须有动态储能组件。
|
||||
|
||||
前端检查、XML 语义检查和原生能力检查相互独立。XML 对一般未连接活动端口报告警告；缺少固定参考来源等情况仍可报错。原生生成按模型的必接要求检查，例如 PNVO 信号口有 `opening0` 的专用缺省处理；网页仍会拦截未连接显示端口。
|
||||
|
||||
## 10. 旧版本处理边界
|
||||
|
||||
|
||||
Reference in new issue
Block a user