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