# SystemSimulationApp 后端求解逻辑与效率优化调研（通俗版）

> 调研基线：2026-08-15（System XML v3 迁移后）；2026-08-16 已补充压力边界、预编译闭合执行计划、方程关联图分块、代数稀疏回退、ODE Jacobian 修正和实测复验的当前状态。
> 本文所称“主求解路径”是当前前端实际调用的 System XML 流式接口；固定 TestModel 和 Test MQL 接口另行说明。机器相关的实测结果单独见[仿真性能评估 2026-08-15](仿真性能评估-2026-08-15.md)。

## 0. 三分钟读懂

### 0.1 求解器到底在做什么

先不管 ODE、RHS、BDF 这些名字。把一次仿真想成制作一段工程动画：

1. **检查装配图。** 气管有没有漏接，控制线方向对不对，模型参数是否齐全。
2. **读取当前“存量”。** 例如气室里有多少气体和能量，质量块现在的位置和速度。
3. **让当前瞬间自洽。** 根据这些存量，把此刻的压力、流量和力反复对账，直到连接规则和组件方程同时满足。
4. **计算变化速度。** 得出“下一小段时间内，质量、能量、位置、速度将怎样变化”。
5. **内部小步前进。** 求解器自己决定每次走多小；变化剧烈时会缩短步长。
6. **按用户指定时刻留快照。** 内部可能算很多小步，但结果文件只在 XML v3 的 `sampleStep` 指定的时刻保存数值。
7. **把进度和结果交给前端。** 运行中发心跳/进度，结束时一次性发送完整曲线数据。

项目里的技术说法“**半显式 ODE + 每次变化率计算前做代数闭合**”，翻译成人话就是：**会积累的量用时间积分向前推；必须在当前瞬间成立的关系，每次都先对账求平衡。**

### 0.2 用仓库里的真实案例贯穿全文

`tests/test_generic_system_xml_simulation.py:86-145` 有一条完整回归气路：

```text
高压气缸                         低压储气罐
0.01 m³、500 kPa                0.1 m³、100 kPa
      ──> 节流孔 ──> 1 m 管路 ──>
```

图中箭头只表示这个初始压差下**预计**的气流方向，不代表物理连线本身有 `source/target` 方向。回归测试检查了：

- 气缸压力下降；
- 储气罐压力上升；
- 总质量和总能量守恒；
- 把工程 JSON 中物理边的 `source/target` 对调，结果不变。

测试只运行 `0～0.01 s`，设置结果采样 `sample_step=0.005 s`、内部上限 `max_step=0.001 s`、`method=BDF`（`tests/test_generic_system_xml_simulation.py:86-145, 254-300, 354-372`）。在 System XML v3 中，前两个字段分别写成 `sampleStep` 和 `maxStep`。它们可以这样理解：

```text
结果快照：  0 s -------- 0.005 s -------- 0.01 s
内部计算：  0 s - 小步 - 小步 - 小步 - ... - 0.01 s
                         每个内部步最多 0.001 s，也可能更短或被重算
```

- `sampleStep`：相机隔多久保存一张结果快照；
- `max_step`：求解器一次内部前进最多能走多远；
- `BDF`：一种适合系统中“有的变化快、有的变化慢”的自适应算法。本文不需要展开它的公式。

另一个真实案例位于 `tests/test_amesim_pnvo001_signal_xml.py:87-204, 230-246`：高、低压氦气室之间有一个阀，阶跃信号在 `0.04 s` 从 0 跳到 1。求解器会像遇到“定时闹钟”一样，准确停到事件时刻，更新阀命令，再从该时刻继续积分。

### 0.3 常见术语翻译

| 技术词 | 先这样理解 | 本项目里的具体含义 |
| --- | --- | --- |
| 动态状态（state） | 会随时间积累的存量 | 气体质量/内能 `[m,U]`，或机械速度/位置 `[v,x]` |
| 代数量 | 当前瞬间的仪表读数 | 压力、流量、连接力等；由当前状态和约束求出 |
| 代数闭合（closure） | 把所有账对平 | 让组件方程、连接守恒和当前状态同时成立 |
| 变化率计算（RHS） | 算下一刻变化有多快 | 输入当前状态，输出 `dm/dt`、`dU/dt`、加速度等 |
| ODE 积分 | 根据变化率向时间前进 | SciPy 的 BDF、Radau、RK45 等 |
| DAE | 状态和瞬时约束一起交给专用求解器 | 当前主内核不是通用 DAE 求解器 |
| stream 焓 | 气体随流动携带的“能量标签” | `h_outflow` 按实际流向传播/混合，不是两端温度相等 |
| 非线性迭代（`least_squares`） | 直接算不出时反复试值 | 压力流量快速路径失败后的回退方案 |
| Jacobian | “改一个量会影响哪些方程”的灵敏度地图 | 可帮助 BDF/Radau 和非线性求解少做试算 |
| dense output | 两个内部步之间的插值尺 | 用来补采样点和定位机械事件 |
| NDJSON | 一行一个 JSON 消息 | 同一 HTTP 响应中依次发送心跳、进度、结果 |
| worker | 后台办事通道 | 当前脚本是一个 Uvicorn worker；流式任务另开求解线程 |

只想了解系统如何运行，可以读第 0、3、5、6、9、10、13 节；需要改求解器时，再阅读其余技术细节和第 15 节代码索引。

## 1. 结论先行

1. **[已实现] 当前主内核是“半显式 ODE + RHS 内代数闭合”。** 动态组件只把储能状态交给 ODE 积分器；每次计算导数前，系统先传播信号、刷新热力状态、求压力/流量代数网络、传播变容边界、迭代 stream 焓并更新机械加速度。它不是通用 DAE 求解器，也不等价于完整 Modelica `inStream/actualStream` 语义（`README.md:18-20`、`app/simulation/README.md:174-195`）。
2. **[已实现] 当前前端主链路是 System XML 流式仿真。** 浏览器生成 XML，经 `POST /api/system-xml/simulate-stream` 发送；后端以 NDJSON 返回心跳与进度，最后在一个 JSON 行中返回完整结果。不是 WebSocket 或标准 SSE。
3. **[已实现] XML v3 的 `sampleStep` 是输出采样间隔，不是固定积分步长。** 内部的 `max_step`（XML 为 `maxStep`）才是自适应积分步长上限；`BDF/Radau/LSODA/RK45/RK23/DOP853` 均受支持。流式运行因总是提供取消检查，会使用 SciPy 低层求解器逐个已接受步推进。
4. **[已优化] 每次完整闭合仍先做 1 次语义上的全网压力流量求解，再传播 stream；后续固定点只重算 stream-sensitive 方程实际关联的方程块。** 物理连通岛现在只是安全分类的第一层，真正执行的 `secondaryBlockCount` 是方程—未知量关联图中的块数；无法可信分类的自定义或异常结构仍保守回退原全网路径。积分结束后，每个输出采样点仍执行一次完整闭合并提取结果。
5. **[已实现] 代数求解已有因果化快路径、方程块和稀疏 `least_squares` 回退。** 对可信内置声明，求解器从方程—未知量关联图编译 `jac_sparsity`，先把本轮未闭合的独立方程块合并成一个 union sparse 问题；若失败，恢复到同一个原始 `x0`，再执行全局 sparse，仍失败才执行兼容的 dense 路径。活动接触或不可信自定义声明不会冒险稀疏化，保留 dense 兼容路径。当前没有解析 Jacobian，但不再是“完全未提供 `jac_sparsity`”。
6. **[已实现] 当前启动脚本是一个 Uvicorn worker。** 每个流式任务再创建一个无并发上限的 daemon 线程和无界队列；没有进程池、集中任务队列、CPU/内存配额或持久化作业系统。同步仿真端点还会在 `async def` 中直接执行 CPU 密集代码。
7. **[推断] 优化应分两条线：**
   - 单算例速度：减少闭合 pass、代数未知量与残差装配，缓存热物性，改善外层积分尺度/Jacobian，减少后处理重算；
   - 服务吞吐与资源稳定性：有界进程 worker、结果分块/按需返回、任务表主动清理和前端结果存储降副本。
