SystemSimulationApp/docs/other/牛顿管流求根与四路网页验证-2026-09-11.md

# 牛顿管流求根、AME 输入复核与网页验证（2026-09-11）

目录整理补充：`tests/data` 的 JSON/XML 仅保留浏览器可导入的四路、八路 corrected JSON；参考曲线、旧工程和后端 XML 已迁到 `tests/baselines` / `tests/fixtures`，本文当前路径同步更新，文件内容及来源哈希不变。详见 [数据目录说明](../../tests/data/README.md)。

本轮在 `5d5a2e1843bc10cf7764c77cc2c1182c21a68df5` 的物性复用实现上，补全局部管流牛顿求根的区间保护和二分回退；按用户确认，将网页/API 与 Python CLI 默认相对误差限改为 `1e-8`。四路输入先按 AME 图纸核对，再做实际原生计算和浏览器验证。环境依赖、生成程序和运行数据均留在 Git 忽略目录，没有提交或推送 Git。

## 实现与适用范围

每条阻力支路在本次 RHS 所给定的两端压力、上游温度和物性下，局部求解一个标量方程：

\[
F(Re)=Re^2 f(Re,\varepsilon/D)-K=0,\qquad
Re=\frac{4|\dot m|}{\pi D\mu}.
\]

`K` 由当前可压缩流动系数、上游状态和管径、管长确定。流向由压差决定；摩擦系数仍使用现有的层流、过渡和湍流连续混合公式。PNL0001/2/3 的容腔质量、能量状态由系统积分器推进，机械运动及接触事件也在系统层处理。局部求根没有把全系统变成一个单独的牛顿方程组。

本次保护包括：

- 检查输入有限性及有效夹根区间；扩展区间和迭代均有 128 次上限。
- 牛顿导数无效、候选点越界，或上一步牛顿未使残差至少减半时，回到保留区间的中点。
- 对实际返回值重新检查归一化方程残差 `≤1e-9`，并检查流量修正量满足绝对 `1e-13 kg/s` 或相对 `1e-10` 的要求。
- 处理小根下溢、大流量溢出、相邻浮点数造成的区间停滞；未满足标准就报告失败，不把最后一次迭代当作成功。

PNL00R 原有直接层流分支继续保留。物性状态复用、物理方程、整体雅各比构造和积分器类型没有因局部保护而更换。夹根连续性、有效输入和浮点可表示范围仍是条件；这套方法不保证任意系统必然完成，也不能消除接触刚性或所有积分误差。

## 先核对模型，再比较数值

交付输入为 [四路 JSON](../../tests/data/test-mql-4-corrected.json)、[同步 XML](../../tests/fixtures/amesim/test-mql-4-corrected.xml) 和 [八路修正版 JSON](../../tests/data/test-mql-8-corrected.json)。完整差异分别见 [四路复核](test-mql-4模型复核与输入修正-2026-09-11.md) 与 [八路修正](test-mql-8模型对照与修正-2026-09-11.md)。

四路 AME 为 `tests/data/test_mql_4.ame`。其 `.cir` 包含 63 个组件和 18 条建模管线，展开为 81 个公开元件、90 条连接、582 项公开参数、64 个动态状态。修正遗留管阻 `amesim_pnl00r_4.rr` 为 `1e-5`，并将 25 条涉及等价端口编号/阻力方向的连线与 AME 编号逐项对齐。

用户指出 `pnnode4` 看起来不同后，又直接解析了 `.cir` 的端口变量和连接记录，使用原始唯一别名逐个匹配，独立于原有同构映射。四个 P4NODE2 的真实压力、温度参考口均为 `port_2`，下列连接原本就是一致的：

| AME 节点别名 | JSON 节点 | 参考口在两侧模型的连接对象 |
|---|---|---|
| pnnode4_16 | amesim_p4node2_1 | pneumatic_69 / amesim_pnl0001_13 的 port_2 |
| pnnode4_17 | amesim_p4node2_2 | pneumatic_68 / amesim_pnl0001_14 的 port_2 |
| pnnode4_18 | amesim_p4node2_3 | pneumatic_66 / amesim_pnl0001_15 的 port_2 |
| pnnode4_19 | amesim_p4node2_4 | pneumatic_65 / amesim_pnl0001_16 的 port_2 |

