README.md

---
license: apache-2.0
language:
- en
tags:
- OneScience
- Earth Science
- Weather Postprocessing
- Probabilistic Forecasting
frameworks: PyTorch
---

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

# Model Introduction

IMPROVER-AIFS corrects systematic biases and improves the reliability of artificial-intelligence weather forecasts. It converts deterministic AIFS forecasts into spatially processed and statistically calibrated deterministic and probabilistic products and can blend them with conventional numerical weather predictions for near-surface weather postprocessing and operational product generation.

Paper: Statistical Postprocessing Yields Accurate Probabilistic Forecasts from Artificial Intelligence Weather Models  
https://doi.org/10.1175/AIES-D-25-0037.1

# Model Description

The method reproduced by IMPROVER-AIFS was proposed by a research team at the Australian Bureau of Meteorology and uses the IMPROVER postprocessing system led by the Met Office. The paper performs calibration and evaluation with ECMWF AIFS, HRES, and ENS forecasts, MSAS gridded analyses, and Bureau Jive automatic weather-station observations. The model is suitable for deterministic correction, probabilistic calibration, and multi-model blended forecasting of surface temperature, surface dewpoint temperature, and 10 m wind speed.

# Use Cases

| Use Case | Description |
| :---: | :--- |
| Deterministic forecast postprocessing | Apply elevation and historical bias correction to AIFS-like weather forecasts. |
| Probabilistic forecasting and calibration | Produce threshold probabilities for three variables with spatial smoothing and reliability calibration. |
| Multi-model blending | Smoothly blend deterministic and probabilistic outputs from AIFS-, HRES-, and ENS-like inputs. |
| ModelScope/OneCode execution | Validate training, inference, evaluation, visualization, and checkpoint workflows in ModelScope or OneCode. |
| Multi-GPU training | Launch distributed data-parallel training with `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/IMPROVER-AIFS --local-dir ./IMPROVER-AIFS
cd IMPROVER-AIFS
```

### 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 number of structured synthetic samples to validate the engineering workflow, with AIFS-, HRES-, and ENS-like forecasts and corresponding MSAS-analysis and Bureau Jive station-observation semantics. Each sample retains 30 history days, 241 hourly leads, three variables, `61/47/49` thresholds, all 569 stations, and a `3x3` neighborhood for each station; only the number of valid dates and station samples used for parameter fitting is reduced. The paper does not publish the complete target Albers grid dimensions, so this implementation does not infer them; synthetic data validate postprocessing, training, inference, and evaluation only and do not represent the paper data distribution or performance.

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

### Training

For single-device 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 outputs are saved to:

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

### Trained Weights

This repository does not include weights under `weight/`. The paper does not provide a confirmed official checkpoint, and the current engineering checkpoint is not claimed to be compatible with external weights.

### Inference

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

Inference loads a checkpoint containing both valid-time folds and generates chunked deterministic and probabilistic blends for two valid dates, 241 leads, and all 569 stations. Numerical results and station metadata are saved to:

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

### Evaluation and Visualization

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

Evaluation results include errors for the raw, postprocessed, and blended forecasts and probabilistic forecast quality, together with target, prediction, and error comparisons at representative lead times. Synthetic-data results validate the engineering workflow only and do not represent paper performance.

```text
result/evaluation/metrics.json
result/evaluation/multi_lead_temperature.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 IMPROVER-AIFS specifications.

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