README.md

---
license: apache-2.0
language:
- en
- zh
tags:
- OneScience
- Earth Science
- precipitation nowcasting
- weather radar
- RYDL
frameworks: PyTorch
datasets:
- RYDL
---

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

# Model Introduction

Paper: RainNet v1.0: a convolutional neural network for radar-based precipitation nowcasting  
https://doi.org/10.5194/gmd-13-2631-2020

RainNet is designed for radar-based precipitation nowcasting. It takes four consecutive radar precipitation fields at 5 min intervals as input, predicts the precipitation field for the next 5 min, and can be extended recursively to a lead time of approximately 60 min.

# Model Description

RainNet was proposed by the authors of the original paper and trained on the German Weather Service (DWD) RY radar precipitation product. It performs radar nowcasting as a regression task for continuous precipitation intensity.

The current implementation takes four consecutive historical frames as input and uses the immediately following time step, `i+4`, as the target. Precipitation values are transformed with `x -> log(x + 0.01)` before entering the model. Each raw `900x900` radar field is expanded to `928x928` with reflect/mirror padding and cropped back to `900x900` after prediction. RainNet has approximately 31.4M parameters; the validated parameter count is 31,380,613. The decoder uses nearest-neighbor upsampling.

# Applicable Scenarios

| Scenario | Description |
| :---: | :--- |
| Continuous precipitation regression training | Train RainNet with consecutive radar precipitation fields. |
| Radar precipitation nowcasting | Predict future precipitation from consecutive historical radar fields. |
| Local pipeline validation | Use Fake Data to validate data loading, training, inference, evaluation, and visualization. |
| ModelScope / OneCode execution | Run the project as a standalone model package. |
| Multi-GPU training | Launch distributed training processes with `torchrun`. |

# Usage

Run the following commands from the root of the model package. The default smoke-test configuration preserves the full `900x900` spatial grid and uses 1 epoch with at most 1 batch per stage to validate the engineering pipeline.

## 1. OneCode

Use the OneCode online environment for intelligent one-click AI4S programming:

[Try intelligent one-click AI4S programming](https://web-2069360198568017922-iaaj.ksai.scnet.cn:58043/home)

## 2. Manual Installation and Usage

Python 3.11, PyTorch, NumPy, h5py, PyYAML, and Matplotlib are required. After installing the environment, run Fake Data generation, training, inference, and evaluation in sequence.

### Hardware Requirements

The model has approximately 31.4M parameters. Training with full `928x928` internal tensors requires substantial accelerator memory, so a CUDA/HIP-compatible GPU or DCU with sufficient memory is recommended. CPU execution is supported but substantially slower.

### Download the Model Package

```bash
modelscope download --model OneScience/RainNet --local_dir ./RainNet
cd RainNet
```

### Install the Runtime Environment

#### DCU Environment

```bash
# Activate DTK and CONDA first
conda create -n onescience311 python=3.11 -y
conda activate onescience311

pip install onescience[earth-dcu] \
  -i http://mirrors.onescience.ai:3141/pypi/simple/ \
  --trusted-host mirrors.onescience.ai
```

#### GPU Environment

```bash
# 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

pip install onescience[earth-gpu] \
  -i http://mirrors.onescience.ai:3141/pypi/simple/ \
  --trusted-host mirrors.onescience.ai
```

### Training Data

#### Real Data

The real dataset is RYDL, available from https://doi.org/10.5281/zenodo.3629951. It uses HDF5, with a raw frame size of `900x900`, a spatial resolution of 1 km, and a temporal resolution of 5 min. Each top-level HDF5 timestamp key corresponds to one two-dimensional precipitation field. This repository does not include or automatically download the complete real dataset.

#### Fake Data

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

This command generates `data/rainnet_fake.hdf5`. Fake Data preserves the real `900x900` frame size, simulates the RYDL HDF5 timestamp key-value organization, maintains a continuous sequence at 5 min intervals, and only reduces the number of time frames.

Fake Data is only used to validate the engineering pipeline. It does not represent real precipitation forecasting performance and does not reproduce the accuracy reported in the paper.

### Training

This reproduction uses Log-Cosh Loss and the Adam optimizer, with a default learning rate of `1e-4`.

#### Single-Accelerator Training

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

#### Distributed Training

```bash
torchrun \
  --nproc_per_node=8 \
  --nnodes=1 \
  --rdzv_id=1000 \
  --rdzv_backend=c10d \
  --max_restarts=0 \
  --master_addr="localhost" \
  --master_port=29500 \
  scripts/train.py
```

### Training Weights

This repository plans to provide weights trained on DWD RY/RYDL radar precipitation data under `weight/`. The weight files will be uploaded in a future update.

### Inference

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

Inference results are saved under `result/output/`. The script loads a training checkpoint, performs one-step inference, and runs a 12-step autoregressive rollout while updating the four-frame sliding window.

### Evaluation and Visualization

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

The script computes MAE, CSI, FSS, and the Persistence baseline from actual inference outputs, and generates forecast comparisons, a training-loss curve, and metric plots.

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

- The OneScience RainNet model package is licensed under Apache License 2.0.
- The original RainNet source code is licensed under the MIT License.
- The RainNet paper was published by Copernicus Publications under the Creative Commons Attribution 4.0 License (CC BY 4.0).
- Attribution to the original paper and authors must be retained when using or redistributing this package.

```bibtex
@article{ayzel2020rainnet,
  title={RainNet v1.0: a convolutional neural network for radar-based precipitation nowcasting},
  author={Ayzel, Georgy and Scheffer, Tobias and Heistermann, Maik},
  journal={Geoscientific Model Development},
  volume={13},
  pages={2631--2644},
  year={2020},
  doi={10.5194/gmd-13-2631-2020}
}
```