8. **[已修复] 高刚度 XML 不再因合法亚帕试探压力失败。** 压力优化下界由 1 Pa 放宽到 0 Pa，允许严格正的亚帕试探值，同时构成方程仍拒绝零压和负压；同一 10 s RK45 算例已完成且没有可恢复重试。
9. **[历史实测] 闭合裁剪的收益随拓扑明显变化。** 已被方程块版取代的物理岛版短算例 `off` 配对改善为 0.6%～21.4%；其 high-stiffness 10 s optimized/forced-global 对照为 14.676 s/16.929 s，完整 `series` 一致。数据保留作纵向基线，不能当作当前方程块版结果，也不能把其他拓扑的收益外推给单一氦气敏感岛。
10. **[实测] 98 组件的大型分支 XML 在 `0.69 s` 附近的长时间停留不是死锁。** 根因是气动外部 volume 跨域耦合在 ODE 有限差分 Jacobian 依赖图中漏了 12 个实测显著项，BDF 因此反复做小步和 Jacobian/LU 工作；修正后结构非零数由 1092 增至 1284、颜色组由 27 增至 31。最终稳定代码连续三次完整 `0～0.81 s` 用时 79.049 s、74.658 s 和 85.103 s，积分统计均为 `nfev/njev/nlu=3393/226/667`、接受步 1009；stream 后续闭合为 9 个方程块、合计 192 个未知量。

## 2. 证据标签与范围

- **[已实现]**：当前可执行代码或测试直接体现。
- **[约定]**：配置、Schema、类型或仓库说明规定，但不一定被每条入口完整执行。
- **[推断]**：从调用结构推导的资源或性能判断，尚无仓库内基准数据。
- **[发现]**：实现间的不一致、诊断缺口或潜在效率风险。

本次覆盖四条后端执行路径：

| 路径 | 是否为当前 UI 主路径 | 数值行为 |
| --- | --- | --- |
| `POST /api/system-xml/simulate-stream` | 是 | XML 校验、拓扑编译、通用系统积分；NDJSON 进度与最终结果 |
| `POST /api/system-xml/simulate` | 否 | 同一通用求解函数；同步返回、无任务登记/流式进度 |
| `POST /api/reactflow/simulate-testmodel` | 否 | 固定 TestModel 专用闭包与产物生成，不按任意 ReactFlow 边拓扑求解 |
| `POST /api/reactflow/simulate-test-mql` | 否 | 当前只返回结构/采样摘要和全零状态数组，不执行 132 状态时域积分 |

## 3. 主求解调用链

```mermaid
flowchart TD
    A["前端校验参数并生成 System XML"] --> B["POST simulate-stream"]
    B --> C["安全解析 + XSD v3 + 语义校验"]
    C --> D["XML 执行模型直接编译 SimulationNetwork"]
    D --> E["准备检查与求解器构造"]
    E --> F["一致初始代数闭合"]
    F --> G["自适应 ODE 逐步积分"]
    G --> H["每个 RHS：信号/热力/代数/stream/机械闭合"]
    G --> I["事件定位、状态重置、求解器重启"]
    G --> J["逐采样点完整后处理闭合"]
    J --> K["完整结果作为末条 NDJSON 返回"]
```

### 3.1 前端形成输入

**[已实现]** 前端先检查模型、表达式和仿真设置，再由 `buildSystemXml()` 在浏览器内构造精简 v3 XML。参数表达式会先求值，并按选定显示单位转成 SI 基准数值；求解期间这些组件参数保持静态，不存在前端实时调参或联合仿真输入通道（`frontend/src/App.tsx` 中的参数解析与 `buildSystemXml()`；`app/simulation/core/base.py:65-95`）。

前端生成 `simulationId`，通过 `fetch` 发送 XML，请求头携带该 ID；响应类型要求为 `application/x-ndjson`（`frontend/src/App.tsx` 中的运行入口与 `streamSystemSimulation()`）。

### 3.2 XML 校验、解析和网络编译

主序列见 `app/main.py` 的 `run_system_xml_simulation()`：

1. `validate_system_xml_document()` 执行大小/安全解析、v3 XSD 和语义校验；
2. XML 解析为只含求解信息的规范化执行模型，不重建 ReactFlow 画布；
3. `compile_system_xml_network()` 创建 `SimulationNetwork`；
4. 构造 `GenericFluidSystem` 与 `SolveIVPConfig`；
5. 调用通用 `simulate()`；
6. 汇总验证、模型接口、数值结果和错误诊断。

XML 安全层限制 5 MiB、禁用 DTD/实体和网络访问（`app/system_xml.py` 的安全解析与 `validate_system_xml_document()`）。

XML 编译最终进入 `_compile_solver_network()` 的两阶段装配（`app/main.py`）：

- v3 语义层先核对组件 `modelVersion`、完整参数和端点引用；编译层再消费零端口介质定义节点；
- 按气动连通区域解析介质引用；
- 实例化实际组件，并根据注册模型恢复端口类型、角色和变量合同；
- 最后建立网络连接。

**[已实现]** v3 不携带坐标、旋转、镜像或端口显示侧，布局不会进入求解。`AmesimForc` 的物理正反由模型参数 `direction=+1/-1` 决定；旋转/镜像图标不会改变力方程（`app/simulation/components/amesim/mechanical/translational.py`）。

### 3.3 求解前结构检查

创建通用系统前，`generic_simulation_preparation_issues()` 检查（`app/simulation/systems/generic.py:93-201`）：

- 所有物理端口已经连接；
- 压力流量系统的未知量数与方程数相等；
- 网络至少存在一个动态储能组件；
- 每个相连物理岛具有动态储能锚点；
- 不允许多个理想储能元件无阻力直接耦合。

这些检查是当前可求解结构的边界，不表示任意声明了 `PortDefinition` 的网络都能被通用求解器处理。

## 4. 数学结构与状态组织

本节的核心区别只有一个：**有些量要“记住过去并随时间积累”，有些量只要在当前瞬间满足约束。**

在高压气缸向低压储罐放气的案例里，气室内的气体质量和能量属于前者；端口压力和通过节流孔的瞬时流量属于后者。求解器先保存前者，再用它们求出后者。下面的“动态状态”“代数未知量”只是这两组量的技术名称。

### 4.1 动态状态

**[已实现]** 动态组件把自身状态拼成全局 ODE 向量：

