天气数据（Weather data providers）
PCSE 已内置多种"即插即用"的天气数据源，分为三大类：
本地文件类
CABOWeatherDataProvider：读取纯文本 CABO 格式。
ExcelWeatherDataProvider：同上结构，但数据放在 Excel 文件，编辑更方便。
CSVWeatherDataProvider：极简 CSV 格式（日期+变量列）。
在线 API 类
OpenMeteoWeatherDataProvider：免费 REST API，历史数据用 ERA5，预报源含 ECMWF 等；只需给出经纬度即可拉取时间序列。
全球数据库类
NASAPowerWeatherDataProvider：自动下载 NASA POWER 农业气象数据（0.25°×0.25°），同样按经纬度请求即可。
class pcse.input.CABOWeatherDataProvider(fname, fpath=None, ETmodel='PM', distance=1)
以CABO 天气文件读取参数为例子
fname：CABO 天气文件的基础名（不含扩展名）。
fpath：文件所在路径，可绝对或相对；默认当前目录。
ETmodel：计算参考蒸散量所用方法，"PM"（Penman-Monteith，默认）或 "P"（Penman 1948）。
distance：气象变量缺失时允许的最大插值跨度，默认 1 天。
class pcse.input.ExcelWeatherDataProvider(xls_fname,missing_snow_depth=None, force_reload=False)
从 Excel 文件（仅 .xlsx）读取气象数据参数为例子
xls_fname：要读取的 Excel 文件名（含 .xlsx）。
missing_snow_depth：缺失 SNOW_DEPTH 时用什么值填充，默认 None。
force_reload：是否绕过缓存，强制重新读取 .xlsx 并生成新缓存文件；缓存写在 $HOME/.pcse/meteo_cache。
class pcse.input.CSVWeatherDataProvider(csv_fname, delimiter=',', dateformat='%Y%m%d', ETmodel='PM', force_reload=False)
从 CSV 文件读取气象数据参数为例子
csv_fname：待读取的 CSV 文件名。
delimiter：列分隔符，默认逗号 ,。
dateformat：日期列格式，默认 '%Y%m%d'（如 20230615）。
ETmodel：计算参考蒸散量方法，"PM"（Penman-Monteith，默认）或 "P"（Penman 1948）。
force_reload：忽略缓存，强制重新读取 CSV 并写入新缓存。
作物文件
class pcse.input.YAMLCropDataProvider(model=pcse.models.Wofost72_PP, fpath=None, repository=None, force_reload=False)
读取作物参数。
model：指定 PCSE 模型类（默认 pcse.models.Wofost72_PP）。提供器会根据模型版本自动选择对应的参数分支。
fpath：本地存放 YAML 参数文件的目录完整路径。
repository：YAML 文件在线仓库的 原始内容 URL（如 https://raw.githubusercontent.com/...）。
force_reload：是否忽略缓存，强制重新加载全部参数（默认 False）。
可同时载入多作物参数，不同于传统"单作物"提供器；运行时只需切换活动作物即可，特别适合轮作模拟。
默认from pcse.input import YAMLCropDataProvider
p = YAMLCropDataProvider()
print§
For a specific model and version just pass the model onto the CropDataProvider:
要求from pcse.models import Wofost81_PP
p = YAMLCropDataProvider(Wofost81_PP)
print§
读取本地 YAML 文件夹
p = YAMLCropDataProvider(fpath=r"D:\UserData\WOFOST_crop_parameters")
站点文件
Class pcse.input.WOFOST72SiteDataProvider(**kwargs) 版本7.2
classpcse.input.WOFOST73SiteDataProvider(**kwargs) 版本7.3
classpcse.input.WOFOST81SiteDataProvider_Classic(**kwargs) 版本8.1
classpcse.input.WOFOST81SiteDataProvider_SNOMIN(**kwargs)版本8.1SNOMIN
版本区别：
7.2 只需 WAV；7.3 需 WAV+CO2；8.1 Classic 需 WAV+NAVAILI；8.1 SNOMIN 需 WAV+NH4I+NO3I。
PCSE 为 WOFOST 不同版本（7.2 → 7.3 → 8.1 Classic → 8.1 SNOMIN）提供了 4 个"站点数据提供器（SiteDataProvider）
| 参数 | 含义 | 7.2 | 7.3 | 8.1 Classic | 8.1 SNOMIN |
|---|---|---|---|---|---|
| IFUNRN | 暴雨非入渗比例是否随雨强变化 0/1 | ●0 | ●0 | ●0 | ●0 |
| NOTINF | 最大非入渗比例 [0--1] | ●0 | ●0 | ●0 | ●0 |
| SSMAX | 地表最大积水量 [cm] | ● | ● | ● | ● |
| SSI | 地表初始积水量 [cm] | ● | ● | ● | ● |
| WAV | 土壤剖面初始含水量 [cm] | √ | √ | √ | √ |
| SMLIM | 初始根区最大湿度 [0--1] | ●0.4 | ●0.4 | ●0.4 | ●0.4 |
| CO2 | 大气 CO₂ 浓度 [ppm] | --- | √ | ●360 | ●≈400 |
| BG_N_SUPPLY | 大气氮沉降 [kg ha⁻¹ d⁻¹] | --- | --- | ●0 | --- |
| NSOILBASE | 土壤基础氮量 [kg ha⁻¹] | --- | --- | ● | --- |
| NSOILBASE_FR | 土壤氮矿化日比例 [d⁻¹] | --- | --- | ● | --- |
| NAVAILI | 初始有效氮量 [kg ha⁻¹] | --- | --- | √ | --- |
| A0SOM | 初始有机质年龄 [yr] | --- | --- | --- | ●24 |
| CNRatioBio | 微生物 C:N 比 [kg C kg⁻¹ N] | --- | --- | --- | ●9 |
| FASDIS | 同化/异化速率比 [-] | --- | --- | --- | ●0.5 |
| KDENIT_REF | 参考反硝化一阶速率 [d⁻¹] | --- | --- | --- | ●0.06 |
| KNIT_REF | 参考硝化一阶速率 [d⁻¹] | --- | --- | --- | ●1.0 |
| KSORP | 吸附系数 [m³ kg⁻¹] | --- | --- | --- | ●0.0005 |
| MRCDIS | 异化-反硝化 Michaelis 常数 [kg C m⁻² d⁻¹] | --- | --- | --- | ●0.001 |
| NH4ConcR | 雨水中 NH₄-N 浓度 [mg L⁻¹] | --- | --- | --- | ●0.91 |
| NO3ConcR | 雨水中 NO₃-N 浓度 [mg L⁻¹] | --- | --- | --- | ●2.1 |
| NH4I | 各层初始 NH₄ [kg ha⁻¹] | --- | --- | --- | √* |
| NO3I | 各层初始 NO₃ [kg ha⁻¹] | --- | --- | --- | √* |
| WFPS_CRIT | 临界充水孔隙度 [m³ m⁻³] | --- | --- | --- | ●0.8 |
农事管理
PCSE 农事管理（AgroManagement）"一段 YAML 定义多个种植季（campaign），每季可配 0-1 套 CropCalendar + 0-N 个 TimedEvent（按日历）+ 0-N 个 StateEvent（按模型状态），AgroManager 按时间顺序把它们串起来驱动播种、施肥、灌溉、收获等动作。"
Class pcse.agromanager.AgroManager(**kwargs)
classpcse.agromanager.CropCalendar(**kwargs)
classpcse.agromanager.TimedEventsDispatcher(**kwargs)
classpcse.agromanager.StateEventsDispatcher(**kwargs)
| 类 | 构造函数独有参数 | 核心职责 | 触发方式 | 返回日期接口 | 校验逻辑 |
|---|---|---|---|---|---|
| AgroManager | agromanagement (YAML 清单) |
总导演：把若干 campaign 按日期串起来，统一发信号 | 每日循环检查当前 campaign → 调对应的 CropCalendar / Timed / State 三类 dispatcher | start_date end_date（自动推算或空段刹车） |
检查 campaign 日期是否重叠、是否缺尾部空段 |
| CropCalendar | crop_name variety_name crop_start_date crop_start_type crop_end_date 或 max_duration crop_end_type |
作物生命周期闹钟：到日子发 crop_start / crop_finish 信号 |
仅看日历日，与模型状态无关 | get_start_date() get_end_date()（ harvest 日或 start+max_duration） |
验证作物周期必须落在本 campaign 窗口内 |
| TimedEventsDispatcher | event_signal events_table（list[dict]，key 为 date） |
日历闹钟：到具体日期就发信号 | 日期匹配即触发 | get_end_date()（本表最晚事件日） |
事件日必须全部落在本 campaign 内 |
| StateEventsDispatcher | event_signal event_state（状态变量名） zero_condition（rising/falling/either） events_table（key 为阈值） |
状态闹钟：模型变量穿零时发信号 | 每步计算 (model_state - threshold) 穿零方向满足条件才触发 |
无（触发日无法提前知道） | 阈值列表须与 zero_condition 方向一致，且阈值在物理合理范围 |