39 KiB
SystemSimulationApp 后端求解逻辑与效率优化调研（通俗版）
调研基线：2026-08-12（System XML v3 迁移后），依据当前仓库代码、配置、说明文档与测试。 本文所称“主求解路径”是当前前端实际调用的 System XML 流式接口；固定 TestModel 和 Test MQL 接口另行说明。文中没有把静态代码分析冒充 CPU、内存实测。
0. 三分钟读懂
0.1 求解器到底在做什么
先不管 ODE、RHS、BDF 这些名字。把一次仿真想成制作一段工程动画：
- 检查装配图。 气管有没有漏接，控制线方向对不对，模型参数是否齐全。
- 读取当前“存量”。 例如气室里有多少气体和能量，质量块现在的位置和速度。
- 让当前瞬间自洽。 根据这些存量，把此刻的压力、流量和力反复对账，直到连接规则和组件方程同时满足。
- 计算变化速度。 得出“下一小段时间内，质量、能量、位置、速度将怎样变化”。
- 内部小步前进。 求解器自己决定每次走多小；变化剧烈时会缩短步长。
- 按用户指定时刻留快照。 内部可能算很多小步，但结果文件只在 XML v3 的
sampleStep指定的时刻保存数值。 - 把进度和结果交给前端。 运行中发心跳/进度，结束时一次性发送完整曲线数据。
项目里的技术说法“半显式 ODE + 每次变化率计算前做代数闭合”，翻译成人话就是：会积累的量用时间积分向前推；必须在当前瞬间成立的关系，每次都先对账求平衡。
0.2 用仓库里的真实案例贯穿全文
tests/test_generic_system_xml_simulation.py:86-145 有一条完整回归气路：
高压气缸 低压储气罐
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。它们可以这样理解：
结果快照： 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. 结论先行
- [已实现] 当前主内核是“半显式 ODE + RHS 内代数闭合”。 动态组件只把储能状态交给 ODE 积分器；每次计算导数前，系统先传播信号、刷新热力状态、求压力/流量代数网络、传播变容边界、迭代 stream 焓并更新机械加速度。它不是通用 DAE 求解器，也不等价于完整 Modelica
inStream/actualStream语义（README.md:18-20、app/simulation/README.md:174-195）。 - [已实现] 当前前端主链路是 System XML 流式仿真。 浏览器生成 XML，经
POST /api/system-xml/simulate-stream发送；后端以 NDJSON 返回心跳与进度，最后在一个 JSON 行中返回完整结果。不是 WebSocket 或标准 SSE。 - [已实现] XML v3 的
sampleStep是输出采样间隔，不是固定积分步长。 内部的max_step（XML 为maxStep）才是自适应积分步长上限；BDF/Radau/LSODA/RK45/RK23/DOP853均受支持。流式运行因总是提供取消检查，会使用 SciPy 低层求解器逐个已接受步推进。 - [已实现] 每次 RHS 的完整闭合至少调用 2 次、存在外部容积传播时最多调用 3 次压力流量求解。 积分结束后，每个输出采样点又执行一次完整闭合并提取全部公开结果。这是当前最明确的单任务重复工作来源。
- [已实现] 代数求解已有因果化快路径。 压力流量求解器预编译相等组与显式流量计划，种子残差足够小时不调用非线性优化；否则对全局未知向量调用 SciPy
least_squares，当前未提供解析 Jacobian 或jac_sparsity。 - [已实现] 当前启动脚本是一个 Uvicorn worker。 每个流式任务再创建一个无并发上限的 daemon 线程和无界队列；没有进程池、集中任务队列、CPU/内存配额或持久化作业系统。同步仿真端点还会在
async def中直接执行 CPU 密集代码。 - [推断] 优化应分两条线：
- 单算例速度：减少闭合 pass、代数未知量与残差装配，缓存热物性，改善外层积分尺度/Jacobian，减少后处理重算；
- 服务吞吐与资源稳定性：有界进程 worker、结果分块/按需返回、任务表主动清理和前端结果存储降副本。
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. 主求解调用链
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()：
validate_system_xml_document()执行大小/安全解析、v3 XSD 和语义校验；- XML 解析为只含求解信息的规范化执行模型，不重建 ReactFlow 画布；
compile_system_xml_network()创建SimulationNetwork；- 构造
GenericFluidSystem与SolveIVPConfig； - 调用通用
simulate()； - 汇总验证、模型接口、数值结果和错误诊断。
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 等值组、显式流/力赋值计划和未知量布局（app/simulation/solvers/algebraic.py:86-106, 637-729）。每次 solve()：
- 从上一解与当前动态状态播种端口未知量；
- 传播状态拥有的压力、位移和速度；
- 执行可显式求值的构成关系与守恒关系；
- 处理单边接触约束；
- 若缩放后残差不超过
1e-7，直接返回且evaluations=0； - 否则调用
scipy.optimize.least_squares。
非线性回退当前参数为 x_scale="jac"、ftol=xtol=gtol=1e-10、max_nfev=500，没有传入解析 Jacobian 或 jac_sparsity（app/simulation/solvers/algebraic.py:771-968）。
[推断] 即使快速路径经常命中，固定的多次全网扫描、残差重建和热物性刷新仍会发生；一旦回退到有限差分 least_squares，成本会随全局未知量数量快速上升。
5. 每次导数计算的代数闭合
这一步就是第 0 节所说的“当前瞬间对账”。以高压气缸—节流孔—管路—低压储罐为例，求解器需要同时保证：
- 接头压力相容；
- 从一个组件流出的质量等于进入另一个组件的质量；
- 节流孔和管路自己的压差—流量关系成立；
- 气体携带的能量按实际流向交给下游；
- 若还有机械活塞或控制信号，它们在同一时刻也要一致。
代码目前不是一次对完，而是按固定顺序做若干轮专项检查。因此一个“计算变化率”的请求会调用 2 次压力/流量闭合；涉及外部容积传播时会调用 3 次。这也是后文首要优化方向。
GenericFluidSystem._close_current_state() 的实际顺序见 app/simulation/systems/generic.py:258-290：
| 顺序 | 操作 | 目的 |
|---|---|---|
| 1 | SignalResolver.solve(time) |
更新时间信号源并从 output 传播到 input |
| 2 | 刷新动态组件热力端口 | 由当前 m/U/V 恢复压力、温度、焓等 |
| 3 | 第一次 PressureFlowSolver.solve() |
闭合当前压力、流量、机械端口代数关系 |
| 4 | PneumaticVolumeResolver.solve() |
沿气动连接传播外部 volume/volume_flow |
| 5 | 若发生容积传播，再刷新热力状态并第二次求压力/流量 | 让变容边界进入气室状态关系 |
| 6 | StreamResolver.solve() |
按实际流向迭代传播/混合 h_outflow |
| 7 | 无条件再次求压力/流量 | 让依赖 stream/温度的构成关系重新闭合 |
| 8 | 更新机械约束加速度 | 为机械状态导数准备 a |
随后 rhs() 才收集各动态组件的导数（app/simulation/systems/generic.py:298-301）。
因此：
- 无外部容积传播时，每次闭合固定有 2 次压力流量求解；
- 有外部容积传播时固定有 3 次；
- stream 默认相对容差
1e-9、最多 100 次迭代，每轮复制端口焓并扫描组件/端口（app/simulation/solvers/stream.py:29-119）。
[发现] 这套固定顺序没有按模型实际能力裁剪。例如没有信号、没有外部容积源或 stream 不反向影响构成关系的网络，仍经过对应全网 pass。是否能安全删去某一 pass 必须由依赖关系和回归测试决定，不能只凭某个算例结果不变。
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-5 |
外层 ODE 相对误差；用户不可配置 |
atol |
SolveIVPConfig 标量默认 1e-8 |
同时用于不同量纲的全部状态；用户不可配置 |
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。
逐步路径在每个已接受步上：
- 检查取消；
- 推进一步；
- 构造 dense output，并插入跨越到的
t_eval样本； - 检测状态事件；
- 报告进度；
- 必要时重建求解器。
Peng–Robinson 试探状态越界会抛 RecoverableTrialStateError；代码回到最后已接受状态，将 max_step 减半，最多重试 16 次（app/simulation/solvers/solver.py:528-914）。
仓库有固定 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：
- 重新应用状态；
- 再执行一次完整
_close_current_state()； - 提取所有组件级及端口级公开结果变量。
见 app/simulation/systems/generic.py:397-474。
[推断] 采样密集或结果变量多时，这会形成明显的第二计算阶段；此时内存中还保留积分状态矩阵，CPU 与内存峰值可能重叠。
8.2 当前返回的诊断
[已实现] 结果包含：
- 状态数、采样数；
- 压力流量
solveCount、最大残差、最大单次评估数； - stream 最大迭代数；
- 停止状态及部分错误上下文。
[发现] _close_current_state() 中局部变量 algebraic 会被后续 pass 覆盖；最大残差/评估统计只采集每次闭合最后一次压力求解，而 solveCount 才累计了全部调用。现有响应还没有外层积分 nfev/njev/nlu、接受/拒绝步、重启次数、分阶段墙钟时间、热物性调用数、峰值 RSS、队列深度和结果字节数。
因此本文可静态定位重复工作，但不能用现有诊断精确量化每个热点的时间占比。
9. 求解时前后端交流
主路径可以压缩为下图：
浏览器 ──一次 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 对象常数项，主峰值可写为：
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. 当前明确的效率热点
| 热点 | 代码证据 | 影响范围 | 判断 |
|---|---|---|---|
| 每次闭合固定 2～3 次压力流量求解 | generic.py:258-290 |
每个 RHS、初始化、每个结果采样点 | [已实现] 重复 pass；真实耗时待测 |
| stream 每轮复制/扫描并重复刷新 | stream.py:29-119 |
每个闭合，最多 100 轮 | [已实现]；网络越大越明显 |
| 非线性回退用全局有限差分 least-squares | algebraic.py:927-947 |
快速路径失效时 | [已实现]；大非线性网络潜在陡增 |
| 外层刚性积分器看不到显式稀疏 Jacobian | solver.py:528-1009 |
BDF/Radau 的每步/Newton | [已实现] |
| 热物性重复反算 | mediums.py:199-266 及各动态组件 refresh |
每个 RHS/闭合 pass | [推断] 需调用计数确认 |
| 每采样点完整后处理闭合 | generic.py:397-474 |
输出点 × 全网 | [已实现] |
| 每个已接受步构造 dense output | solver.py:528-914 |
流式逐步路径 | [已实现]；无跨样本/事件时可能浪费 |
| 无界求解线程与任务结果驻留 | main.py:491-520, 773-880 |
并发任务 | [已实现] 稳定性风险，不等于单算例变慢 |
| 完整结果单行 JSON 与前端多副本 | main.py:825-840、App.tsx:8872-8958 |
大输出 | [已实现] 内存/网络热点 |
13. 优化建议排序
以下按预期综合收益排序；同档位优先低风险、低难度项。收益是基于调用频率与复杂度的代码推断，不是基准测试结果。“单算例”指一个模型的墙钟时间，“吞吐”指多任务服务能力。
13.1 先看人话版
在改算法前，应先给各阶段计时和计数；这本身不直接加速，但能防止优化错地方。之后可按下面顺序理解主要方案：
| 顺序 | 人话方案 | 为什么可能更快 | 主要风险 |
|---|---|---|---|
| 1 | 少做重复“瞬时对账” | 当前每次变化率计算固定做 2～3 次压力/流量闭合，调用频率最高 | 少做一轮可能漏掉真实耦合，必须按组件依赖裁剪 |
| 2 | 先整理方程，再求解 | 合并重复未知量，把关联较弱的方程分组；大模型回退迭代时收益很高 | 连接、接触和跨域活塞会让分组出错 |
| 3 | 给不同状态使用合适的“尺子” | 质量、内能、位置、速度量级差异很大；合理缩放可减少无效内部步 | 容差改变会影响精度和事件时刻 |
| 4 | 相同输入不要重复查热物性 | 同一轮闭合中常以相同状态反算压力、温度等 | 缓存失效不严谨会产生错误结果 |
| 5 | 只计算、保存和传输需要的曲线 | 采样多、变量多时，可同时减少后处理、内存和网络开销 | 会改变默认结果合同，需要保留完整模式 |
| 6 | 给并发任务设固定“办理窗口” | 有界进程 worker 可防止无限建线程，并更好利用多核 | 对单个算例未必更快，跨进程取消和结果传递更复杂 |
下面的完整表把这些方向进一步拆成 12 项，并明确收益、风险和实施难度。
| 排名 | 建议 | 主要收益对象 | 预期收益 | 风险 | 实施难度 |
|---|---|---|---|---|---|
| 1 | 将 _close_current_state 编译为按能力/依赖启用的执行计划：无信号不扫信号、无外部容积源不传播；仅在 stream 或体积确实使构成关系变脏时追加压力求解。保留可收敛的耦合迭代上限。 |
单算例 | 高；覆盖每个 RHS 和每个后处理点 | 中：错误裁剪会破坏耦合一致性 | 中 |
| 2 | 强化代数结构消元：合并 equality group 中重复未知量，按方程关联图分块，预编译残差/尺度；为非线性回退提供解析或稀疏 Jacobian/jac_sparsity。跨域活塞应按方程关联而非仅按物理域分块。 |
单算例、大网络 | 很高，尤其 least-squares 回退时 | 高：影响收敛与接触约束 | 高 |
| 3 | 为 BDF/Radau 提供状态缩放、分量级 atol 和 Jacobian 稀疏结构；允许有边界地配置 rtol/atol，依据物理时标选择 max_step，不要简单全局放宽容差。 |
单算例、刚性网络 | 中到高 | 中高：会改变误差轨迹/事件时刻 | 中高 |
| 4 | 在单次闭包内缓存热物性结果，并预计算 dynamic components、signal sources、stream components、端口引用和结果访问器；状态或体积变化时严格失效。 | 单算例 | 中到高，热力网络可能高 | 中：缓存失效错误会污染物理结果 | 中 |
| 5 | 改造结果选择和后处理：允许选择变量、采样/降采样；避免对不需要的变量和时间点执行完整闭合，必要时复用积分期间已接受的闭合快照。 | 单算例、内存 | 长仿真/多变量时高 | 中：结果合同与复用精度 | 中高 |
| 6 | 引入有界作业队列和固定大小的进程 worker；统一让同步端点也进入执行器，并设置最大并发、排队长度和结果尺寸。 | 吞吐、稳定性 | 高；单任务速度通常不变 | 中高：跨进程取消和序列化 | 高 |
| 7 | 进度与结果解耦：NDJSON 只发送进度和 resultId，结果按变量/时间块压缩下载或外部存储；前端改用 TypedArray/IndexedDB，图表先降采样。 |
内存、网络、UI | 大结果时高 | 中：需要版本化协议 | 中高 |
| 8 | 主动定时清理任务表，限制任务数/结果字节；成功交付后只保留摘要或引用。将无界进度队列改为“最新进度槽 + 不可丢终态槽”。 | 稳定性 | 中到高 | 低中 | 低中 |
| 9 | 只在当前步跨越下一采样点或需要状态事件检测时构造 dense output；记录并优化事件重启。大量周期 UD00 事件采用惰性调度。 | 单算例、事件密集模型 | 中 | 低到中 | 低到中 |
| 10 | CSV 在浏览器直接生成或按 resultId 服务端流式生成，避免全量 series 重新上传与 StringIO 全量复制。 |
内存、网络 | 中 | 低 | 低中 |
| 11 | 用共享 Schema/OpenAPI 生成前后端事件类型，修正 complete/completed；停滞依据服务端活动计数/已接受步时间戳并允许按模型调节。 |
可靠性、减少误杀重算 | 中 | 低 | 低中 |
| 12 | 长期评估支持稀疏残差/Jacobian 的 DAE 求解器，将外层 ODE 与内层代数 least-squares 统一成状态—代数系统。 | 复杂大模型 | 潜在很高 | 很高：架构与验证成本大 | 很高 |
13.2 推荐落地顺序
在改算法前先增加低侵入观测，但不把“加指标”误列为直接加速：
- 记录每个闭合 pass 的调用数、墙钟时间、代数
nfev与是否命中快路径； - 记录热物性调用数/迭代数、stream 迭代数；
- 导出外层
nfev/njev/nlu、接受/拒绝步、事件与重启次数； - 记录状态/结果数组字节数、最终 JSON 字节、任务队列深度和进程 RSS；
- 用小、中、大三类基准网络定位排名 1～5 的真实占比；
- 先实施第 1、4、8、9 项的可回滚改造，再决定第 2、3、5 项的深度；
- 服务并发需求明确后并行推进第 6、7 项。
每项算法改动都应继续验证质量/能量守恒、正反流、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/代数求解主链。
- 气动、机械和信号的专用闭合顺序。
- 压力流量显式因果化快路径与
least_squares回退。 - 自适应积分、输出采样、信号断点、机械端挡、协作取消和部分结果。
- NDJSON 长响应、心跳、取消端点、异常恢复轮询和任务状态表。
- 单 Uvicorn worker、每任务 daemon 线程、完整终态结果驻留与浏览器多副本行为。
约定
- 内核定位为半显式 ODE/代数 MVP，而非任意 DAE。
- XML/组件运行参数使用 SI 基准值。
- 采样上限、超时、心跳和任务名义保留时长。
- 组件参数在单次运行中静态；时间变化通过信号源等模型表达。
推断及必须实测
- 哪一类闭合 pass、热物性或 Jacobian 估计占主要墙钟时间。
- 单个任务实际占用几个核心、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:86-968 |
PressureFlowSolver.solve() |
| 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() |
| 前端流式协议 | frontend/src/App.tsx |
streamSystemSimulation()、取消/轮询 |
| 启动方式 | start-backend.bat:17-21 |
Uvicorn 单 worker 命令 |
| 主路径回归测试 | tests/test_generic_system_xml_simulation.py、tests/test_core_solver.py |
通用仿真、事件、取消 |