73 lines
3.3 KiB
Markdown
73 lines
3.3 KiB
Markdown
# System XML v1 协议
|
||
|
||
> 此版本仅用于识别旧文件。新项目使用 [System XML v2](system-xml-v2.md)，物理连接在 v2 中改为无序端点。
|
||
|
||
System XML 是 ReactFlow 前端与 PythonModels 仿真层之间的稳定交换格式。
|
||
|
||
## 基本约定
|
||
|
||
- 根元素固定为 `System`，`schemaVersion` 固定为 `1`。
|
||
- `unitSystem` 固定为 `SI`。组件参数必须保存为 SI 基准值，界面显示单位不进入数值换算语义。
|
||
- 子元素顺序固定为 `Simulation`、`Components`、`Connections`。
|
||
- `Component.id` 是稳定的仿真实例 ID；`name` 是用户可编辑的显示名称。
|
||
- `Component.type` 是 PythonModels 模型类型；`componentType` 是前端组件类型。
|
||
- `Connection.source/target` 只标识图形拓扑端点，不代表仿真中的实际流动方向。正流和倒流由求解器决定。
|
||
- v1 文档不携带结果数据；仿真结果通过运行接口返回。
|
||
|
||
## 完整示例
|
||
|
||
```xml
|
||
<?xml version="1.0" encoding="UTF-8"?>
|
||
<System name="transfer-system" schemaVersion="1" unitSystem="SI">
|
||
<Simulation tStart="0" tStop="2" step="0.1" maxStep="0.005" method="BDF"/>
|
||
<Components>
|
||
<Component id="cylinder_1" name="cylinder_1" type="cylinder" componentType="cylinder" x="90" y="180">
|
||
<Port name="port_b"/>
|
||
<Parameter name="volume" value="0.01"/>
|
||
<Parameter name="p0" value="35000000"/>
|
||
<Parameter name="T0" value="300"/>
|
||
</Component>
|
||
<Component id="tank_1" name="tank_1" type="tank" componentType="tank" x="420" y="180">
|
||
<Port name="port_a"/>
|
||
<Parameter name="volume" value="0.1"/>
|
||
<Parameter name="p0" value="100000"/>
|
||
<Parameter name="T0" value="300"/>
|
||
</Component>
|
||
</Components>
|
||
<Connections>
|
||
<Connection id="edge-1" source="cylinder_1" sourcePort="port_b" target="tank_1" targetPort="port_a"/>
|
||
</Connections>
|
||
</System>
|
||
```
|
||
|
||
## Simulation
|
||
|
||
| 属性 | 类型 | 含义 | 约束 |
|
||
|---|---|---|---|
|
||
| `tStart` | double | 仿真起始时间，单位 s | 有限数 |
|
||
| `tStop` | double | 仿真结束时间，单位 s | 必须大于 `tStart` |
|
||
| `step` | double | 结果采样间隔，单位 s | 必须大于 0 |
|
||
| `maxStep` | double | 求解器最大积分步长，单位 s | 必须大于 0 |
|
||
| `method` | string | 求解器名称，例如 `BDF` | 非空 |
|
||
|
||
## Components
|
||
|
||
每个 `Component` 必须包含唯一 `id`、显示名称、模型类型、前端类型和画布坐标。组件下可以包含多个 `Port` 和 `Parameter`。
|
||
|
||
参数的 `value` 必须是可转换为有限浮点数的 SI 值。具体组件支持的端口、参数和取值范围由后续组件注册表协议约束。
|
||
|
||
## Connections
|
||
|
||
每个 `Connection` 必须包含唯一 `id` 和两个完整端点：
|
||
|
||
- `source` + `sourcePort`
|
||
- `target` + `targetPort`
|
||
|
||
端点中的组件 ID 必须存在，端口名称必须属于对应组件。v1 前端仍使用 source/target 组织连线，但仿真层必须将它们视为连接的两个端点，不得直接解释为固定物理流向。
|
||
|
||
## 版本兼容
|
||
|
||
- 解析器遇到缺少 `schemaVersion` 的旧 XML 时，应明确报告“旧协议”，不能静默当作 v1。
|
||
- v1 新增可选字段时必须保持旧解析器可忽略；删除字段或改变字段语义时必须升级主版本。
|
||
- XSD 只验证文档结构和基础数据类型。跨字段约束、组件端口规则和拓扑可求解性由仿真校验层负责。
|