README.md

---
datasets:
- OneScience/ERA5
frameworks:
- PyTorch
language:
- en
- zh
license: mit
tags:
- OneScience
- Earth Science
- Weather Forecast
- Global Forecast
- ERA5
- OneForecast
tasks: []
---

<p align="center">
  <strong>
    <span style="font-size: 30px;">OneForecast</span>
  </strong>
</p>

# Model Introduction

OneForecast was developed by the team of Prof. Xiaomeng Huang in the Department of Earth System Science at Tsinghua University, in collaboration with multiple institutions. The paper has been accepted by ICML 2025.

Paper: OneForecast: A Universal Framework for Global and Regional Weather Forecasting

https://arxiv.org/abs/2502.00338

# Model Description

OneForecast is a universal framework for nested global-regional weather forecasting based on graph neural networks (GNNs). Its core goal is to address the challenges of existing AI weather models in balancing low-resolution global forecasts with high-resolution regional forecasts, as well as issues such as over-smoothing in extreme event forecasting.

# Use Cases

| Scenario | Description |
| :---: | :--- |
| Global Weather Forecast Training | Train the single-step OneForecast model using ERA5 HDF5 data. |
| Local Quick Validation | Use synthetic data to verify the data protocol, model construction, training, inference, and result visualization. |
| Multi-GPU Training | Data-parallel training on multiple GPUs/DCUs via PyTorch DDP and `torchrun`. |
| ModelScope / OneCode Execution | Download as a standalone model package, install the OneScience dependencies, and run. |

# Usage Guide

## 1. OneCode Usage

Experience intelligent one-click AI4S programming through the OneCode online environment:

[Click to Experience Intelligent One-Click AI4S Programming](https://web-2069360198568017922-iaaj.ksai.scnet.cn:58043/home)

## 2. Manual Installation and Usage

**Hardware Requirements**

- A GPU or DCU is recommended.
- CPU can be used for import and small-scale connectivity verification; full training and inference will be slow.
- DCU users must install DTK in advance. DTK 25.04.2 or above, or the OneScience recommended version matching your cluster, is recommended.

### Download the Model Package

```bash
hf download OneScience-Group/OneForecast --local-dir ./OneForecast
cd OneForecast
```

### Install the Runtime Environment

**DCU Environment**

```bash
# Please activate DTK and CONDA first
conda create -n onescience311 python=3.11 -y
conda activate onescience311
# uv installation is supported
pip install onescience[earth-dcu] -i http://mirrors.onescience.ai:3141/pypi/simple/  --trusted-host mirrors.onescience.ai
```

**GPU Environment**

```bash
# Please activate CONDA first
conda create -n onescience311 python=3.11 -y libstdcxx-ng=12 libgcc-ng=12 gcc_linux-64=12 gxx_linux-64=12
conda activate onescience311
# uv installation is supported
pip install onescience[earth-gpu] -i http://mirrors.onescience.ai:3141/pypi/simple/  --trusted-host mirrors.onescience.ai
```

### Training Data Introduction

The OneScience community provides ERA5 data for training (due to file size limits, the current repository contains a slice of the full dataset). Users can download it with the command below and confirm that the data path in `conf/config.yaml` is set correctly:

```bash
hf download --repo-type dataset OneScience-Group/ERA5 --local-dir ./data
```

### Generate Synthetic Data

Synthetic data is only used to verify the data protocol and program flow; it does not represent scientific forecast quality:

```bash
python scripts/fake_data.py
```

### Training

Single GPU:

```bash
python scripts/train.py
```

Training starts from random initialization by default and saves the model to `data/checkpoint/model_bak.tar`.

Multi-GPU:

```bash
torchrun --nproc-per-node=4 scripts/train.py
```

### Fine-tuning

Fine-tuning starts from the training checkpoint `data/checkpoint/model_bak.tar` by default and saves the result to `data/checkpoint/model_finetuned.tar`:

```bash
python scripts/finetune.py
```

### Training Weights

This repository provides weights trained on ERA5 reanalysis data in the `weights/` folder. The weight files will be uploaded soon and are expected to be available in the near future.

### Inference

Inference loads the training checkpoint `data/checkpoint/model_bak.tar` by default, uses the test-year data, and writes predictions to `outputs/predictions/`:

```bash
python scripts/inference.py --config conf/config.yaml
```

### Result Visualization

```bash
python scripts/result.py
```

# OneScience Official Information

| Platform | OneScience Main Repository | Skills Repository |
| --- | --- | --- |
| Gitee | https://gitee.com/onescience-ai/onescience | https://gitee.com/onescience-ai/oneskills |
| GitHub | https://github.com/onescience-ai/OneScience | https://github.com/onescience-ai/oneskills |

# Citation & License

- This repository is a reproduction of the original OneForecast paper.