发现的实际显示问题是：三个节点沿用旧工程旋转方向，且前端 P4NODE2 的 3、4 号端口锚点与 AME 几何定义互换。修复图标锚点及修正版工程的旋转/连线路由，物理连接编号和参数保持审计结果。另一次独立参数解析核对了表压加 `101300 Pa`、毫米/面积/容积/刚度/阻尼单位转换和状态初值，未发现新数值差异。公开适配项与 AME 直接字段在审计中单列。

`native-python-reference.json` 是 50 网络冻结数值基准；`test-mql-4-amesim-reference.json` 是 72 曲线、57 时刻的结果基准，两者都不是工程文件，未改写。AME 四路归档仍包含旧八路编译/结果缓存（132 状态）；本轮没有可调用的 Amesim 安装，不能把该缓存当作四路运行。本次比较使用仓库中已有的官方重编译四路参考，原 AME SHA256 与当前文件相符。它不能证明全部时间点、全部输出或接触力都与 Amesim 一致。

## 相同精度下的求解速度

使用同一四路输入、同一物性复用实现、同一 SUNDIALS 7.4.0/GCC 13.3.0 环境。BDF，0～10 s，输出步长 0.01 s，最大步长 `1e30`，各算法均使用 `rtol=1e-8`。每个版本预热一次、正式运行三次，交错运行次序；下表为中位数。

| 局部管流算法 | 纯求解时间 | 进程全程 |
|---|---:|---:|
| 旧固定点迭代（16/64 次上限、半步松弛） | 1.3309 s | 2.3479 s |
| 前次提交的牛顿实现 | 0.9171 s | 1.9009 s |
| 本次补全保护的牛顿＋二分回退 | 0.9097 s | 1.8962 s |

本次相对固定点版本纯求解耗时减少 **31.6%**，约为其 **1.46 倍速度**。相对已经采用牛顿的前次提交，约 0.8% 差异不足以认定另有显著加速；本轮新增保护的主要收益是失败处理和收敛条件完整性。前次牛顿与本次版本的全部采样序列、最终输出和最终状态逐值完全相同。

固定点版本是在明确基线提交的 C 源码中，仅替换回原来的局部半步松弛迭代，不是运行旧版整个应用。因此这张表隔离了管流算法差异，不混入物性复用收益。基准脚本检查替换位置，并保存实际源码、输入快照、哈希、构建键和原始结果。

此前 `rtol=1e-7` 的同机基准：固定点 1.8731 s、前次牛顿 1.3149 s、本次 1.3074 s。收紧精度后，本模型本次纯求解反而降为 0.9097 s，RHS 次数从 32029 降至 21499；自适应积分路径改变，不能据此推断所有系统收紧误差限都会加速。

## Amesim 曲线验收

网页使用的默认误差限由 `1e-7` 改为 `1e-8`，绝对误差限继续按状态类型生成。原误差门槛不放宽。默认 `1e-7` 在确切端口编号对齐后最大温差为 `0.0168374 K`，超过 `0.015 K` 门槛；收紧后为 `0.00882331 K`。

| 物理量 | 最大绝对误差 | 既有门槛 |
|---|---:|---:|
| 压力 | 199.671 Pa | 250 Pa |
| 温度 | 0.00882331 K | 0.015 K |
| 位移 | 0.807942 μm | 2 μm |
| 速度 | 2.73964 μm/s | 10 μm/s |
| 质量流量 | 0.00707919 g/s | 0.03 g/s |

72 条曲线在 57 个保存的 Amesim 时刻全部通过。四路运行到 10 s，输出 1003 点（含额外事件点），全量数值有限；闭合气路总质量最大漂移 `2.4425e-14 kg`。误差用原始 native/网页导出数据线性插值到参考时刻计算，没有平滑数据或删去不利比较点。

等价端口重排改变了浮点加法次序，从而影响自适应积分轨迹。旧/新端口布置在 10 个相同状态上的 RHS 探测，最大缩放差约 `3.95e-15`；新保护与前次牛顿的整条结果也相同。因此收紧系统精度处理的是全系统积分敏感性，不能归因于局部二分保护本身。

