README.md

---
license: apache-2.0
language:
- en
tags:
- OneScience
- Earth Science
- Ensemble Forecast Postprocessing
- Probabilistic Neural Network
frameworks: PyTorch
---

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

# Model Introduction

PPNN converts ensemble weather forecasts and station information into calibrated probability distributions for 2 m temperature, supporting station-level ensemble postprocessing, uncertainty representation, and probabilistic weather forecasting.

Paper: Neural Networks for Postprocessing Ensemble Weather Forecasts  
https://doi.org/10.1175/MWR-D-18-0187.1

# Model Description

The method was proposed by research teams at Ludwig-Maximilians-Universität München, Karlsruhe Institute of Technology, and the Heidelberg Institute for Theoretical Studies. The paper trains on ECMWF TIGGE ensemble forecasts and Deutscher Wetterdienst station observations of 2 m temperature. It is intended for station-temperature probabilistic postprocessing and ensemble calibration at a fixed 48-hour lead.

# Use Cases

| Use Case | Description |
| :---: | :--- |
| Ensemble forecast postprocessing | Generate Gaussian temperature forecasts from ensemble moments and station information. |
| Probabilistic training | Train mean and scale parameters with Gaussian CRPS. |
| ModelScope/OneCode execution | Validate feature construction, training, inference, calibration evaluation, and visualization in ModelScope or OneCode environments. |
| Multi-GPU training | Train independent network replicas 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/PPNN --local-dir ./PPNN
cd PPNN
```

### 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 first. DTK 25.04.2 or later, or the OneScience-recommended version matching the 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

Training data consist of ECMWF TIGGE ensemble forecasts and DWD station observations of 2 m temperature. Each sample contains 50 ensemble members, 18 forecast variables, and station location and elevation information, with same-valid-time station temperature as the target. Forecasts are initialized daily at 00 UTC with a fixed 48-hour lead, and temperature is measured in degrees Celsius. This repository uses a small number of synthetic samples to validate training, inference, and probabilistic evaluation; they do not represent the official TIGGE or DWD distribution, training scale, or formal paper 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
```

The default engineering configuration reduces the hidden width from the paper's long-training value of 512 to 32, the independent network count from 10 to 2, and the training epochs and sample count. It does not reduce the 50 members, 18 variables, metadata for 537 stations, two-dimensional station embedding, or 48-hour lead. A formal experiment requires the real TIGGE and DWD data, the paper-scale network ensemble, and the complete training period.

Training outputs are saved to:

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

### Trained Weights

No weights are bundled under `weight/`, and no directly loadable pretrained checkpoint released by the paper authors was identified. Locally trained engineering checkpoints are written to `result/checkpoints/ppnn.pt` and must not be represented as official pretrained weights.

### Inference

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

Inference loads the trained checkpoint and generates Gaussian temperature forecasts at the fixed 48-hour lead from 50-member ensemble statistics and station information. Complete numerical results are saved to:

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

### Evaluation and Visualization

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

Evaluation follows the paper's probabilistic protocol for Gaussian CRPS, raw-ensemble CRPS, CRPSS, PIT calibration, and spread-error diagnostics, saving overall and station-sample aggregate results; the task has one fixed 48-hour lead and no classes, so no per-lead or per-class metrics are saved. It also generates PIT-calibration and probabilistic-error comparisons. Synthetic-data results validate the engineering workflow only and do not represent formal paper performance.

```text
result/evaluation/metrics.json
result/evaluation/ppnn_evaluation.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 PPNN specifications.

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