Earth2Studio 确定性预报技能

本技能指导用户通过earth2studio.run.deterministic构建确定性（单一成员）天气预报推断脚本。

前提条件

已安装带有支持CUDA的GPU的Earth2Studio
Python 3.10+，可访问模型权重和数据的网络

实时文档参考

在推荐组件之前，请获取相关文档以验证当前API：

组件	URL
预测模型	https://nvidia.github.io/earth2studio/modules/models_px.html
数据源（分析）	https://nvidia.github.io/earth2studio/modules/datasources_analysis.html
数据源（预报）	https://nvidia.github.io/earth2studio/modules/datasources_forecast.html
IO后端	https://nvidia.github.io/earth2studio/modules/io.html
`run.deterministic`	https://github.com/NVIDIA/earth2studio/blob/main/earth2studio/run.py

工作流程

1. 收集需求（跳过已经提供的部分）

时间范围（小时/天/周）
关注的变量（如2米温度、风、位势高度等）
区域（全球或特定区域，如美国本土CONUS）
可用的GPU/VRAM

2. 选择模型

获取预测模型页面。根据时间范围、区域、VRAM进行筛选。注意模型的：

输入变量（input_coords["variable"]）
时间步长（output_coords["lead_time"]）

3. 选择数据源

数据源必须提供所有模型输入变量。通过earth2studio/lexicon/<source>.py中的词典进行验证。常见搭配：全球模型 → GFS/ARCO/IFS；区域模型 → HRRR。

4. 选择IO后端

默认：ZarrBackend。对于传统工具使用NetCDF4Backend，对于内存/小型运行使用XarrayBackend。

5. 计算nsteps

nsteps = forecast_hours / model_step_hours

示例：5天预报，步长6小时 → nsteps = 120 / 6 = 20

6. 决定：output_coords过滤

过滤变量（output_coords）当用户请求特定变量（例如“2米温度和风”）时——减少输出大小
保存所有变量（省略output_coords）当用户说“所有变量”或未指定时——保留完整模型输出

7. 生成脚本

from collections import OrderedDict
import numpy as np
import torch
from earth2studio.models.px import <ModelClass>
from earth2studio.data import <DataSourceClass>
from earth2studio.io import <IOBackendClass>
from earth2studio.run import deterministic

model = <ModelClass>.load_model(<ModelClass>.load_default_package())
data = <DataSourceClass>()
io = <IOBackendClass>("<output_path>")

# Include output_coords ONLY if user requested specific variables
output_coords = OrderedDict({"variable": np.array(["t2m", "u10m"])})

io = deterministic(
    time=["YYYY-MM-DDTHH:MM:SS"],
    nsteps=<N>,
    prognostic=model,
    data=data,
    io=io,
    output_coords=output_coords,  # omit if saving all variables
    device=torch.device("cuda"),
)

8. 手动循环替代方案

当用户明确要求手动实现（不使用earth2studio.run.deterministic）时，请按顺序执行以下清单：

fetch_data - 获取初始条件：x, coords = fetch_data(data, time, model.input_coords, device)
设置total_coords - 为时间和lead_time维度构建坐标数组
io.add_array - 在循环前使用total_coords初始化IO后端
create_iterator - 创建预测迭代器：model_iter = model.create_iterator(x, coords)
循环遍历nsteps - for step, (x, coords) in enumerate(model_iter): if step >= nsteps: break
map_coords - 如果需要，过滤输出变量：x_out, coords_out = map_coords(x, coords, output_coords)
split_coords - 为IO写入做准备：x_out, coords_out = split_coords(x_out, coords_out)
io.write - 将每一步写入后端

9. 解释后续步骤

如何更改预报时间或运行多次初始化
如何读取输出（xr.open_zarr(...)）
指向用于后处理的诊断工作流程

所有权

拥有： 模型选择、数据源兼容性、IO后端选择、nsteps计算、生成earth2studio.run.deterministic脚本。

不拥有： 集合预报工作流程、诊断、仅数据获取、安装、模型训练。

故障排除

常见错误和解决方案见references/troubleshooting.md。

提醒

推荐模型或数据源之前始终获取实时文档 - API在不同版本间会变化
验证词典兼容性 - 模型输入变量必须存在于数据源的VOCAB中
使用load_default_package() - 这是加载模型权重的标准模式
时间格式为ISO 8601 - 对time参数使用"YYYY-MM-DDTHH:MM:SS"格式
风速需要两个分量 - 如果用户要求“风速”，应包括u10m和v10m
nsteps是整数除法 - nsteps = total_hours // model_step_hours
ZarrBackend是默认 - 仅当用户有特定需求时才建议其他后端
需要GPU - 所有预测模型都需要CUDA；不支持CPU推理