pastas

使用 Pastas 建立地下水响应模型

使用 Pastas 建模井水位对时变应力的响应。拟合得到的响应参数是有效模型参数；仅凭这些参数无法确定导水系数、含水层几何形态或水力连通性。若要解答有依据的空间流动问题，请使用 FloPy/MODFLOW。

此入口面向 Pastas 2.0。其组件构造函数接受所属模型并自行注册；旧式 add_stressmodel 模式正逐步淘汰。为保证工作可复现，请使用经过测试的依赖基线。在已检查的环境中，2.0 软件包还需要 tqdm，用于其导入的求解器计时器。

准备数据并预留评估日期

记录水头单位和垂直基准、井/筛管、时间戳约定、应力单位，以及蒸发量是实测值还是估算的参考潜在蒸发量。相对水头或水深序列为负，并不意味着其表示高于海平面的高程。保留原始基准。

对于日尺度补给模型，请将水头一致换算为 m，将降水和参考蒸发量一致换算为 mm/day。保留每日累积标签；若不了解观测支持范围，不要臆造时区或移动日期。缺失降雨不等于零。水头缺口应保持未填补；检查应力数据是否覆盖模型预热期，并记录任何应力填补所依据的校准来源。Pastas 默认可能会填补并延长应力数据，因此应在构建模型前明确这些选择。

拟合前固定校准日期和留出日期。仅使用校准期水头和应力构建模型，包括从数据推导的初始值。未来观测到的应力可用于历史回算；未来观测到的水头不得用于调整拟合参数或模拟状态。此外，预测还需要指定未来应力情景和不确定性。

校准经过检查的补给模型

此函数要求输入为唯一且按日期排序的日尺度 Series，非负应力数据完整并覆盖请求的观测预热期，且至少包含 3 个有限的校准水头值。随附的辅助程序会强制执行这些输入检查。

import pastas as ps

def fit_recharge(calibration_head, calibration_precip, calibration_evap,
                 start, end, warmup_days):
    model = ps.Model(calibration_head, name='well')
    settings = {'freq': 'D', 'sample_up': 'bfill', 'sample_down': 'mean',
                'fill_nan': None, 'fill_before': None, 'fill_after': None}
    ps.RechargeModel(model, calibration_precip, calibration_evap,
                     rfunc=ps.Gamma(), recharge=ps.rch.Linear(), name='recharge',
                     settings=(settings.copy(), settings.copy()))
    ps.ArNoiseModel(model)
    model.solve(tmin=start, tmax=end, warmup=warmup_days, report=False)
    if not model.solver.result.success:
        raise RuntimeError('Calibration did not converge')
    return model

校准辅助程序会验证 CSV 结构、日期、显式校准时间窗口和应力覆盖范围，然后通过 model.to_file(...) 保存 .pas。绘图为可选项。该程序假设单位已完成标准化；不会根据列名猜测单位，也不会填补缺失应力数据。

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

请相对于此已安装技能目录解析脚本路径。校准文件并不代表已完成留出评估：请使用固定评估期报告基线、独立观测日期指标和残差。

贡献、诊断与持久化

model.get_contributions() 返回一个 Series 列表，可能拆分为降水和蒸发分量。遍历该列表，或调用 model.get_contribution('recharge') 请求一个合并后的贡献；不要对它调用 .items()。检查模拟总量时，要加上拟合常数。块响应表示持续有限时长的应力块，而不是瞬时脉冲。应相应使用 model.get_step_response 和 model.get_block_response。

使用 model.to_file('model.pas') 保存，使用 ps.io.load('model.pas') 重新加载，并在相同日期窗口上比较模拟结果。经检查的 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 补给量进行回算：质量控制、仅用校准期数据拟合、三个基线、残差 ACF、连续留出期模拟，以及保存／加载回读。辅助函数的每日补给路径和抽水响应符号也通过了真实库检查。这并不能验证所有非线性、多井或不确定性配置。

Pastas 2.0 官方版本，带版本的模型 API 源码，检查日期：2026-09-15。