ljz
1aac220084
在单次 Jacobian 构建内按完整输入精确复用储气物性、PH 反算、密度和管路求根结果，保持原有求值副作用、差分政策与失败回退。八路模型求解 CPU 中位数减少 19.27%，循环和不循环的完整原始采样均与恢复基线一致。 增加独立的跨平台时间剖析工具，记录互斥阶段耗时、Newton/LU 统计、矩阵复用与内核复用，保存 UD00 两种工况的调查报告和机器可读汇总。 补充 Windows/Linux 运行、测试、原生编译和剖析所需依赖文档及索引，不修改依赖清单、版本锁或安装环境。 验证：8 项新增专项回归通过；2270 次完整 Jacobian 核对零差异；16 次剖析配对及预热运行保持完整数值一致。既有固定样本哈希失败和 Linux 实机验收限制见报告。
118 lines
7.5 KiB
Markdown
118 lines
7.5 KiB
Markdown
# Windows / Linux 依赖说明
|
||
|
||
文档版本：1.0.0；更新日期：2026-09-16。
|
||
|
||
适用范围：当前原生求解器、Jacobian 确定性复用及时间剖析工具。本次更新依赖文档，不安装环境或升级版本。依赖声明和锁文件仍以仓库既有文件为准。
|
||
|
||
## 依赖分层
|
||
|
||
| 用途 | Windows x64 | Linux x86_64 | 声明或入口 |
|
||
|---|---|---|---|
|
||
| 后端编排 | CPython 3.12，项目环境通常为 `.venv-win` | CPython 3.12，项目环境通常为 `.venv` | [.python-version](../../.python-version) |
|
||
| 后端运行包 | FastAPI、lxml、Pydantic 2、Uvicorn standard | 同左，包含平台相应的传递依赖 | [requirements.txt](../../requirements.txt) |
|
||
| 前端开发/构建 | Node.js 20.19+ 或 22.12+、npm | 同左 | [package.json](../../frontend/package.json)、[package-lock.json](../../frontend/package-lock.json) |
|
||
| 模型原生编译 | GCC/MinGW，支持 C11 和当前 GCC 编译参数 | GCC、标准 C 开发环境 | [原生构建器](../../app/simulation/native_codegen/build.py) |
|
||
| BDF 及共用原生程序 | SUNDIALS 7.4.0 开发头文件、导入库和 DLL | SUNDIALS 7.4.0 开发头文件及静态库 | [原生后端说明](../../native/README.md) |
|
||
| 后端数值回归 | 上述工具链，加 NumPy | 同左 | [requirements-test.txt](../../requirements-test.txt)，NumPy 范围 `>=1.26,<3` |
|
||
| 求解器时间剖析 | 上述原生工具链与 Python 标准库 | 同左 | [profile_native_solver.py](../../tests/manual/profile_native_solver.py) |
|
||
| 浏览器回归 | 前端开发依赖中的 Playwright，以及对应浏览器 | 同左；另需浏览器要求的系统运行库 | 前端 `npm ci` 与 Playwright 浏览器安装 |
|
||
|
||
NumPy 属于测试依赖，不是后端运行依赖。当前原生数值计算不依赖 SciPy；本轮 Jacobian 优化没有引入自动微分库。时间剖析也不需要额外的 Python profiler 包、Linux perf 或开启 SUNDIALS 内部 profiler。
|
||
|
||
## Python 版本与平台安装口径
|
||
|
||
跨平台直接依赖参考版本为 FastAPI 0.141.1、lxml 6.1.1、Pydantic 2.13.4、Uvicorn 0.52.3，来源为 [python312-direct.txt](../../constraints/python312-direct.txt)。`.python-version` 记录参考补丁版本 3.12.3。支持范围、参考版本和实际安装环境是不同概念；历史性能结果对应当时的实际环境，不能由文档更新推断环境已升级。
|
||
|
||
### Windows
|
||
|
||
在已有 Python 3.12 环境中，运行包使用范围文件配合直接依赖约束：
|
||
|
||
```powershell
|
||
.\.venv-win\Scripts\python.exe -m pip install -r requirements.txt -c constraints/python312-direct.txt
|
||
.\.venv-win\Scripts\python.exe -m pip check
|
||
```
|
||
|
||
运行后端测试时改用：
|
||
|
||
```powershell
|
||
.\.venv-win\Scripts\python.exe -m pip install -r requirements-test.txt -c constraints/python312-direct.txt
|
||
```
|
||
|
||
Windows 目前没有完整的传递依赖 wheel 哈希锁。直接依赖约束不等于完整锁，不能拿 Linux wheel 锁安装到 Windows。
|
||
|
||
### Linux
|
||
|
||
发布和参考 CI 的运行依赖使用现有完整锁：
|
||
|
||
```bash
|
||
.venv/bin/python -m pip install -r constraints/python312-linux-x86_64.lock
|
||
.venv/bin/python -m pip check
|
||
```
|
||
|
||
此锁适用于 CPython 3.12、兼容 manylinux_2_28 的 Linux x86_64，锁定传递依赖和 wheel SHA-256。必须作为 `-r` 输入；它启用 binary-only 和哈希校验。
|
||
|
||
测试依赖在运行环境安装完成后单独安装：
|
||
|
||
```bash
|
||
.venv/bin/python -m pip install -r requirements-test.txt -c constraints/python312-direct.txt
|
||
.venv/bin/python -m pip check
|
||
```
|
||
|
||
`requirements-test.txt` 中 NumPy 仅规定范围，不是完整测试环境锁。正式跨版本性能比较还应记录实际 Python/NumPy/工具链版本，不能声称这一步实现了全部测试依赖的精确锁定。
|
||
|
||
## Windows 原生依赖
|
||
|
||
构建器接受 GCC 风格参数，当前不提供 MSVC 构建入口。本机已用 GCC 8.1 验证；这只是实测版本，不是对所有较早/较新 GCC 版本的兼容承诺。现有 Windows CI 使用 conda-forge 的 `sundials=7.4.0` 和 `m2w64-gcc`。
|
||
|
||
`SUNDIALS_ROOT` 指向包含 `include`、`lib`、`bin` 的开发文件根目录。需要以下五个库：
|
||
|
||
| 模块 | Windows 导入库 | 随程序部署的 DLL |
|
||
|---|---|---|
|
||
| CVODE | `lib/sundials_cvode.lib` | `bin/sundials_cvode.dll` |
|
||
| Core | `lib/sundials_core.lib` | `bin/sundials_core.dll` |
|
||
| Serial NVector | `lib/sundials_nvecserial.lib` | `bin/sundials_nvecserial.dll` |
|
||
| Dense Matrix | `lib/sundials_sunmatrixdense.lib` | `bin/sundials_sunmatrixdense.dll` |
|
||
| Dense Linear Solver | `lib/sundials_sunlinsoldense.lib` | `bin/sundials_sunlinsoldense.dll` |
|
||
|
||
还需保留发行包依赖的运行库，例如 `vcruntime140.dll`。构建器会把找到的上述 DLL 及该运行库复制到模型程序旁边。单独安装同名 Python 包不能提供这些 C 开发文件。
|
||
|
||
发现规则：`SIMULATION_NATIVE_CC` 覆盖编译器，否则从 PATH 查找 `gcc`；`SUNDIALS_ROOT` 覆盖库根目录，否则从当前 Python 基础环境的 `Library` 查找。若 Python 与 SUNDIALS 安装在不同环境，需要显式设置覆盖变量；文档不要求固定盘符或机器路径。
|
||
|
||
## Linux 原生依赖
|
||
|
||
执行 [setup-native-linux.sh](../../bat/setup-native-linux.sh) 前，系统应已提供：
|
||
|
||
- Bash、GCC 和标准 C 头文件/链接工具。
|
||
- CMake 及所选生成器对应的构建工具，默认通常为 GNU Make。
|
||
- curl、tar/gzip、sha256sum，以及 HTTPS 下载所需的系统 CA 证书。
|
||
|
||
脚本下载并校验固定的 SUNDIALS 7.4.0 源码，构建 Release 静态库，默认安装到项目 `.venv/native/sundials-7.4.0`。脚本本身不安装系统软件包。
|
||
|
||
```bash
|
||
bash bat/setup-native-linux.sh
|
||
```
|
||
|
||
需要 `libsundials_cvode.a`、`libsundials_core.a`、`libsundials_nvecserial.a`、`libsundials_sunmatrixdense.a`、`libsundials_sunlinsoldense.a`。构建器在依赖根目录的 `lib`、`lib64`、`lib/x86_64-linux-gnu` 下探测这组静态库。
|
||
|
||
如果设置 `SYSTEM_SIMULATION_NATIVE_ENV` 改变安装位置，应相应将 `SUNDIALS_ROOT` 指向该位置下的 `sundials-7.4.0`。默认情况下构建器先查当前 Python 环境的 `native/sundials-7.4.0`，再查 `/usr/local` 和 `/usr`。Linux 的 `start-all.sh` 另外要求 Bash 4.3+。
|
||
|
||
## 本轮新增功能的依赖边界
|
||
|
||
- Jacobian 复用使用现有 C11 标准库和上述五个 SUNDIALS 库，没有新增链接库。
|
||
- 时间剖析使用 SUNDIALS 7.4 公共接口，包括 Newton 操作表、非线性失败计数与步失败计数；需保留完整开发头文件。
|
||
- 诊断副本使用 GCC 的 cleanup 属性，Windows/Linux 都沿用项目 GCC 工具链。Windows 使用 QueryPerformanceCounter，Linux 使用 CLOCK_MONOTONIC。
|
||
- 当前 SUNDIALS 内部 profiler 关闭时，误差估计没有独立计时；报告按不可分离的内部控制组记录，不要求重新构建 SUNDIALS 来制造该阶段的独立数字。
|
||
|
||
在已有环境中核对本轮新增功能：
|
||
|
||
```text
|
||
python -m unittest tests.test_native_jacobian_reuse tests.test_native_jacobian_reuse_runtime tests.test_solver_profile -v
|
||
python tests/manual/profile_native_solver.py --output test/my-solver-profile --run
|
||
```
|
||
|
||
`python` 替换为对应平台的项目环境解释器。第二条命令会编译独立诊断副本并运行两种 UD00 工况，不安装依赖。详细计数与计时口径见 [时间剖析说明](native-solver-profiling.md)。
|
||
|
||
## 实际验证状态
|
||
|
||
本轮 Jacobian 优化与时间剖析已在 Windows 的现有环境实测，包含 UD00 循环/不循环以及完整数值保持核对；Linux 有对应构建、计时和测试路径，尚未完成本轮真实 Linux 运行验收。依赖文档覆盖两平台，不代表两平台验收均已完成。
|