- 固定/变容气室及部分动态管路通常使用质量与内能 `[m, U]`；导数由质量流、焓流和换热构成。PNCH023 示例见 `app/simulation/components/amesim/storage/chambers.py:111-218`。
- PNL0003 具有两个容积单元，使用四维 `[m1, U1, m2, U2]`（`app/simulation/components/amesim/flow/pipes.py:1043-1078`）。
- MECMAS21 的机械状态是 `[v, x]`，导数是 `[a, v]`（`app/simulation/components/amesim/mechanical/translational.py:569-700`）。

`MechanicalStateReducer` 会按机械连接中的 `x/v` 等值关系将刚性相连的质量归组，每组只保留一套 `[v, x]` 状态，从而避免重复积分同一个运动自由度（`app/simulation/solvers/mechanical.py:225-427`）。

### 4.2 代数未知量与方程

网络从物理端口合同和组件残差构造代数系统（`app/simulation/systems/network.py:159-237`）：

- 气动端口的主要代数变量是 `p` 和 `m_flow`；
- 机械端口包含 `x`、`v`、`f`，其中已归属动态状态的坐标会被状态/等值关系约束；
- 连接对 `effort/equal` 生成两端差值，对 `flow/sumToZero` 生成两端和值；
- 组件再提供状态约束、构成关系、质量/力守恒等残差。

stream 焓 `h_outflow` 不直接强制相等；标量信号和气动外部容积也不进入同一通用连接残差，而由专用 resolver 处理。

### 4.3 压力流量因果化与非线性回退

`PressureFlowSolver` 初始化时预编译方程模板、effort 等值组、显式流/力赋值计划、未知量布局，以及方程声明到未知量的静态关联图。热流闭合先按物理连通关系划定安全范围，再在可信内置模型中按这张关联图拆成更细的方程块。每次 `solve()`：

1. 从上一解与当前动态状态播种端口未知量；
2. 传播状态拥有的压力、位移和速度；
3. 执行可显式求值的构成关系与守恒关系；
4. 处理单边接触约束；
5. 若缩放后残差不超过 `1e-7`，直接返回且 `evaluations=0`；
6. 否则找出残差未闭合或种子不可行的方程块，把这些互相独立的块合并成一次 sparse `least_squares`；
7. 方程块失败时恢复原始 `x0`，执行全局 sparse `least_squares`；全局 sparse 仍失败时再次恢复同一个 `x0`，最后执行 dense 兼容回退。

非线性回退当前参数为 `x_scale="jac"`、`ftol=xtol=gtol=1e-10`、`max_nfev=500`。可信结构会传入由声明图编译的 `jac_sparsity`；活动单边接触会改变坐标和活动集，自定义组件也可能没有完整依赖声明，因此这些情况继续使用 dense 路径。稀疏/分块是加速层，不会把失败候选带入兼容回退。诊断中的 `evaluations` 是 SciPy 报告的优化器 `nfev`，`residualEvaluations` 才包含数值 Jacobian 在内的真实残差回调数，并通过 `jacobianMode`、`denseFallbackUsed` 和块回退字段说明实际路径。

**[当前边界]** 第一次压力流量求解仍要保证全网所有方程成立，但“全网语义”不再等于“总是把全部未知量交给一个 dense 优化器”：可信声明图可只求本轮未闭合方程块的 union。后续 stream 固定点则进一步只重算敏感方程块。保守条件会恢复全网 sparse→dense 行为；没有可信依赖声明或活动接触时，仍可能直接恢复 dense，成本会随未知量数快速上升。

在用户提供的 `test_mql-full-branches-01-04.xml`（SHA-256 `2fb95e65f5de0c85a6a17802aef74ea004087323fd00fd8d01acf0184ff71d48`）中，472×472 代数关联矩阵只有 919 个结构非零项，密度约 0.413%，可拆为 58 个独立方程块。一个受控扰动实验在相同 `max_nfev=20` 下，dense 与 sparse 分别触发 3796 和 164 次真实残差回调，墙钟约为 7.357 s 和 0.634 s，即同一预算下约 11.6 倍的单次回退成本改善；这项实验只衡量回退开销，不代表两条路径在 20 次评估内已经收敛。

## 5. 每次导数计算的代数闭合

这一步就是第 0 节所说的“当前瞬间对账”。以高压气缸—节流孔—管路—低压储罐为例，求解器需要同时保证：

- 接头压力相容；
- 从一个组件流出的质量等于进入另一个组件的质量；
- 节流孔和管路自己的压差—流量关系成立；
- 气体携带的能量按实际流向交给下游；
- 若还有机械活塞或控制信号，它们在同一时刻也要一致。

代码先建立全网初始压力解，再传播 stream 焓；只有组件方程明确依赖 stream 的范围，才让 stream 焓和其方程—未知量关联块继续迭代到同一个固定点。这样既让当前 RHS 不依赖上一次调用留下的焓/流量历史、保持有限差分 Jacobian 可重复，又避免无关方程重复对账。物理岛仍用于确认范围不会跨越未声明边界，但不再等同于实际求解块。

`GenericFluidSystem._close_current_state()` 的实际顺序见 `app/simulation/systems/generic.py`：

| 顺序 | 操作 | 目的 |
| ---: | --- | --- |
| 1 | `SignalResolver.solve(time)` | 用构造时预绑定的信号源和连接更新时间信号 |
| 2 | 传播机械 `x/v` 等值关系 | 把当前机械状态同步到刚性连接端口 |
| 3 | `PneumaticVolumeResolver.solve()` | 用预绑定的气动端口、输出组件和连接传播外部 `volume/volume_flow` |
| 4 | 刷新动态组件热力端口 | 由当前 `m/U/V` 和最新体积恢复压力、温度、焓 |
| 5 | 第一次全网 `PressureFlowSolver.solve()` | 建立本轮热流固定点的初始压力和流量 |
| 6 | `StreamResolver.solve()`，必要时最多 25 轮重算敏感方程块 | 用预绑定的组件、端口和连接传播焓；让焓、温度引用和敏感构成流量同时收敛 |
| 7 | 更新机械约束加速度 | 为机械状态导数准备 `a` |

随后 `rhs()` 才收集各动态组件的导数。

因此每次闭合固定有 **1 次全网语义**的压力流量求解；没有敏感方程块时，stream 传播一次后结束，不再有第二次压力求解。若有 `B` 个敏感方程块，每一轮外层热流固定点会把相应块作为一个 union 快路径求解，最多 25 轮；保守回退时恢复原全网求解器。stream 自身仍有相对容差 `1e-9` 和最多 100 次内部迭代，外层热流固定点最多 25 轮，两层上限不能混为一个数。上述大型 XML 的敏感 union 是 9 个方程块、合计 192 个未知量，而不是其单一巨大物理连通岛中的全部 472 个未知量。

signal、stream 和外部 volume resolver 已把静态组件列表、端口引用和连接绑定预编译到系统构造阶段；运行时仍执行真实的信号赋值、焓迭代、volume 传播和动态热力刷新。闭合计划只在组件以布尔能力声明明确说明压力流量方程是否依赖 stream、且方程变量声明可信时裁剪；未分类自定义 stream 组件、非法声明、跨组件残差或局部非方阵都会保守回退全网。这个边界避免把“少扫描”误做成“少算物理关系”。

