Earth2Studio 确定性预测技能

指导用户使用 earth2studio.run.deterministic 构建确定性（单成员）天气预报推理脚本。

前置条件

• 已安装 Earth2Studio 并配备支持 CUDA 的 GPU
• Python 3.10+，网络访问以获取模型权重和数据

在线文档参考

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

工作流

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

• 时间范围（小时/天/周）
• 关注的变量（t2m、风、位势高度等）
• 区域（全球或特定区域如 CONUS）
• 可用的 GPU/VRAM

2. 选择模型

获取预报模型页面。按时间范围、区域、VRAM 过滤。注意模型的：

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

3. 选择数据源

数据源必须提供所有模型输入变量。通过 earth2studio/lexicon/.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）当用户请求特定变量时（例如"t2m 和风"）——减少输出大小
• 保存所有变量（省略 output_coords）当用户说"所有变量"或未指定时——保留完整的模型输出

7. 生成脚本

from collections import OrderedDict
import numpy as np
import torch
from earth2studio.models.px import 
from earth2studio.data import 
from earth2studio.io import 
from earth2studio.run import deterministic

model = .load_model(.load_default_package())
data = ()
io = ("")

# 仅当用户请求了特定变量时才包含 output_coords
output_coords = OrderedDict({"variable": np.array(["t2m", "u10m"])})

io = deterministic(
    time=["YYYY-MM-DDTHH:MM:SS"],
    nsteps=,
    prognostic=model,
    data=data,
    io=io,
    output_coords=output_coords,  # 如果保存所有变量则省略
    device=torch.device("cuda"),
)

8. 手动循环替代方案

当用户明确要求手动实现（不使用 earth2studio.run.deterministic）时，按顺序遵循此检查清单：

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

9. 解释后续步骤

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

所有权

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

不负责： 集合工作流、诊断、纯数据获取、安装、模型训练。

故障排除

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

提醒

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