README.md

---
frameworks: PyTorch
language:
- en
license: apache-2.0
tags:
- OneScience
- Earth Science
- Weather Forecast
- Global Weather Forecast
- ERA5
- Neural ODE
tasks: []
datasets:
- OneScience/ERA5
---
<p align="center">
  <strong>
    <span style="font-size: 30px;">ClimODE</span>
  </strong>
</p>

# Model Introduction

ClimODE is a weather forecasting model proposed in 2024 by researchers from Aalto University and collaborating institutions.

Paper: ClimODE: Climate and Weather Forecasting with Physics-informed Neural ODEs

https://arxiv.org/abs/2404.10024

# Model Description

ClimODE is a physics-informed neural ordinary differential equation model for global, monthly-scale, and regional climate and weather forecasting. It represents atmospheric evolution as a continuous-time dynamical system and incorporates a transport-based physical inductive bias into the neural ODE.

# Use Cases

| Scenario | Description |
| :---: | :--- |
| Global weather forecasting | Train or evaluate ClimODE on ERA5 data following this project's five-variable protocol. |
| Local quick validation | Use synthetic ERA5 HDF5 data to check data loading, training, inference, evaluation, and visualization. |
| ModelScope / OneCode execution | Download the standalone model package, install dependencies, and run the scripts directly. |
| Multi-GPU training | Launch PyTorch DistributedDataParallel with `torchrun`. |

# 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**

- Training and inference require a GPU or DCU recognized by PyTorch. CPU can be used to generate synthetic data and inspect configuration, but cannot run the current training and inference scripts.
- Multi-GPU training uses the NCCL backend. Ensure that the device driver, communication libraries, and PyTorch version are compatible.
- 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/ClimODE --local-dir ./ClimODE
cd ClimODE
```

### 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 an ERA5 data slice for training. Download it and confirm that the paths in `conf/config.yaml` point to the downloaded data:

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

ClimODE reads the five variables `z`, `t`, `t2m`, `u10`, and `v10`, regridding the source `721x1440` fields to the model's `32x64` grid. The source variable mapping is defined in `conf/config.yaml`.

### Generate Synthetic Data

When real ERA5 data is unavailable, generate a full-resolution synthetic fixture for pipeline validation:

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

Synthetic data does not represent ERA5 and cannot reproduce the paper's metrics.

### Training

Single GPU:

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

Multi-GPU:

```bash
torchrun --nproc_per_node=8 scripts/train.py
```

The default checkpoint is saved to `data/checkpoints/model_bak.pth`.

### Fine-tuning

To fine-tune from an existing checkpoint, pass an explicit checkpoint and mode:

```bash
python scripts/train.py --mode finetune --checkpoint data/checkpoints/model_bak.pth
```

An official pretrained checkpoint can be selected explicitly with `--use-pretrained --pretrained-checkpoint <path>`.

### Training Weights

This repository provides a `weight/` directory for ClimODE checkpoints. The weight files will be uploaded soon and are expected to be available in the near future.

### Inference

Inference reads `data/checkpoints/model_bak.pth` by default. If it is unavailable, pass `--checkpoint` explicitly:

```bash
python scripts/inference.py
```

Predictions, uncertainty estimates, and targets are written to `result/output/`.

### Evaluation and Visualization

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

The script computes latitude-weighted RMSE, ACC, and CRPS, and writes per-variable figures to `result/output/figures/`.

# Official OneScience Resources

| 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 and License

- This repository is a OneScience adaptation of the ClimODE paper and is not the official Aalto-QuML release.