## 6. 初始化、积分参数与推进方式

可以把初始化理解为“先摆好第 0 帧”，把积分理解为“根据每一帧的变化速度继续制作后续帧”。初始化并不会自动修改所有不合理的初始存量；它主要是在给定初始质量、能量、位置和速度后，求出与之匹配的端口压力、流量和力。

### 6.1 初始状态

`consistent_initial_state_vector()` 取得组件构造时形成的初值，应用该状态并执行一次完整代数闭合，然后原样返回状态向量（`app/simulation/systems/generic.py:292-296`）。

**[重要边界]** 这不是通用 DAE 一致初值求解：它不会联合调整微分状态及导数，只求“给定当前动态状态时”的端口代数变量。固定 TestModel 的专用压力投影/初始化逻辑不能外推为通用 XML 求解器能力。

### 6.2 参数来源及真实含义

初学者最需要先分清 XML v3 的 `sampleStep` 和 `maxStep`（进入 Python 后分别是 `sample_step` 和 `max_step`）：

- `sampleStep` 只控制**结果多久记一条**；
- `max_step` 才限制**内部一次最多走多远**；
- 自适应求解器可以走得比 `max_step` 更短，也可能先试一步、发现误差过大后退回来重算。

所以，把 `sampleStep` 从 0.1 改成 0.01 通常会让输出曲线更密、结果占用更多内存，但它不等价于命令求解器固定每 0.01 秒算一步。

| 参数 | 当前来源/默认值 | 实际用途 |
| --- | --- | --- |
| `t_start / t_stop` | 前端与 Pydantic 默认 `0 / 2 s` | 积分区间 |
| `sampleStep`（内部 `sample_step`） | 默认 `0.1 s` | 仅生成输出 `t_eval` 采样网格；工程 JSON 仍暂名 `simulation.step` |
| `maxStep`（内部 `max_step`） | 默认 `0.005 s` | 自适应求解器内部已接受步的上限 |
| `method` | 默认 `BDF` | BDF、Radau、LSODA、RK45、RK23、DOP853 |
| `rtol` | 通用 XML 路径硬编码 `1e-6` | 外层 ODE 相对误差；用户不可配置 |
| `atol` | `SolveIVPConfig` 标量默认 `1e-8`；机械状态收紧到 `min(default, 1e-12)` | 热力状态使用默认值，机械速度/位置使用更紧的分量容差；用户不可配置 |
| `first_step` | 默认 `None` | 交给 SciPy；用户不可配置 |
| 代数残差容差 | `1e-7` | 压力流量快速路径/接受标准 |
| 代数最大评估 | `500` | 单次 `least_squares` 上限 |
| stream 容差/迭代 | `1e-9 / 100` | 焓传播固定点 |
| 采样数上限 | `10001` | 限制输出样本，不限制 RHS 次数或事件数 |

前端/Pydantic 默认值见 `frontend/src/App.tsx` 的仿真默认配置和 `app/main.py:131-137`；通用路径构造 `SolveIVPConfig` 见 `app/main.py:684-701`；采样网格见 `app/simulation/systems/generic.py:204-225`。

**[已实现]** `sampleStep` 生成的采样网格会确保包含 `t_stop`，并在超过 10001 点时拒绝；它不会把 BDF 变成固定步算法。实际 RHS 次数由自适应误差控制、Jacobian 估计、拒绝步、事件重启和 `max_step` 共同决定。

### 6.3 逐步推进分派

`integrate_ode()` 位于 `app/simulation/solvers/solver.py:917-1009`：

- 有取消检查、信号断点或机械状态事件时，使用 SciPy 的低层 BDF/DOP853/LSODA/RK23/RK45/Radau 类逐步推进；
- 无上述需求时，可一次调用常规 `solve_ivp`；
- 当前流式接口总会传 `cancel_check`，所以总走逐步路径；
- 同步 XML 接口只有在没有断点/状态事件时才可能走一次性 `solve_ivp`。

逐步路径在每个已接受步上：

1. 检查取消；
2. 推进一步；
3. 仅当本步跨越下一个 `t_eval` 样本或需要机械状态事件检测时构造 dense output，并插入样本；
4. 检测状态事件；
5. 报告进度；
6. 必要时重建求解器。

**[已优化]** 没有跨采样点、也没有状态事件时，不再为每个已接受步无条件构造插值对象。该优化对稀疏采样、无机械事件的模型有收益；用户大型分支 XML 含机械状态事件，所以仍必须在每步保留用于事件定位的 dense output，本轮实测中这项优化对该 XML 没有收益。

Peng–Robinson 试探状态越界会抛 `RecoverableTrialStateError`；代码回到最后已接受状态，将 `max_step` 减半，最多重试 16 次（`app/simulation/solvers/solver.py:528-914`）。

高刚度 XML 的历史失败不是“所有亚帕压力都不物理”，而是优化器原 1 Pa 下界过严：RK45 的内部自适应试探会短暂给出仍严格大于 0 Pa、但小于 1 Pa 的压力种子。当前 `PRESSURE_LOWER_BOUND_PA=0.0`，合法正压试探交回 RK45 自身判断，零压/负压仍由构成方程拒绝。该模型 10 s RK45 已通过且可恢复重试数为 0，因此这里没有用异常重启掩盖真实模型错误。

### 6.4 大型分支 XML 的 `0.69 s` 慢区

用户 XML 包含 98 个组件、472 个代数未知量和 74 个 ODE 状态。旧代码不是在 `0.69 s` 死锁，而是 BDF 到达这一刚性变化区后开始大量缩步、重建有限差分 Jacobian 并做 LU 分解。定位发现，气动外部 volume resolver 把机械位移写入气室容积，形成“机械位置 → 气室热力/压力 → 气动力”的跨域闭环；旧 ODE 稀疏依赖图只沿普通物理端口追踪，漏掉了这条外部 volume 边的 12 个实测显著导数项。

修正采用保守的双向跨域依赖：接收外部容积的气动储能状态依赖相关机械状态，机械力平衡也依赖被耦合的气动状态。结构非零数因此由 1092 增至 1284，有限差分颜色组由 27 增至 31。颜色组稍多不是退化：旧图更小是因为漏项，给 BDF 的 Jacobian 数值不完整，导致后续重复试步的总成本更高。

功能收口过程中的较早阶段测量为 92.187 s；最终稳定代码连续三次完整运行到 `0.81 s`，分别用时 79.049 s、74.658 s 和 85.103 s。三次积分统计均为 `nfev=3393`、`njev=226`、`nlu=667`、接受步 1009、求解器启动 3 次；压力流量求解 28008 次，全部由 seeded 快路径满足残差合同，没有触发方程块或 dense 非线性回退。

三次完整响应按规范 JSON 序列化后的 SHA-256 均为 `454cd11aece1c4a2296a88e2c1dd592eeace28565e342235fb7a7df34de5b18f`。为避免诊断字段增删造成“物理结果没变但响应哈希变化”，另定义外部标签 `physical-solution-v1`：待哈希对象只投影 `{status, simulatedUntil, requestedStopTime, series, final}`，标签本身不放入对象；用 `json.dumps(sort_keys=True,separators=(",",":"),ensure_ascii=False)` 规范化后 SHA-256 为 `04982f427867801c582fea81c6e2da0b726bd8a61d7894b311e4a807b19e89a7`。旧 `09b5c7…` 是聚合诊断和最终 union 路径收口前的 full-response 哈希，受响应结构影响，不能与当前哈希直接比较。

