README.md

---
license: apache-2.0
language:
- en
tags:
- OneScience
- Earth Science
- Probabilistic Downscaling
- Consistency Model
frameworks: PyTorch
---

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

# Model Introduction

ScaleAdaptiveCM uses a single-step consistency model to transform coarse Earth-system-model precipitation into high-resolution probabilistic fields for fast, scale-adaptive climate downscaling and uncertainty analysis.

Paper: Fast, scale-adaptive and uncertainty-aware downscaling of Earth system model fields with generative machine learning  
https://doi.org/10.1038/s42256-025-00980-5

# Model Description

The method was proposed by teams from the Potsdam Institute for Climate Impact Research, the Technical University of Munich, Nanjing University of Information Science and Technology, and collaborating institutions. The paper trains on daily ERA5 precipitation and evaluates POEM, GFDL-ESM4, and SpeedyWeather.jl simulations. The model generates `240×384` precipitation ensembles from `60×96` coarse fields.

# Use Cases

| Use Case | Description |
| :---: | :--- |
| Probabilistic precipitation downscaling | Convert coarse ESM precipitation fields into high-resolution ensembles. |
| Scale-adaptive generation | Control retained large scales and generated small-scale structure through noise scale. |
| Local engineering validation | Validate consistency training, single-step sampling, ensemble mean, and spread. |
| ModelScope/OneCode execution | Validate structured data, training, inference, downscaling metrics, and visualization in ModelScope or OneCode environments. |
| Multi-GPU training | Validate distributed training and the checkpoint workflow 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/ScaleAdaptiveCM --local-dir ./ScaleAdaptiveCM
cd ScaleAdaptiveCM
```

### 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 uses daily ERA5 precipitation from 1940-2018 on a `240×384` target grid and ESM fields on a `60×96` native grid. This repository generates structured precipitation with ITCZ, weather-system, and intermittent small-scale patterns while preserving the fourfold downscaling relation. Synthetic data validate engineering only and do not represent ERA5 or ESM distributions, training 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
```

The default reduces samples, network width, and epochs without reducing the `60×96 → 240×384` protocol. Training artifacts are saved to `result/checkpoints/scale_adaptive_cm.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 adds scale-guided noise to the coarse field and generates a high-resolution ensemble in one network evaluation per member. Results are saved to `result/output/predictions.npz`.

### Evaluation and Visualization

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

Evaluation computes MAE, RMSE, large-scale correlation, power-spectrum error, and ensemble CRPS 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 ScaleAdaptiveCM specifications.

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