用途
Pastas 用于地下水时间序列分析与建模，采用传递函数噪声（transfer function noise）模型，描述某口井对随时间变化应力的响应。资料明确指出：拟合得到的响应参数是有效模型参数，其本身并不能确立渗透系数、含水层几何形态或水力连通性；若问题涉及有支撑的空间流动，应使用 FloPy/MODFLOW。
主要能力
- 构建地下水响应模型，将水头序列与降水、蒸发等应力关联。
- 使用 RechargeModel 配合 Gamma 响应函数与线性补给进行补给建模。
- 通过 ArNoiseModel 引入噪声模型。
- 提供 model.get_contributions()、model.get_contribution('recharge')、model.get_step_response、model.get_block_response 等诊断接口。
- 支持模型持久化：model.to_file('model.pas') 保存，ps.io.load('model.pas') 重新加载。
- 提供 ps.stats.acf 用于残差自相关诊断，可指定滞后天数与 bin_method。
使用方式
资料给出一个校准补给模型的示例函数 fit_recharge，其输入要求为唯一、有序的日日期 Series，覆盖所请求观测预热期的完整非负应力，以及至少三个有限校准水头。示例中构造 ps.Model，设置 settings（freq 为 'D'、sample_up 为 'bfill'、sample_down 为 'mean'、fill_nan/fill_before/fill_after 均为 None），添加 RechargeModel 与 ArNoiseModel，再调用 model.solve(tmin, tmax, warmup, report=False)，并检查 model.solver.result.success。
命令行用法示例：
python scripts/groundwater_model.py head_m.csv rain_mm_day.csv evap_mm_day.csv
--calibration-start 2005-01-01 --calibration-end 2013-12-31
--warmup-days 730 --noise --output fitted.pas
脚本路径需相对于已安装的技能目录解析。校准辅助函数会校验 CSV 形状、日期、显式校准窗口与应力覆盖，然后以 model.to_file(...) 保存 .pas；绘图为可选。它假定单位已归一化，不会从列名猜测单位，也不执行缺失应力填补。
数据准备与评估约定
需记录水头单位与垂直基准、井/滤管、时间戳约定、应力单位，以及蒸发是实测还是估算的参考潜在蒸发。负的相对水头或埋深序列并不自动等于海拔高程，应保留原始基准。日补给模型应使用一致换算的水头（m）、降水与参考蒸发（mm/day）。保留日累积标签；在不知观测支撑的情况下不得臆造时区或平移日期。缺失降雨不等于零。水头缺口应保持未填补，检查应力在模型预热期的覆盖情况，并记录任何应力填补及其校准来源。Pastas 默认可能填补和延伸应力，因此应在构造模型前明确这些选择。
校准与留出日期须在拟合前固定。构造模型时仅使用校准水头与应力，包括由数据推导的初始值。未来观测应力可支持后报（hindcast）；未来观测水头不得用于调整拟合参数或模拟状态。预测还需要指定的未来应力情景与不确定性。
诊断与持久化要点
model.get_contributions() 返回 Series 列表，可能拆分为降水与蒸发分量；应迭代该列表，或用 model.get_contribution('recharge') 请求合并贡献，不要对其调用 .items()。检查总模拟时需加上拟合常数。块响应表示有限时长的应力块，而非瞬时脉冲，应分别使用 model.get_step_response 与 model.get_block_response。已检查的 API 中没有 Model.to_json 方法。添加 ps.ArNoiseModel(model) 与仅传入 noise=True 求解器标志是不同的。
当观测存在缺口时，可使用 ps.stats.acf(residuals, lags=[1, 7, 30], bin_method='gaussian')，滞后单位以天指定，并检查配对计数。残差诊断与噪声序列诊断回答不同问题。AIC/BIC 比较要求相同的观测/目标函数，且通用的 EVP>70% 阈值不是验证标准。持续的新息相关性会限制对常规参数标准误的置信度。
适用场景与限制
适用于地下水水位时间序列的响应建模、补给模型校准、残差自相关诊断与模型保存/加载。资料说明该项目的文水地质工作流使用 Pastas 2.0 运行固定的公开 USGS/GSOD 补给后报，包含 QC、仅校准拟合、三个基线、残差 ACF、连续留出模拟与保存/加载回读；辅助函数的日补给路径与抽水响应符号也有真实库检查。但这并不验证所有非线性、多井或不确定性配置。应力配置（抽水/河流输入、非线性补给）与响应解释（参数符号、单位、响应尾部）需要各自的数据与诊断。
版本与依赖
该入口针对 Pastas 2.0。其组件构造器接受所属模型并自行注册；旧的 add_stressmodel 模式正在被淘汰。应使用经过测试的依赖基线以保证可复现。在已检查的环境中，2.0 包还需要 tqdm 以支持其导入的求解器计时器。资料标注的检查日期为 2026-09-15。