本轮还区分验证了两种容易混淆的“容差”。机械状态 `atol` 从 `1e-12` 放宽到 `1e-10` 的单次 A/B 约快 16%，但这会改变机械状态与事件的误差合同，当前证据不足，未采用。另一项是外层 thermofluid **流量固定点**相对容差从 `1e-12` 放宽到 `1e-9`；它反而增加 BDF 内部步数并改变积分轨迹，也未采用。这里的正式修复是补全依赖图，不是通过放宽精度或闭合容差掩盖问题。

仓库有固定 RK4 回退，但通用压力流量求解器本身依赖 SciPy；因此它不能被视为一般流体网络在无 SciPy 环境下的完整替代方案。

## 7. 事件、取消与停止

### 7.1 信号离散时刻

STEP0、UD00 等信号源提供离散事件时刻。积分器先推进到事件左侧的相邻浮点时刻，再在精确事件时间更新信号并重建求解器，连续动态状态保持不变（`app/simulation/solvers/signal.py:70-99`、`app/simulation/components/amesim/signals/sources.py:128-141`）。

### 7.2 机械端挡

机械状态事件在已接受步的 dense state 上检查端挡穿越，最多 60 次二分定位；命中后按塑性/恢复系数重置位置和速度并重启积分器。同一时刻最多允许 64 次链式状态重置（`app/simulation/solvers/mechanical.py:430-627`、`app/simulation/solvers/solver.py:92-166`）。

**[约定]** 这是为信号断点与机械端挡编写的专用事件框架，不是可由任意组件声明残差事件的通用高指数 DAE 框架。

### 7.3 协作取消

流式任务的取消端点只设置共享 `threading.Event`。积分器在已接受步、重试边界等检查点协作停止；若正在执行一次耗时的热物性、stream 或 `least_squares` 调用，取消不能立即抢占（`app/main.py:535-547`、`app/simulation/solvers/solver.py:917-1009`）。

停止后若至少已有两个有效采样点，通用系统可整理并返回部分结果；相关行为由 `tests/test_generic_system_xml_simulation.py:433-533` 覆盖。

## 8. 后处理与现有诊断

### 8.1 结果后处理

积分完成后，`GenericFluidSystem.simulate()` 重置机械约束模式，并对每个 `solution.t`：

1. 重新应用状态；
2. 再执行一次完整 `_close_current_state()`；
3. 提取所有组件级及端口级公开结果变量。

见 `app/simulation/systems/generic.py:397-474`。

**[推断]** 采样密集或结果变量多时，这会形成明显的第二计算阶段；此时内存中还保留积分状态矩阵，CPU 与内存峰值可能重叠。

**[当前边界]** 本轮优化没有复用积分期间的闭合快照，也没有跳过后处理对账。每个输出点仍执行完整 `_close_current_state()`；变化仅在于该闭合内部使用同一套预编译绑定和敏感方程块执行计划。

### 8.2 当前返回的诊断

**[已实现]** 结果包含：

- 状态数、采样数；
- 压力流量 `solveCount`、`closurePassCount`、`secondaryPhysicalIslandCount`、真实方程 `secondaryBlockCount`、`secondaryUnknownCount`、保守回退原因、最大残差、最大单次评估数和最后求解作用域；
- stream 最大迭代数；
- 停止状态及部分错误上下文。

**[已实现]** 积分诊断已经包含分段及汇总的 `nfev/njev/nlu`、已接受步、求解器启动、状态迁移和可恢复重试数。设置 `SIMULATIONAPP_PROFILE=standard|audit` 后，响应还会加入分阶段墙钟时间；audit 进一步记录物性调用、精确重复、缓存命中和逆解迭代。

**[已修复]** 闭合现在聚合所有实际压力求解的最大残差和最大单次评估数，`last` 与 `lastScope` 指向最后一个真实求解作用域，不再被一个未执行或较早 pass 的局部变量覆盖。`solveCount` 统计求解器调用次数，`closurePassCount` 单列发生过压力求解的固定点 pass；`secondaryPhysicalIslandCount` 只表示安全分类得到的物理范围，`secondaryBlockCount` 明确表示方程关联块数，不能再把两者混称为“块”。代数诊断还返回真实 `residualEvaluations`、`jacobianMode`、dense/方程块回退状态。子作用域失败时，API 返回 `scopeKind` 和 `scopeComponents`。仍缺少峰值 RSS、任务队列深度等服务级指标；结果字节和编码时间目前由离线基准工具测量，不进入常规 API 响应。

## 9. 求解时前后端交流

主路径可以压缩为下图：

```text
浏览器 ──一次 POST：完整 System XML──────────────> 后端
浏览器 <──同一长连接：心跳、进度、心跳、进度──── 后端求解线程
浏览器 <──最后一个消息：完整结果 JSON─────────── 后端
浏览器 ──需要时另发取消 POST───────────────────> 后端
```

这里的“流式”主要是**进度消息流式**，不是每算出一段曲线就立刻传一段曲线。最终数值序列仍在末尾一次性返回。

### 9.1 当前协议

| 阶段 | 通信 | 当前行为 |
| --- | --- | --- |
| 提交 | 一个 HTTP POST | 请求体为完整 XML；`X-Simulation-Id` 标识任务 |
| 运行 | 同一响应上的 NDJSON | 进度事件、错误事件、5 秒心跳 |
| 完成 | 同一 NDJSON 流最后一行 | 一次性携带完整 `SimulationResult` |
| 用户取消 | 另一个短 POST | 设置协作取消事件；原流继续等待终态 |
| 流断开/停滞恢复 | GET 状态 | 每 500 ms 轮询，最多 30 秒 |

后端路由见 `app/main.py:589-634, 773-906`，前端解析、取消和恢复见 `frontend/src/App.tsx` 中的 `streamSystemSimulation()` 及相邻任务控制函数。

**[已实现]** 后端每 5 秒无队列事件时直接发送 heartbeat。通用系统按进度至少变化 0.25% 才发送积分进度，通常至多约 400 条积分进度事件（`app/simulation/systems/generic.py:318-343`）。

前端规则：

- 30 秒没有收到任何字节：连接超时；
- 60 秒只收到心跳而没有真实积分进度：判定 stalled 并请求取消；
- 正常运行不是轮询，轮询仅用于异常恢复。

**[发现]** 合法但单个已接受步/闭合超过 60 秒时，前端可能误判停滞。后端结果事件的 `phase` 使用 `completed/stopped/stalled/failed`，前端事件类型却声明 `"complete"`；运行时当前没有按该字段做严格校验，所以契约漂移尚未直接报错（`app/main.py:825-840`、`frontend/src/App.tsx` 的流式事件类型）。

### 9.2 开发和部署连接数

**[已实现]** 开发态 Vite 将 `/api` 代理到 `127.0.0.1:8000`（`frontend/vite.config.ts:4-10`），所以一个流式仿真在开发态占用浏览器→Vite、Vite→FastAPI 两段长连接；若生产部署由 FastAPI/反向代理直接提供 API，则具体连接层数取决于部署。

