# Jacobian 构建内的确定性结果复用

日期：2026-09-15。

## 目的与边界

一次 Jacobian 构建会反复计算基准状态和分组扰动状态。多数扰动只影响局部输入；其余部分的昂贵计算可以复用。当前实现保留原有结构着色、差分增量、canonical 基准、矩阵装配及 Dense LU，只复用经过审查的确定性内核结果。

普通 RHS、接受步物性检查、摩擦事件及采样输出继续使用完整求值路径。本功能不依赖“按用途裁剪”实现，不删除任何原有输出或导数的有限性检查。

## 生命周期

1. 生成器为有分组收益且使用相关内核的模型生成 `ModelJacobianWorkspace` 和 `model_eval_jacobian_reuse`。
2. CVODE 每次请求 Jacobian 时，`model_jacobian_begin` 清空工作区。
3. 同一条 canonical 路径重算基准。此时记录确定性结果；该次求值完成后关闭记录。
4. 分组扰动查询基准结果。输入原始浮点位完全一致才复用；改变的输入重新计算，不覆盖基准条目。
5. 下次 Jacobian 请求重新开始。事件、后续 Newton 迭代和其他仿真运行不会沿用旧基准。

工作区在 C 工作进程内部通过堆内存分配，随运行释放。分配失败时继续采用未缓存的 canonical 着色差分，不把可选优化变成求解失败。

## 可复用的计算

| 计算 | 完整输入键 | 复用内容 | 保留的原有行为 |
|---|---|---|---|
| 储气物性 | 内核函数、质量、热状态、实际容积、全部介质参数 | `NativeGas` 全部字段 | 仅用于 property cache 为 NULL 的 canonical 内核 |
| 压力—焓温度反算 | 压力、焓、全部介质参数 | 温度 | 先查询当前求值的 PH 缓存；仍执行温度观察及本次缓存填充 |
| 密度 | 压力、温度、全部介质参数 | 密度 | 仍进行物性观察、字段有效性判断和本次字段填充 |
| 管路标量求根 | K、相对粗糙度、流量换算系数 | 原方程的收敛根 | 方程、容差、流向和失败判定不变 |

键使用完整浮点位，区分正负零。介质使用参数值而非对象地址。所有数值均来自原始公式或原始求根器，不使用量化、近似相等、邻近状态插值或结果钳制来提高命中率。

这也是运行时对“是否受扰动影响”的判定：机械位置引起的容积变化、耦合储气状态投影以及流向变化，都先计算实际物理输入，再查询完整键。复用不依赖实例名称、支路编号、固定流向或预设拓扑。

## 为什么不能直接共享原有物性缓存

原有 `NativePropertyCache` 的 PT/PH 条目和填充顺序会影响浮点舍入选择。直接跨扰动共享整个缓存，可能改变同一函数的实际数值路径，差分又会放大这类差异。

新机制仅在原路径本来需要执行纯函数时替代该函数的返回值。本次求值自己的缓存、观察、条件分支和错误检查仍按原顺序执行。例如 PH 已在当前求值缓存中命中时，直接使用原来那条命中路径；不会用跨扰动记忆覆盖它。

## 容量与恢复

- 储气条目按生成的物性调用分配，每个调用保留一份基准；非基准输入不驱逐它。
- 标量缓存固定为 1024 个槽。冲突时比较完整键，不把哈希相同视为输入相同。
- 每次查找至多探测 32 个槽，避免大型模型或表满时扫描整张表。放不下或找不到时执行原计算。
- 只记录成功的储气结果和有限标量结果。非有限标量不进入缓存。
- 分组扰动失败后使用未缓存的完整逐列差分。取消或超时不会触发额外重试。
- `--verify-jacobian` 使用未缓存的 canonical 完整差分核对每个矩阵元素。发现差异后使用参考矩阵，并为后续请求关闭着色/复用路径。

## 新模型接入

使用已有储气和气动计算函数的模型自动参与复用，不需要新增用户参数或维护第二份方程。结构分析不能证明分组安全时，原有差分回退继续生效。

新增底层函数默认按原方法执行。要让它参与复用，需要一次性说明完整输入、确定性、输出和副作用边界；新增介质参数也必须纳入完整键。不能仅凭函数名称或某个算例中数值未变就判为可复用。

## 解析 Jacobian 与自动微分的评估

本轮先实现可与原差分逐位对照的复用。当前物理内核包含限位/摩擦切换、`fmax/fmin` 分支、PH 反算和带区间保护的管流求根。若进一步使用解析或自动微分，需要明确切换点的导数政策，并对隐式方程求导；直接对迭代程序逐条求导不等于取得收敛物理解的导数。这些工作不包含在本轮实现中。

## 诊断与验证

构建清单的 `jacobianStructure.reuse` 描述启用条件、容量、范围和核对策略。结果的 `jacobianReuse` 分别记录 gas、ph、density、pipe 的实际计算与复用次数，范围是优化后的基准/分组探针，不包含独立参考差分。

RHS、Jacobian、步数等原有计数含义不变。复用减少的是一次 RHS 内部的昂贵计算，不应表现为虚减 RHS 次数。

主要测试：`tests.test_native_jacobian_reuse`、`tests.test_native_jacobian_reuse_runtime`，并结合原有物性、管路、生成器、守恒、事件、告警、存储及 Jacobian 测试。

前后比较工具：`tests/manual/benchmark_native_jacobian_reuse.py`。正式计时须在编译及重型验证结束后串行执行；带 `--verify-jacobian` 的运行只用于正确性核对。