OneScience-Group/ConvLSTM

ConvLSTM

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

2. Download and Installation

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

# 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

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

python scripts/fake_data.py

Training

python scripts/train.py

For multi-GPU training, use:

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.

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

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.

result/output/predictions.npz

Evaluation and Visualization

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.

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.