仓库没有 WebSocket 路由、`EventSource` 或 `text/event-stream`；当前 NDJSON 只是普通 HTTP 分块响应。

## 10. CPU、线程、内存、网络和磁盘占用

先区分两个问题：

- **一个算例跑得快不快**：主要看每次变化率计算做了多少轮闭合、非线性试算和热物性计算；
- **多人同时运行稳不稳**：主要看并发任务是否有上限、是否能使用多个进程、每个结果在内存中保留多少份。

“每个任务开一个线程”不等于“每个任务独占一个 CPU 核”。Python 组件逻辑、SciPy 数值核和底层 BLAS 的实际并行程度取决于运行环境；仓库没有 CPU/RAM 实测数据，所以本节只给代码可证明的结构和数量级。

### 10.1 进程与线程

- `start-all.bat` 分别启动 Vite 与 FastAPI（`start-all.bat:19-22`）。
- `start-backend.bat` 的 Uvicorn 命令没有 `--workers`，当前脚本即单进程单 worker（`start-backend.bat:17-21`）。
- 每个流式仿真创建一个 daemon `threading.Thread` 和一个无界 `queue.Queue`；没有信号量、线程池或排队上限（`app/main.py:773-880`）。
- 全局任务字典只在读写元数据时持锁，不限制同时启动的求解数量。
- `POST /api/system-xml/simulate` 是 `async def`，但直接执行同步 CPU 求解；若调用该端点，会占用当前 Uvicorn 事件循环。

**[推断]** 单个求解主要是串行 Python 全网扫描加 SciPy 数值核，常会持续消耗一个核心；多任务线程不保证线性利用多核，还可能出现 GIL 竞争、SciPy/BLAS 原生线程过度订阅和内存峰值相叠。仓库没有固定 BLAS 线程数，具体 CPU 占用必须在目标部署环境实测。

### 10.2 内存数量级

不计 Python 对象常数项，主峰值可写为：

```text
O(组件 + 连接 + 代数结构)
+ O(采样数 × 动态状态数)
+ O(采样数 × 公开结果变量数)
```

当前采样上限是 10001。放大因素包括：

- 积分状态矩阵与后处理 `series` 在后处理阶段同时存在；
- 最终完整结果保存在全局任务记录中，又被编码为一个大型 NDJSON 行；
- 前端收到结果后执行 `structuredClone`，再 `JSON.stringify` 写入 `sessionStorage`（`frontend/src/App.tsx` 的结果快照与恢复逻辑）；
- 图表会把数值数组映射为对象点数组，多个曲线窗口会产生更多前端副本；
- CSV 导出把完整结果再次上传，后端在 `StringIO` 中一次性构造完整 CSV（`frontend/src/SimulationResultsView.tsx:1041`、`app/main.py:299-377`）。

`SIMULATION_TASK_RETENTION_SECONDS=600`，但过期任务只在注册下一个任务时清理；没有新任务时，最后一批终态结果可能一直保留到进程退出（`app/main.py:491-520`）。

### 10.3 队列、网络和磁盘

- 任务队列是无界的，但进度被 0.25% 节流；正常单任务队列通常不大，客户端变慢或终态序列化时仍没有硬上限。
- 最终数值序列不分块，网络、后端 JSON 编码、前端字符串缓冲与 `JSON.parse` 会在完成时形成瞬时峰值。
- 通用 XML 求解本身不写仿真产物，结果主要驻留内存。
- 固定 TestModel 与 public Test MQL runner 会在 `app/data/simulation-runs` 下写时间戳产物；这不是主流式路径的磁盘行为。

## 11. 其他求解入口不能与主路径混同

### 11.1 固定 TestModel

`POST /api/reactflow/simulate-testmodel` 从所选类型/参数中提取固定数量的气瓶、贮箱、管/孔板来构造专用 `TestModelClosure`，不消费用户的任意节点边拓扑；它复用 `integrate_ode`，并写 CSV、SVG 和报告产物（`app/main.py:1363-1447`、`app/simulation/examples/testmodel/run.py`）。

它是回归/演示算例，不是通用 ReactFlow 网络求解器。

### 11.2 Test MQL

`POST /api/reactflow/simulate-test-mql` 当前忽略任意拓扑和主要积分配置；`TestMqlSystem.simulate()` 构造 132 状态的全零 `y`，只返回结构数量随时间的摘要（`app/main.py:1450-1481`、`app/simulation/examples/test_mql/system.py:6302-6318`）。

完整的 112 个气动状态与 20 个机械状态闭包存在于独立诊断/comparison 代码，但没有接入这个公开 API；仓库仍将其描述为校准阶段，不能宣称与 AMESim 全时域等价。

## 12. 当前明确的效率热点

| 热点 | 代码证据 | 影响范围 | 判断 |
| --- | --- | --- | --- |
| 每次闭合的压力流量重算 | `generic.py` 的预编译热流闭合计划 | 每个 RHS、初始化、每个结果采样点 | [已优化] 固定 1 次全网语义初解；后续只重算 stream-sensitive 方程关联块，不再把整个敏感物理岛重复求解 |
| stream 每轮复制/比较焓并刷新 | `stream.py` | 每个闭合，最多 100 轮 | [静态预编译已完成] 组件、端口和连接已预绑定；每轮必要的数值复制、比较和刷新仍保留 |
| 非线性回退使用有限差分 least-squares | `algebraic.py` | 快速路径失效时 | [首轮已优化] 可信声明图先做未闭合方程块 union sparse；失败恢复 `x0` 后做 global sparse→dense；接触/不可信结构保留 dense |
| 外层 ODE Jacobian 稀疏依赖图 | `generic.py`、`solver.py` | BDF/Radau 的每步/Newton | [已修复] 已传 `jac_sparsity`；补上外部 volume 的跨域双向依赖，用户 XML 为 1284 非零/31 色 |
| 热物性重复反算 | `mediums.py` 及各动态组件 refresh | 每个 RHS/闭合 pass | [已优化] 2026-08-16 已加入仿真隔离的四项氦气精确 LRU；代表算例 2,869/435 次命中/未命中，PR 三次根调用由 1,712 降至 689 |
| 每采样点完整后处理闭合 | `generic.py:397-474` | 输出点 × 全网 | [已实现] |
| dense output 插值对象 | `solver.py` | 流式逐步路径 | [已优化] 仅跨样本或需要状态事件时构造；含状态事件的用户 XML 每步仍需要，因此无本案收益 |
| 无界求解线程与任务结果驻留 | `main.py:491-520, 773-880` | 并发任务 | [已实现] 稳定性风险，不等于单算例变慢 |
| 完整结果单行 JSON 与前端多副本 | `main.py:825-840`、`App.tsx:8872-8958` | 大输出 | [已实现] 内存/网络热点 |

下面是 2026-08-16 **物理岛版首轮实现的历史 `off` 基线**。这些数据仍可说明旧执行计划相对更早“每轮全网”的收益，但该实现已由方程关联块版取代，不能把表中的“块”解释为当前 `secondaryBlockCount`：

