0 Fork 0

Files

T

ljz 1aac220084 优化 Jacobian 确定性复用并补充性能剖析与平台依赖文档

在单次 Jacobian 构建内按完整输入精确复用储气物性、PH 反算、密度和管路求根结果，保持原有求值副作用、差分政策与失败回退。八路模型求解 CPU 中位数减少 19.27%，循环和不循环的完整原始采样均与恢复基线一致。

增加独立的跨平台时间剖析工具，记录互斥阶段耗时、Newton/LU 统计、矩阵复用与内核复用，保存 UD00 两种工况的调查报告和机器可读汇总。

补充 Windows/Linux 运行、测试、原生编译和剖析所需依赖文档及索引，不修改依赖清单、版本锁或安装环境。

验证：8 项新增专项回归通过；2270 次完整 Jacobian 核对零差异；16 次剖析配对及预热运行保持完整数值一致。既有固定样本哈希失败和 Linux 实机验收限制见报告。

2026-09-16 13:39:53 +08:00

7.5 KiB

Raw Blame History

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
后端运行包	FastAPI、lxml、Pydantic 2、Uvicorn standard	同左，包含平台相应的传递依赖	requirements.txt
前端开发/构建	Node.js 20.19+ 或 22.12+、npm	同左	package.json、package-lock.json
模型原生编译	GCC/MinGW，支持 C11 和当前 GCC 编译参数	GCC、标准 C 开发环境	原生构建器
BDF 及共用原生程序	SUNDIALS 7.4.0 开发头文件、导入库和 DLL	SUNDIALS 7.4.0 开发头文件及静态库	原生后端说明
后端数值回归	上述工具链，加 NumPy	同左	requirements-test.txt，NumPy 范围 `>=1.26,<3`
求解器时间剖析	上述原生工具链与 Python 标准库	同左	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。.python-version 记录参考补丁版本 3.12.3。支持范围、参考版本和实际安装环境是不同概念；历史性能结果对应当时的实际环境，不能由文档更新推断环境已升级。

Windows

在已有 Python 3.12 环境中，运行包使用范围文件配合直接依赖约束：

.\.venv-win\Scripts\python.exe -m pip install -r requirements.txt -c constraints/python312-direct.txt
.\.venv-win\Scripts\python.exe -m pip check

运行后端测试时改用：

.\.venv-win\Scripts\python.exe -m pip install -r requirements-test.txt -c constraints/python312-direct.txt

Windows 目前没有完整的传递依赖 wheel 哈希锁。直接依赖约束不等于完整锁，不能拿 Linux wheel 锁安装到 Windows。

Linux

发布和参考 CI 的运行依赖使用现有完整锁：

.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 和哈希校验。

测试依赖在运行环境安装完成后单独安装：

.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 前，系统应已提供：

Bash、GCC 和标准 C 头文件/链接工具。
CMake 及所选生成器对应的构建工具，默认通常为 GNU Make。
curl、tar/gzip、sha256sum，以及 HTTPS 下载所需的系统 CA 证书。

脚本下载并校验固定的 SUNDIALS 7.4.0 源码，构建 Release 静态库，默认安装到项目 .venv/native/sundials-7.4.0。脚本本身不安装系统软件包。

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 来制造该阶段的独立数字。

在已有环境中核对本轮新增功能：

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 工况，不安装依赖。详细计数与计时口径见时间剖析说明。

实际验证状态

本轮 Jacobian 优化与时间剖析已在 Windows 的现有环境实测，包含 UD00 循环/不循环以及完整数值保持核对；Linux 有对应构建、计时和测试路径，尚未完成本轮真实 Linux 运行验收。依赖文档覆盖两平台，不代表两平台验收均已完成。

7.5 KiB Raw Blame History Unescape Escape