README.md

---
license: apache-2.0
language:
- en
tags:
- OneScience
- Earth Science
- Precipitation Nowcasting
- Spatiotemporal Sequence Prediction
frameworks: PyTorch
---

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

# Model Introduction

ConvLSTM is a convolutional recurrent neural network for spatiotemporal sequence prediction. It replaces the input-to-state and state-to-state transformations of LSTM with spatial convolutions, thereby modeling local spatial correlations while preserving long-term temporal dependencies.

Paper: Convolutional LSTM Network: A Machine Learning Approach for Precipitation Nowcasting  
https://papers.nips.cc/paper_files/paper/2015/hash/07563a3fe3bbe7e3ba84431ad9d055af-Abstract.html

# Model Description

ConvLSTM was proposed by researchers at the Hong Kong University of Science and Technology and the Hong Kong Observatory. The model is trained and evaluated using the 97 days with the highest rainfall in the 2011 to 2013 Hong Kong weather radar data, as well as synthetic Moving-MNIST sequences. The model is suitable for precipitation nowcasting, video prediction, and general spatiotemporal sequence prediction tasks.

# Use Cases

| Scenario | Description |
| :---: | :--- |
| Precipitation nowcasting | Predict the next 15 time steps from 5 historical radar maps. |
| Spatiotemporal sequence modeling | Jointly learn spatial and temporal correlations with a convolutional gating structure. |
| Multi-step image prediction | Continuously generate future images through an Encoder-Forecaster structure. |
| Local workflow validation | Use synthetic radar sequences to check training, inference, evaluation, visualization, and checkpoint workflows. |
| Multi-GPU training | Launch distributed data-parallel training with `torchrun`. |

# Usage Instructions

## 1. OneCode

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

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

## 2. Download and Installation

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

### Environment Dependencies

**Hardware Requirements**

- A GPU or DCU is recommended.
- A CPU can be used for connectivity validation with the default small-sample configuration.
- DCU users must install DTK in advance. DTK 25.04.2 or later, or the OneScience-recommended version matching the current cluster, is recommended.

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

This repository uses a small number of synthetic samples to validate the engineering workflow. The synthetic data contains 20 consecutive single-channel `float32` radar echo images of `100×100` pixels at 6-minute intervals. The first 5 frames are used as input and the following 15 frames as prediction targets. This data is only used to validate ConvLSTM's spatiotemporal encoding, 15-step prediction, training, inference, and evaluation workflows; it does not represent the official radar data distribution or training scale.

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

### Training

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

For multi-GPU training, use:

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

The default configuration retains two Encoder layers, two Forecaster layers, `3×3` convolutions, channel-wise peephole connections, and the full prediction length; it only reduces the number of samples, hidden channels, and training epochs.

```text
result/checkpoints/convlstm.pt
result/training/metrics.json
```

### Training Weights

This repository does not include synthetic or trained weights, and the paper does not provide a directly downloadable original Theano pretrained checkpoint.

### Inference

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

Inference loads the training checkpoint and generates 15 future radar echo predictions from 5 historical radar maps. The inference results contain the input sequence, ground-truth target, predicted sequence, and corresponding lead-time information in minutes.

```text
result/output/predictions.npz
```

### Evaluation and Visualization

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

Following the paper, the evaluation converts radar echoes to rainfall rates using the Z-R relationship and computes Rainfall-MSE, CSI, FAR, POD, and Correlation. The results include per-step metrics for all 15 forecast lead times and overall summary metrics, and generate comparison plots of targets, predictions, and absolute errors for selected lead times. Results on synthetic data are only for validating the engineering workflow and do not represent metrics on the paper's actual radar data.

```text
result/evaluation/metrics.json
result/evaluation/comparison.png
```

# Official OneScience 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

This repository is an independent engineering reproduction of the publicly available specifications in the ConvLSTM paper.

Use of the code and data in this repository remains subject to the licenses and terms of use of their respective projects.