README.md

---
license: apache-2.0
language:
- en
tags:
- OneScience
- Earth Science
- Extreme Precipitation
- Generative Downscaling
frameworks: PyTorch
---

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

# Model Introduction

PrecipExtremes-GAN uses a residual generative adversarial network to map coarse atmospheric fields to high-resolution daily precipitation and assess extrapolation of extreme changes to warmer climates.

Paper: On the Extrapolation of Generative Adversarial Networks for downscaling precipitation extremes in warmer climates  
https://agupubs.onlinelibrary.wiley.com/doi/10.1029/2024GL112492

# Model Description

The method was proposed by teams from New Zealand's National Institute of Water and Atmospheric Research, the University of New South Wales, and collaborating institutions. The paper trains on ACCESS-CM2-driven CCAM simulations and evaluates four independent GCM-driven historical and SSP3-7.0 simulations. The model supports daily precipitation downscaling and extreme-precipitation climate-change analysis over New Zealand.

# Use Cases

| Use Case | Description |
| :---: | :--- |
| Daily precipitation downscaling | Generate high-resolution precipitation from eight coarse atmospheric predictors. |
| Extreme extrapolation | Compare historical and future training for 99.5th-percentile precipitation change. |
| Local engineering validation | Validate deterministic U-Net, residual GAN, and ensemble inference. |
| ModelScope/OneCode execution | Validate structured data, training, inference, extreme-precipitation metrics, and visualization in ModelScope or OneCode environments. |
| 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/PrecipExtremes-GAN --local-dir ./PrecipExtremes-GAN
cd PrecipExtremes-GAN
```

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

The paper predicts approximately 12 km CCAM daily precipitation from eight 1.5-degree U, V, T, and Q fields at 500 and 850 hPa. Since final tensor dimensions are not reported, this repository uses an explicitly documented `24×24 → 96×96` engineering grid. Synthetic data validate engineering only and do not represent CCAM or GCM distributions, scale, or paper performance.

```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 first fits a deterministic U-Net and then trains a residual generator with MSE, adversarial, and intensity losses. The default reduces samples, width, ensemble size, and epochs, writing `result/checkpoints/precip_extremes_gan.pt` and `result/training/metrics.json`.

### Trained Weights

The paper does not provide directly loadable official model weights, and this repository bundles no weights under `weight/`.

### Inference

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

Inference writes deterministic, residual-GAN member, and ensemble-mean outputs to `result/output/predictions.npz`.

### Evaluation and Visualization

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

Evaluation computes daily MAE, 99.5th-percentile error, and future-versus-historical climate-signal error and writes `result/evaluation/metrics.json` and `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 PrecipExtremes-GAN specifications.

Use of this repository's code, official model weights, and data remains subject to the licenses and terms of their respective projects.