# 数值结构与失败语义

库按依赖分层：state/conserved 为状态与方程；mesh/flux/reconstruction/step 构成有限体积推进；riemann/sampling 提供非真空参照；simulation 负责快照、预算、重试与边界账本；diagnostics/initial/convergence 支持验证；checkpoint/csv/remap/observations/experiment 为完整工作流。

`Gas`、`Mesh`、`SolverConfig`、`Simulation` 经构造校验，字段对消费者只读。原始/守恒结果结构公开，但所有计算入口复核其物理性。`GasError::Invalid` 表示不满足输入约束，`Numerical` 表示浮点范围、迭代、步进或资源预算失败。

HLL 取左右声速和速度包络，Rusanov 取最大特征速度。primitive 限制线性重构用相邻单元的 minmod/MC 斜率，边界单元保持常数。SSPRK2 是两次 Euler 评估后取凸组合；两阶段都检查 CFL 和正压力。`run_until` 每步以剩余时间和 CFL 给出候选步长，物理/CFL 拒绝时减半并计入重试预算。不会静默截断至目标前或把失败结果当成功返回。

守恒账本累计每次接受步的左右边界通量差乘 dt；RK2 对两个阶段的边界贡献取相同权重。残差为当前积分减初始积分再减累计边界变化，单位与守恒量相同。诊断总和采用补偿加法。它能检查数值更新是否与边界通量一致，不能独立证明解足够精确。

精确非真空 Riemann 先检查真空条件，再扩张正压力上界，二分求星区压力；残差超过容差或 200 次迭代仍不收敛则报错。`sample` 区分初始态、激波后态、稀疏扇、接触两侧。接触处取左星区；`at` 在 t=0 时取初始左右态。

误差 `l1` 为单元绝对误差的平均值，`l2` 为均方根，`linf` 为最大值，未乘域长度。Sod/Lax 报告中心点参照下的误差；平滑熵波使用解析单元平均值，观察阶为相邻 L1 比与网格宽度比的对数之比，零误差返回 None。

重映射使用从左端起算的计算坐标进行重叠积分，降低大偏移坐标相减的损失。`integrate` 接收实际坐标，区间端点仍受 Double 可表示精度限制。探针给出所属单元的分片常量值，不作高阶空间插值。

公开来源不可信时，应用仍须设置自己的输入字节、分配、总计算时间和并发限制。库内有限上限用于防止无界结构，不是网络服务的沙箱。