README.md

---
license: other
language:
- en
- zh
tags:
- OneScience
- Earth Science
- Weather Forecasting
- Precipitation Forecasting
- Short-Range Weather Forecasting
frameworks: PyTorch
datasets:
- OneScience/MetNet3-Fake
---

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

# Model Overview

MetNet-3 is a regional high-resolution weather forecasting model designed for sparse observations, capable of predicting variables such as precipitation, temperature, dew point, and wind.

Paper: *Deep Learning for Day Forecasts from Sparse Observations*

https://arxiv.org/abs/2306.06079

# Model Description

This directory provides an independent compact smoke implementation based on the paper, preserving multi-source input interfaces, lead-time conditioning, a sparse OMO mask, probabilistic outputs, and HRRR auxiliary regression. The input scale, temporal fusion, MaxViT backbone, and output resolution have all been simplified.

The current model is intended for functional verification only; it is not the official Google implementation and does not provide official pre-trained weights.

# Use Cases

| Scenario | Description |
| :---: | :--- |
| Multi-Source Weather Model Research | Verify input interfaces for MRMS, OMO, HRRR, GOES, etc. |
| Local Rapid Verification | Run training, checkpointing, and inference with fake data. |
| Real Regional Forecasting | Subsequently interface with real MRMS, OMO, HRRR, and GOES data. |

# Usage

## 1. OneCode

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

## 2. Manual Installation & Usage

**Hardware Requirements**

- CPU can run the current compact configuration.
- GPU is recommended for real data and larger configurations.

### Download the Model Package

```bash
hf download --model OneScience-Group/MetNet-3 --local-dir ./MetNet-3
cd MetNet-3
```

### Set Up the Runtime Environment

**DCU Environment**

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

### Data

The current `model/fake_data.py` provides an indexable fake Dataset that generates MRMS, OMO, HRRR proxy, GOES proxy, topography, coordinates, time, and lead-time data and requires no additional download. Each sample excludes the batch dimension; the DataLoader concatenates samples into batches.

### Training

```bash
python scripts/train.py
```

The script performs multi-epoch multi-task training, independent validation, learning rate scheduling, and early stopping:

1. Generates train/validation fake Datasets and multi-task targets;
2. Validates the input schema on each batch;
3. Computes precipitation cross-entropy, surface-variable cross-entropy, and HRRR MSE, and updates parameters;
4. Computes validation loss on an independent validation Dataset;
5. Saves latest/best checkpoints and history; supports `--resume`;
6. The inference stage reads `weight/model.pth`.

```bash
python scripts/train.py --epochs 10
python scripts/train.py --resume weight/training/latest.pth --epochs 20
```

Checkpoint outputs:

```text
weight/model.pth
weight/training/latest.pth
weight/training/best.pth
weight/training/history.json
```

### Inference

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

Inference results:

```text
result/prediction.pt
result/target.pt
result/inference.json
```

### Result Inspection

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

The current output is generated from fake data and is intended only to verify that the model runs; it does not represent the paper's forecast skill metrics.

The result script generates `result/metrics.json` and `result/comparison.png`, reporting precipitation/surface MAE in normalized bin space, HRRR proxy RMSE, and probability normalization error — not the paper's CRPS, CSI, or physical-unit MAE.

### Paper vs. Current Implementation I/O

| Input / Output | Paper | Current Compact Configuration |
| --- | --- | --- |
| MRMS High | 2 channels × 11 frames | 4 channels × 3 frames, last frame only used |
| MRMS Low | 1 channel × 1 frame | 3 channels × 2 frames, last frame only used |
| OMO | 14 channels × 9 frames | 2 channels × 3 frames, last frame only used |
| HRRR / GOES | 618 / 16 channels | 8 / 4 proxy channels |
| Precipitation Output | Two target classes, 512 bins each | Single target, 16 bins |
| Surface Output | 6 variables, 256/180 bins | 6 variables, uniform 8 bins |
| Backbone | Modified 12-block MaxViT | Single-layer Transformer proxy |
| Training | Full data with multi-task training | Multi-epoch fake Dataset multi-task training |

The complete execution flow is `train.py -> inference.py -> result.py`. Individual fake Dataset samples have input shape `[T,C,H,W]` and targets as a corresponding multi-task dictionary, with a default spatial size of `8×8`; `current_time` and `lead_time` are each `[1]`, becoming `[B,1]` after the DataLoader. The checkpoint is always written to `weight/model.pth`, and training history with latest/best checkpoints is written to `weight/training/`. The model package is distributed without these local training weights or `result/` artifacts.

### Real Data

Real-data training requires MRMS instantaneous/accumulated precipitation, OMO/ASOS station observations, HRRR 617 channels and stale-age, GOES 16 channels, elevation, a common projection, QC, missing-value handling, and normalization statistics.

# OneScience Official 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 & License

- This directory is an independent compact reproduction built according to the MetNet-3 paper.
- Paper materials, code, and subsequent real data are each subject to their respective licenses.