README.md

---
license: apache-2.0
language:
- en
tags:
- OneScience
- Earth Science
- Climate Extremes
- Spatial Reconstruction
frameworks: PyTorch
---

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

# Model Introduction

CRAI-ClimateExtremes reconstructs missing regions from incomplete climate-extreme index fields and validity masks for historical-extreme analysis and sparse-observation reconstruction.

Paper: Artificial intelligence reveals past climate extremes by reconstructing historical records  
https://doi.org/10.1038/s41467-024-53464-2

# Model Description

The method was proposed by research teams from the German Climate Computing Center, the Met Office, the University of Hamburg, and collaborating institutions. The paper uses 45 historical simulations from eight CMIP6 models, HadEX-CAM observations, and reanalysis products including ERA5. The model reconstructs monthly TX90p, TN90p, TX10p, and TN10p temperature-extreme indices.

# Use Cases

| Use Case | Description |
| :---: | :--- |
| Climate-extreme reconstruction | Reconstruct four monthly temperature-extreme indices from incomplete fields and validity masks. |
| Irregular-gap handling | Validate partial convolution, mask propagation, and missing-region loss. |
| Local engineering validation | Validate the end-to-end workflow with structured synthetic data on the complete `144×192` grid. |
| ModelScope/OneCode execution | Validate structured data, training, inference, climate-reconstruction metrics, and visualization in ModelScope or OneCode environments. |
| Multi-GPU training | Validate distributed training and the checkpoint workflow through `torchrun`. |

# Usage Instructions

## 1.OneCode

Experience intelligent, one-click AI4S programming through the OneCode online environment:

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

## 2. Download and Installation

```bash
hf download OneScience-Group/CRAI-ClimateExtremes --local-dir ./CRAI-ClimateExtremes
cd CRAI-ClimateExtremes
```

### 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 monthly CMIP6 extreme indices from 1901-2014 and applies HadEX-CAM missing-data masks to construct training samples. Inputs contain an index field and validity mask `[B,2,144,192]`, while targets are complete `[B,1,144,192]` index fields. This repository uses a small structured synthetic dataset for engineering validation only and does not represent the real CMIP6 or HadEX-CAM 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 configuration reduces samples, network width, epochs, and ensemble members without reducing the `144×192` grid or four-index protocol. Formal experiments require real CMIP6 and HadEX-CAM data and paper-scale training, with artifacts saved to:

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

### Trained Weights

The paper does not provide directly loadable official model weights, and this repository bundles no weights under `weight/`. The locally trained checkpoint is saved to `result/checkpoints/crai_climateextremes.pt` and must not be represented as an official pretrained weight.

### Inference

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

Inference loads the unified ensemble checkpoint, reconstructs missing extreme indices, and saves the member mean and spread. Complete numerical outputs are saved to:

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

### Evaluation and Visualization

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

Evaluation computes missing-region RMSE, Spearman correlation, bias, and neighborhood spatial correlation and generates a target, input, and reconstruction comparison. Synthetic-data results validate engineering only and do not represent paper performance; outputs 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 CRAI-ClimateExtremes specifications.

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