| 算例 | 墙钟改善 |
| --- | ---: |
| `air_chain` | 7.9% |
| `air_branched` | 6.5% |
| `helium_step` | 0.6% |
| `mechanical_contact` | 21.4% |
| high-stiffness short | 14.6% |

完整 high-stiffness 10 s 的历史基线约 28.126 s，本轮全部改动后的中位数为
13.694 s；这个跨版本差额不能归到某一项优化。当前代码上单独强制恢复全网后续
闭合的受控对照为 optimized 14.676 s、forced-global 16.929 s，完整 `series`
一致。`helium_step` 只有一个仍需重算的敏感岛，改善仅 0.6%；这说明收益取决于
可跳过多少无关网络，不能宣称单一氦岛也有两位数提升。后处理的逐采样点完整闭合
仍然保留。

当前方程关联块版另用用户大型分支 XML 做了受控短区间 A/B：输入 SHA-256 为 `2fb95e65f5de0c85a6a17802aef74ea004087323fd00fd8d01acf0184ff71d48`，含 98 个组件、472 个代数未知量和 74 个 ODE 状态。stream 后续求解的 9 个方程块合计 192 个未知量；`0～0.01 s` optimized 与 forced-global 分别为 16.200 s 和 18.584 s，物理解与 `series` 逐值一致。最终稳定代码完整 `0～0.81 s` 连续三次为 79.049 s、74.658 s 和 85.103 s，积分统计均为 `nfev/njev/nlu=3393/226/667`。短区间 A/B 只归因于后续 stream 闭合作用域，完整运行同时包含 Jacobian 修正和最终执行路径收口，二者不能混算成一个百分比。

## 13. 优化建议排序

以下按**预期综合收益**排序；同档位优先低风险、低难度项。排序同时参考代码结构和 2026-08-15 的阶段/物性实测，但尚未覆盖大规模拓扑与多任务吞吐。“单算例”指一个模型的墙钟时间，“吞吐”指多任务服务能力。

### 13.1 先看人话版

在改算法前，应先给各阶段计时和计数；这本身不直接加速，但能防止优化错地方。之后可按下面顺序理解主要方案：

| 顺序 | 人话方案 | 为什么可能更快 | 主要风险 |
| ---: | --- | --- | --- |
| 1 | 少做重复“瞬时对账” | [方程块首轮已完成] 初解保持全网语义，后续只重算 stream-sensitive 的关联方程块 | 自定义/异常结构必须继续保守回退，不能漏掉真实耦合 |
| 2 | 先整理方程，再求解 | [稀疏首轮已完成] 可信声明图将未闭合块合并求解；大模型回退时减少数值 Jacobian 试算 | 接触活动集和不可信自定义声明必须走兼容回退 |
| 3 | 给不同状态使用合适的“尺子” | 质量、内能、位置、速度量级差异很大；合理缩放可减少无效内部步 | 容差改变会影响精度和事件时刻 |
| 4 | 相同输入不要重复查热物性 | 同一轮闭合中常以相同状态反算压力、温度等 | 缓存失效不严谨会产生错误结果 |
| 5 | 只计算、保存和传输需要的曲线 | 采样多、变量多时，可同时减少后处理、内存和网络开销 | 会改变默认结果合同，需要保留完整模式 |
| 6 | 给并发任务设固定“办理窗口” | 有界进程 worker 可防止无限建线程，并更好利用多核 | 对单个算例未必更快，跨进程取消和结果传递更复杂 |

下面的完整表把这些方向进一步拆成 12 项，并明确收益、风险和实施难度。

| 排名 | 建议 | 主要收益对象 | 预期收益 | 风险 | 实施难度 |
| ---: | --- | --- | --- | --- | --- |
| 1 | [方程块首轮已完成] 将 `_close_current_state` 编译为按能力/依赖启用的执行计划：signal/stream/volume 预绑定；首次压力求解保留全网语义，仅在 stream 确实使构成关系变脏时重算相关方程关联块，并保留全网回退和耦合迭代上限。 | 单算例 | 历史物理岛版实测 0.6%～21.4%；大型 XML 方程块版短区间 16.200 s 对 18.584 s | 中：错误裁剪会破坏耦合一致性，需持续回归自定义模型 | 已完成首轮 |
| 2 | [稀疏首轮已完成] 可信方程声明图已用于 union block sparse 和 global sparse→dense 回退；后续继续评估 equality group 真正消元、解析 Jacobian，以及活动接触的安全分块。 | 单算例、大网络 | 扰动实验同预算残差回调 3796→164，约 11.6 倍；实际收益取决于是否触发非线性回退 | 高：接触活动集与错误声明会影响收敛 | 首轮已完成，继续深化 |
| 3 | [依赖图已修复] BDF/Radau 已使用状态 `jac_sparsity`，外部 volume 跨域漏边已补；后续再评估状态缩放和可配置分量级 `rtol/atol`，不要简单全局放宽容差。 | 单算例、刚性网络 | 大型 XML 已从 `0.69 s` 慢区定位并完整跑通；机械 `atol` A/B 虽约快 16%但改变精度合同，flow 固定点放宽则增加步数，均未采用 | 中高：会改变误差轨迹/事件时刻 | 稀疏图首轮完成，缩放待评估 |
| 4 | [已完成] 氦气高成本物性已按单次仿真做精确、有界缓存；dynamic components 及 signal/stream/volume 的静态组件、端口和连接也已预绑定。 | 单算例 | 已取得可见收益，且减少固定拓扑的重复查找 | 中：缓存失效错误会污染物理结果 | 已完成 |
| 5 | 改造结果选择和后处理：允许选择变量、采样/降采样；避免对不需要的变量和时间点执行完整闭合，必要时复用积分期间已接受的闭合快照。 | 单算例、内存 | 长仿真/多变量时高 | 中：结果合同与复用精度 | 中高 |
| 6 | 引入有界作业队列和固定大小的进程 worker；统一让同步端点也进入执行器，并设置最大并发、排队长度和结果尺寸。 | 吞吐、稳定性 | 高；单任务速度通常不变 | 中高：跨进程取消和序列化 | 高 |
| 7 | 进度与结果解耦：NDJSON 只发送进度和 `resultId`，结果按变量/时间块压缩下载或外部存储；前端改用 TypedArray/IndexedDB，图表先降采样。 | 内存、网络、UI | 大结果时高 | 中：需要版本化协议 | 中高 |
| 8 | 主动定时清理任务表，限制任务数/结果字节；成功交付后只保留摘要或引用。将无界进度队列改为“最新进度槽 + 不可丢终态槽”。 | 稳定性 | 中到高 | 低中 | 低中 |
| 9 | [首轮已完成] 只在当前步跨越下一采样点或需要状态事件检测时构造 dense output；后续记录并优化事件重启，大量周期 UD00 事件再评估惰性调度。 | 单算例、事件密集模型 | 无事件且采样稀疏时可减少插值对象；本次含状态事件 XML 无收益 | 低到中 | 首轮已完成 |
| 10 | CSV 在浏览器直接生成或按 `resultId` 服务端流式生成，避免全量 series 重新上传与 `StringIO` 全量复制。 | 内存、网络 | 中 | 低 | 低中 |
| 11 | 用共享 Schema/OpenAPI 生成前后端事件类型，修正 `complete/completed`；停滞依据服务端活动计数/已接受步时间戳并允许按模型调节。 | 可靠性、减少误杀重算 | 中 | 低 | 低中 |
| 12 | 长期评估支持稀疏残差/Jacobian 的 DAE 求解器，将外层 ODE 与内层代数 least-squares 统一成状态—代数系统。 | 复杂大模型 | 潜在很高 | 很高：架构与验证成本大 | 很高 |