既有 LSTP00A 碰撞事件力峰仍约 `1.50e11 N`，不在这 72 曲线参考范围内。局部求根和本次 `rtol` 调整没有解决该已知问题；原始结果仍保留这些峰值。详见 [此前接口力报告](test-mql-4网页仿真与LSTP00A接口力对比-2026-09-11.md)。

## 最终真实浏览器验证

在本次独立服务 `http://127.0.0.1:8011` 运行正式 Vite 构建，Playwright 驱动 Chromium 151.0.7922.34，未模拟 API 或注入预制仿真结果。使用图标修正后的交付 JSON（SHA256 `542494eed8e235cb36eae5f80a0776b812e547d9215fa370949b0882834ebc8b`）。预热一次、正式运行三次：

| 指标 | 三次正式运行中位数 |
|---|---:|
| C 内部纯求解 | 0.9249 s |
| 原生进程全程 | 1.8465 s |
| 点击运行至 HTTP 流结束 | 2.7666 s |
| 点击运行至结果可查看 | 3.5504 s |

“结果可查看”计时包含实际响应、浏览器结果处理、IndexedDB 保存完成，以及切换到结果页并出现导出控件；没有把它称为纯计算时间。各次实际诊断均为 `rtol=1e-8`、10 s 完成、21499 次 RHS、4970 个接受步、243 个拒绝步、1003 个采样点。

验证了 JSON 导入、真实仿真、图形选择和曲线绘制、结果文件下载、CSV 下载、刷新恢复，以及将下载的结果文件重新导入并显示温度曲线。无 `pageerror`。刷新前后完整结果逐值相等；网页原始结果与独立原生基准的全部曲线和最终输出逐值相同；CSV 的 883 列、1003 行逐单元与网页原始结果一致。结果参考比较也直接针对最终网页导出的 `.simresult` 重做，全部通过。

证据为 `test/solver-newton-20260911/browser-mql4-final-rtol1e8/` 中的输入快照、4 次 `.simresult`、`result.csv`、`restored.simresult`、`summary.json`、`native-equality.json`、`csv-equality.json`、`temperature-view-proof.json` 和页面截图。`result.png` 为首次选择的质量曲线；`result-temperature.png` 为精确选择温度后的截图。网页显示检查中发现脚本的宽泛 K 文本匹配也会命中 kg，已将可复现脚本改为精确匹配单位 K；该选择问题不影响任何原始数值或计时。

## 八路修正版的完成性检查

`test-mql-8-corrected.json` 对齐 157 个元件、178 条连接、1092 个公开参数。修正公共机械质量的 4 项参数（质量 90000→100 kg、限位 -0.72/0→-1/1 m、stoptype 1→4）；修改 62 条边的端口，其中 7 个 P4NODE2 的参考口来源原先确实接错，其余包含共享容腔/汇总支路编号对齐。最大积分步长改为 AME 保存的 `1e30`，8 个 P4 显示方向也与 AME 对齐。原 JSON 保留为审计来源，新的实际运行使用 corrected 文件。

同一修正后执行 XML 和同一内核，在旧 `rtol=1e-7` 下 120 s 超时，推进至 5.144858167 s。按用户确认的新全局 `rtol=1e-8`，单次原生运行完整到 10 s：纯求解 5.9071 s，74265 次 RHS，6974 个接受步、454 个拒绝步，1002 个返回采样，全部有限；56 个气体质量状态的总质量最大漂移 `1.15463e-14 kg`。两次精度不同且只做单次完成性检查，不将其时间比值当作管流优化加速比。

这证明修正版在当前默认设置下可以完整运行，不等同于八路全部曲线已经与 Amesim 一致。本轮八路没有重跑 Amesim 或制作曲线参考。原始数据位于 `test/solver-newton-20260911/mql8/native-run-rtol1e8/`，旧超时记录仍在同级 `native-run/`。输入 JSON SHA256 为 `670977bef67e62d9c66e8af497bada208bd72a7301be45128d185d47282cf288`。

## 回归检查

