README.md

---
license: apache-2.0
language:
- en
tags:
- OneScience
- Earth Science
- Radar Nowcasting
- Diffusion Model
- 3D Radar
- Probabilistic Forecasting
- Severe Convection
frameworks: PyTorch
---

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

# Model Introduction

EchoCast-3D generates five future probabilistic radar volumes from three historical 3D scans for convective evolution, missing-data reconstruction, and short-range nowcasting. It jointly learns spatiotemporal evolution and vertical storm structure during diffusion and can form complete ensemble forecasts when observations contain gaps.

Paper: Generative machine learning for skilful 3D radar nowcasting  
https://doi.org/10.1038/s41612-026-01407-7

# Model Description

The method was proposed by teams from the Chinese Academy of Sciences, Hohai University, and collaborating institutions. The paper trains and evaluates on four-elevation radar volumes from the China Meteorological Administration. EchoCast-3D encodes multi-elevation wedge blocks as unified tokens and jointly learns echo evolution and gap recovery through MaskDiT diffusion and masked reconstruction. The model supports probabilistic 3D radar nowcasting from the previous 18 minutes to the next 30 minutes.

# Use Cases

| Use Case | Description |
| :---: | :--- |
| 3D radar nowcasting | Predict five future radar volumes from three historical frames. |
| Gap-robust forecasting | Jointly perform 75% token-mask reconstruction and diffusion denoising. |
| Local validation | Validate ensemble forecasts and metrics on real packed-wedge geometry. |
| ModelScope/OneCode execution | Validate data, training, inference, radar metrics, and visualization. |
| Multi-GPU training | Validate distributed training and checkpoint workflows through `torchrun`. |

# Usage Instructions

## 1.OneCode

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

## 2. Download and Installation

```bash
hf download OneScience-Group/EchoCast-3D --local-dir ./EchoCast-3D
cd EchoCast-3D
```

### 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 synthetic dataset for engineering validation, including eight consecutive six-minute volumes, four elevations, three history frames, five targets, and the real packed-wedge dimensions. Four elevations retain `366/366/363/363` azimuths and `180/180/120/120` range bins while reducing samples, model scale, diffusion steps, and epochs; `3×3` patching yields 24,320 tokens whereas the paper reports 24,400. These data validate MaskDiT, gap reconstruction, diffusion training, ensemble inference, and evaluation only and do not represent official CMA radar distributions and scale.

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

### Training

For single-GPU training, use:

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

Training combines score matching on unmasked tokens with `0.1`-weighted reconstruction over the 75% randomly masked tokens. The default reduces hidden dimension, DiT depth, heads, diffusion steps, samples, and epochs while preserving radar geometry and the three-to-five-frame protocol. Training artifacts are saved to:

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

### Trained Weights

The paper does not provide a confirmed public pretrained-weight URL, and no weights are bundled under `weight/`.

### Inference

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

Inference loads the local checkpoint and conditions on the previous three radar volumes and their validity masks. Starting from 3D Gaussian noise, the model iteratively denoises five future volumes and uses different random seeds to form an ensemble. Outputs retain lead, elevation, azimuth, and range ordering. Inference results are saved to:

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

### Evaluation and Visualization

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

Evaluation computes ensemble CRPS, MAE, and RMSE and CSI, FAR, and POD at 20, 30, and 40 dBZ thresholds. It also saves ensemble coverage ratios for five leads and four elevations and generates observed-versus-ensemble-mean composite reflectivity comparisons. Synthetic-data results validate engineering only and do not represent formal paper performance. Evaluation results are saved to:

```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 public EchoCast-3D specifications, with code licensed under the Apache License 2.0.

The original paper is licensed under CC BY-NC-ND 4.0; the paper, official model weights, and China Meteorological Administration radar data remain subject to the licenses and terms of their respective projects.