结果访问器和每轮剩余临时容器不属于第 4 项已经完成的 signal/stream/volume 静态预绑定；前者应结合第 5 项后处理改造单独基准，不把尚未实测的小项混入已完成收益。

### 13.2 推荐落地顺序

低侵入阶段/物性观测、积分计数和代表算例首轮基准已经落地，但不把“加指标”误列为直接加速。下一步建议：

1. 继续汇总压力流量快路径命中、非线性 `nfev`、真实 `residualEvaluations` 和残差装配时间；单次诊断已能区分 block sparse、global sparse 和 dense 回退；
2. 用同一套基准把方程声明图 A/B 扩展到更多自定义组件、活动接触和保守回退路径；大型 98 组件 XML 与首轮短算例已经覆盖可信内置路径；
3. 补 1/8/32 单元规模曲线、1/2/4 并发吞吐和峰值 RSS；
4. 记录状态/结果数组字节、任务队列深度；结果 JSON 字节可继续由基准工具测量；
5. 再决定 equality group 真正消元/解析 Jacobian、结果按需计算和进程 worker 的实施深度。

每项算法改动都应继续验证质量/能量守恒、正反流、stream 混合、机械端挡、信号断点、取消部分结果和 AMESim/TestModel 基线。相关测试证据包括 `tests/test_generic_system_xml_simulation.py:244-533`、`tests/test_core_solver.py:19-508`、`tests/test_amesim_mechanical_public_components.py`。

## 14. 已实现、约定与推断的边界汇总

### 已实现

- System XML 校验、拓扑编译和通用半显式 ODE/代数求解主链。
- 气动、机械和信号的专用闭合顺序。
- 压力流量显式因果化快路径，以及可信声明图上的 union block sparse、global sparse→dense `least_squares` 兼容回退；失败候选不会污染原始 `x0`。
- signal/stream/外部 volume 静态绑定，以及“全网语义初解 + stream-sensitive 方程块重算 + 保守全网回退”的闭合执行计划。
- 明确区分物理岛、方程块和方程块未知量的诊断，并记录实际残差回调、Jacobian 模式、最后作用域和子块失败作用域。
- BDF/Radau 状态 `jac_sparsity`，以及外部 volume 跨域双向依赖修正。
- dense output 按采样跨越/状态事件惰性构造；状态事件模型仍保持每步插值能力。
- 允许严格正亚帕试探压力的高刚度 RK45 路径；零压和负压仍不接受。
- 自适应积分、输出采样、信号断点、机械端挡、协作取消和部分结果。
- NDJSON 长响应、心跳、取消端点、异常恢复轮询和任务状态表。
- 单 Uvicorn worker、每任务 daemon 线程、完整终态结果驻留与浏览器多副本行为。

### 约定

- 内核定位为半显式 ODE/代数 MVP，而非任意 DAE。
- XML/组件运行参数使用 SI 基准值。
- 采样上限、超时、心跳和任务名义保留时长。
- 组件参数在单次运行中静态；时间变化通过信号源等模型表达。

### 已有初步实测、仍需扩大样本

- 压力流量闭合是当前代表气动短算例的首要热点；物性调用具有高精确重复率，仿真隔离的四项 PR 氦气缓存已取得可见端到端收益。
- 长氦气代表算例的积分阶段占约 90.5%，后处理约 5%。
- 物理岛版闭合执行计划的历史短算例配对收益为 0.6%～21.4%；完整 high-stiffness optimized/forced-global 历史对照为 14.676 s/16.929 s，数值序列一致。这些基线保留用于纵向比较，但已不是当前方程块实现。
- 当前大型分支 XML 的 stream 后续闭合为 9 个方程块/192 个未知量；`0～0.01 s` optimized/forced-global 为 16.200 s/18.584 s 且物理解/`series` 逐值一致。最终稳定代码完整 `0～0.81 s` 连续三次为 79.049 s/74.658 s/85.103 s，积分统计一致。
- 代数 sparse 扰动实验将真实残差回调由 3796 降至 164（约 11.6 倍耗时改善）；它是回退微基准，不能外推为所有仿真的整体加速倍数。
- 上述结论仍需在更大拓扑、更多真实工程和固定硬件环境复测。

### 推断及必须继续实测

- 单个任务实际占用几个核心、SciPy/BLAS 原生线程数和多任务扩展曲线。
- 典型/最大工程的峰值 RSS、结果 JSON 大小、浏览器内存副本和 sessionStorage 成功率。
- 各优化的实际收益；表中排序应在观测数据出现后更新。

## 15. 关键文件与符号索引

| 主题 | 文件与位置 | 关键符号 |
| --- | --- | --- |
| API 主入口与任务流 | `app/main.py` | `run_system_xml_simulation()`、`simulation_event_stream()` |
| JSON/XML 网络编译 | `app/main.py` | `compile_reactflow_network()`、`compile_system_xml_network()`、`_compile_solver_network()` |
| XML v3 校验/解析 | `app/system_xml.py`、`schemas/system-simulation-v3.xsd` | `SystemXmlDocument`、`validate_system_xml_document()` |
| 通用系统准备与仿真 | `app/simulation/systems/generic.py:93-474` | `GenericFluidSystem`、`_close_current_state()` |
| 压力流量代数闭合 | `app/simulation/solvers/algebraic.py` | `PressureFlowSolver.solve()`、方程关联图、sparse→dense 回退 |
| stream 方程块闭合 | `app/simulation/solvers/algebraic_blocks.py` | `StreamPressureBlockSolver` |
| stream 焓 | `app/simulation/solvers/stream.py:29-119` | `StreamResolver.solve()` |
| 标量信号 | `app/simulation/solvers/signal.py:40-109` | `SignalResolver`、`signal_event_times()` |
| 气动外部容积 | `app/simulation/solvers/pneumatic_volume.py:21-93` | `PneumaticVolumeResolver` |
| 机械因果化与事件 | `app/simulation/solvers/mechanical.py:225-627` | `MechanicalStateReducer` |
| ODE 推进 | `app/simulation/solvers/solver.py:37-1009` | `SolveIVPConfig`、`integrate_ode()` |
| 启动暖机 | `app/simulation/warmup.py` | BDF、稀疏分组、`least_squares` sparse LSMR 路径 |
| 可选性能埋点 | `app/simulation/performance.py` | `profile_run()`、`profile_phase()`、`profile_property()` |
| 可重复性能基准 | `app/simulation/benchmark_performance.py` | `python -m app.simulation.benchmark_performance` |
| 前端流式协议 | `frontend/src/App.tsx` | `streamSystemSimulation()`、取消/轮询 |
| 启动方式 | `start-backend.bat:17-21` | Uvicorn 单 worker 命令 |
| 主路径回归测试 | `tests/test_generic_system_xml_simulation.py`、`tests/test_core_solver.py` | 通用仿真、事件、取消 |