- 9 个相关后端模块共 **38 项测试全部通过**，无跳过：局部求根、管路物理及四路 Amesim 门槛、物性复用、管流缓存、原生代码生成/打包/API、依赖顺序、50 网络目录基准、原生唯一后端及预热。
- 正式前端 TypeScript/Vite 构建通过。**2 项真实 DOM 几何测试通过**：用 AME `COMP_PORT/PORT_POS` 原始坐标验证旋转后的四个实际 Handle，并验证镜像后粗线仍指向 `port_2`；既有 PN3/P4 图形测试同时通过。
- 将原生程序复制到新目录，清空 `PATH/PYTHONPATH` 并去除 `LD_LIBRARY_PATH`，初始化得到 64 个状态，独立 BDF 0～10 s 运行成功。二进制哈希与打包清单一致。

日志分别为 `final-backend-tests.log`、`frontend-final-build.log`、P4 几何测试证据及 `standalone-package-verification.json`。求根单元测试含独立摩擦公式与二分参考、过渡区邻接浮点数、坏导数注入、无夹根/无可接受根及极端流量尺度，不以运行速度作为正确性断言。

## 环境与复现

Python 包使用现有 `.venv`。新增原生依赖放在 `.venv/native/sundials-7.4.0/`，浏览器缺失共享库放在 `.venv/native/browser-libs/`；没有安装到系统目录。`.venv/`、`app/data/`、`test/` 均已由现有 Git 规则忽略。只交付可读的环境安装脚本 `bat/setup-native-linux.sh`，不交付环境二进制。Linux 原生构建和预热已补齐，保留 Windows 路径和 DLL 打包分支。

```sh
# 无需 Amesim 应用的输入核查
.venv/bin/python tests/model_audit/audit_mql4_model.py --check

# 三版本真实原生基准，输出必须选新目录
.venv/bin/python tests/manual/benchmark_native_pipe_solver.py \
  tests/data/test-mql-4-corrected.json --output-dir test/new-pipe-benchmark --runs 3

# 结果比较；绘图使用已有系统 Python 的 NumPy/Matplotlib
python3.12 tests/manual/compare_native_amesim.py \
  test/solver-newton-20260911/benchmark-mql4-rtol1e8/guarded-newton/run-1/result.json \
  --output-dir test/new-amesim-comparison --plot
```

运行证据根目录为 `test/solver-newton-20260911/`。`benchmark-mql4-rtol1e8/summary.json` 包含公平计时、实际精度和哈希；`comparison-mql4-rtol1e8/` 包含逐曲线 CSV/JSON 及 SVG/PNG 对照图；`temperature-diagnostics/` 保留选择新默认精度的诊断。全部原始结果与可执行程序保留在本机忽略目录，未加入 Git。

## 八路真实网页补验

通过本次 `127.0.0.1:8011` 正式网页，直接导入最终 `test-mql-8-corrected.json`，以全局 `rtol=1e-8` 完整运行到10 s。曲线显示、CSV和结果文件下载、刷新后恢复均成功，无浏览器脚本异常。网页原始曲线和最终输出与独立原生八路运行逐值相同；CSV的1785列、1002行逐单元与原始数据相同。最后一轮为功能补验，不计入四路速度基准。

完整证据在 `test/solver-newton-20260911/browser-mql8-final/`：`summary.json`、`verification.json`、输入快照、原始/恢复后的`.simresult`、CSV和网页截图。初轮自动化曾因写死四路独有组件ID而在选择曲线时失败，应用求解已完成且无pageerror；脚本改为从当前工程选择真实存在的PNL0002后，上述流程全部通过。

## 验证快照与并行工作

本轮数值基准保留实际 C 源码、构建清单、程序与输入快照；网页证据记录了具体输入 SHA256 和实际结果。收尾检查时，工作区出现了并行修改的 `App.tsx`、`SimulationResultsView.tsx`、边线路由、压力单位和相关测试文件。本轮没有覆盖这些改动，也不将此前38项后端测试和网页构建结论扩大为后续并行改动的验证。当前任务核心文件哈希另存于 `test/solver-newton-20260911/final-task-source-hashes.json`。本轮实际执行环境为Linux，Windows构建分支保留，但本轮未在Windows重新运行。