README.md

---
license: gpl-3.0
language:
- en
- zh
tags:
- OneScience
- Earth Science
- Weather Forecasting
- Global Weather Forecasting
- ERA5
frameworks: PyTorch
datasets:
- OneScience/ERA5
---

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

# Model Overview

DLWP-CS employs cubed-sphere convolutional neural networks for global weather forecasting, mitigating the geometric distortions that conventional latitude-longitude grids suffer near the poles.

Paper: *Improving Data-Driven Global Weather Prediction Using Deep Convolutional Neural Networks on a Cubed Sphere*

https://doi.org/10.1029/2020MS002109

# Model Description

This directory provides an independent PyTorch structural smoke implementation based on the paper and official code, featuring cubed-sphere cross-face padding, convolutions, a simplified U-Net, capped leaky ReLU, and autoregressive inference. It is not a reproduction of the paper's experimental architecture or ERA5 training.

# Use Cases

| Scenario | Description |
| :---: | :--- |
| Cubed-Sphere Architecture Research | Verify six-face adjacency, flipping, and convolution. |
| Local Rapid Verification | Run training and rollout with fake data. |
| ERA5 Global Weather Forecasting | Subsequently interface with ERA5 data processed via Tempest-Remap. |

# 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 minimum configuration.
- GPU is recommended for training on real data.

### Download the Model Package

```bash
hf download --model OneScience-Group/DLWP-CS --local-dir ./DLWP-CS
cd DLWP-CS
```

### 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 default training uses a deterministic fake Dataset from `model/dataset.py` and requires no additional download; each sample has shape `[C,6,H,W]`, and the validation set uses an independent seed.

### Training

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

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

1. Generates fake data of shape `[C,6,H,W]` by index;
2. Validates the six-face topology and capped leaky ReLU;
3. Executes U-Net forward/backward, MSE loss, and optimization per epoch;
4. Computes validation loss on an independent fake validation Dataset;
5. Saves latest/best checkpoints and history; supports `--resume`.

```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 result script produces `result/metrics.json` and `result/comparison.png`. The current `rmse` and `spatial_acc` serve only as connectivity checks on fake tensors; they do not apply the denormalization, latitude-weighted area averaging, cubed-sphere inverse mapping, or daily climatological anomaly computation required by the paper.

### Paper vs. Current Implementation I/O

| Item | Paper DLWP-CS | Current Smoke Implementation |
| --- | --- | --- |
| Dynamic Input | 4 variables at `t-6h,t`, 8 channels | 2-channel single state with no physical semantics |
| Auxiliary Input | Solar radiation, land-sea mask, topography | Not implemented |
| Spatial Grid | `[6,48,48]` cubed sphere | `[6,8,8]` fake grid |
| Output | 4 variables at `t+6h,t+12h`, 8 channels | 2-channel output of the same shape |
| Network / Training | Two-level U-Net, combined loss over two autoregressive steps | Single-level simplified U-Net, multi-epoch single-step MSE training |
| Analysis | Physical-unit, latitude-weighted RMSE/ACC | Smoke metrics without physical units |

The complete execution flow is `train.py -> inference.py -> result.py`. The fake Dataset preserves the cubed-sphere input shape but does not represent a continuous weather time series; the model package is distributed without local training weights or `result/` artifacts. A production mode further requires an ERA5 Dataset implementation, CS48 remapping, 4 dynamic variables, auxiliary fields, normalization statistics, and the paper's two-step iterative training loss.

### Real Data

Real-data training requires ERA5 variables Z500, Z1000, 300–700 hPa geopotential thickness, and 2 m temperature, along with solar radiation, a land-sea mask, topography, and Tempest-Remap offline remapping weights.

# 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

- Official Code: https://github.com/jweyn/DLWP-CS
- This directory is an independent adaptation based on the paper and official structure, licensed under GPL-3.0.