README.md

---
license: apache-2.0
language:
- en
tags:
- OneScience
- Earth Science
- WRF
- Physical Parameterization
- Radiative Transfer
- Bidirectional LSTM
frameworks: PyTorch
---

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

# Model Introduction

WRF-ML bridges WRF v4.3 and Python machine-learning parameterizations. This reproduction focuses on the recommended Model D, using a bidirectional LSTM to emulate RRTMG shortwave and longwave outputs.

Paper: WRF–ML v1.0: a bridge between WRF v4.3 and machine learning parameterizations and its application to atmospheric radiative transfer  
https://doi.org/10.5194/gmd-16-199-2023

# Model Description

The model was proposed by researchers at Alibaba Group's Damo Academy. It was trained with atmospheric-column inputs and RRTMG outputs generated by WRF simulations, with 57 vertical levels per sample. Through layout adaptation and a synchronous request-response protocol, it supports shortwave and longwave flux and heating-rate emulation as an online WRF physical parameterization.

# Use Cases

| Use Case | Description |
| :---: | :--- |
| Radiation emulation | Emulate shortwave and longwave fluxes and heating rates. |
| WRF parameterization | Validate atmospheric-column batching and output layout restoration. |
| Offline evaluation | Compute RMSE for six radiation outputs. |
| Coupling protocol | Demonstrate synchronous blocking request, inference, and response. |
| ModelScope/OneCode execution | Validate structured data, training, inference, probabilistic precipitation metrics, and visualization in ModelScope or OneCode. |
| Multi-GPU training | Start multi-process training through `torchrun`. |

# Usage Instructions

## Download

```bash
hf download OneScience-Group/WRF-ML --local-dir ./WRF-ML
cd WRF-ML
```

### Environment Dependencies

**Hardware Requirements**

- A GPU or DCU is recommended.
- A CPU can run the default small-sample connectivity configuration.
- DCU users should install DTK 25.04.2 or a compatible OneScience-recommended version first.

**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
```

## Synthetic Data

The paper uses a `190x170` horizontal domain, 57 vertical levels, and WRF-RRTMG columns sampled every 30 minutes. Synthetic data preserve 57 levels, WRF layout conversion, and six output semantics while reducing column count, hidden width, and epochs; the ten inputs are explicitly an engineering ledger because the paper does not enumerate all input variables. Results verify the workflow only and do not represent paper performance.

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

## Training

```bash
python scripts/train.py
torchrun --nproc_per_node=2 --nnodes=1 --master_addr="localhost" --master_port=29500 scripts/train.py
```

The default synthetic run jointly optimizes 57-level radiation profiles and boundary fluxes, and both single-process and two-process DDP training have been verified. It produces one recoverable Model-D-style checkpoint and records normalized mean squared error. Training results are saved to:

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

## Weights

The paper's code and data are archived at https://doi.org/10.5281/zenodo.7407487. This reproduction does not link a pretrained checkpoint because a separately licensed official weight artifact was not confirmed.

## Inference

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

Inference restores the checkpoint, runs the synchronous layout-adapted coupler, and produces 57-level profiles and boundary fluxes. Profile and boundary output shapes are `[6,57,4]` and `[6,2]`, respectively, and both have passed finite-value checks. Inference results are saved to:

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

## Evaluation

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

Evaluation reports RMSE for shortwave and longwave fluxes, heating rates, and boundary shortwave fluxes and creates a vertical-profile comparison. All metrics are finite, and the PNG has passed format and non-empty-pixel checks. Evaluation results are saved to:

```text
result/evaluation/metrics.json
result/evaluation/comparison.png
```

# Official OneScience Information

| Platform | OneScience | OneSkills |
|---|---|---|
| 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 WRF-ML specifications, with code licensed under the Apache License 2.0.

The original paper is licensed under CC BY 4.0; the paper, WRF, RRTMG, ONNX Runtime, and related data remain subject to their respective licenses and terms.