README.md

---
frameworks: ONNX Runtime
language:
- en
license: cc-by-nc-nd-4.0
tags:
- OneScience
- Earth Science
- Weather Forecast
- Subseasonal Forecast
- Ensemble Forecasting
- ERA5
- ONNX
tasks: []
datasets:
- OneScience/ERA5
---
<p align="center">
  <strong>
    <span style="font-size: 30px;">FuXi-S2S</span>
  </strong>
</p>

# Model Introduction

FuXi-S2S is a global subseasonal forecasting model proposed by researchers from Fudan University and collaborating institutions.

Paper: A machine learning model that outperforms conventional global subseasonal forecast models

https://doi.org/10.1038/s41467-024-50714-1

# Model Description

FuXi-S2S takes two consecutive daily mean atmospheric states as input and targets the two-week to two-month forecast range, where conventional numerical models remain challenging to use effectively. This model package exposes the official ONNX inference graph through a small ONNX Runtime adapter.

# Use Cases

| Scenario | Description |
| :---: | :--- |
| Global subseasonal forecasting | Run the official FuXi-S2S ONNX weights with ERA5 inputs following the fixed 76-channel order. |
| Local quick validation | Use synthetic HDF5 data to check data loading, ONNX Runtime execution, and visualization. |
| ModelScope / OneCode execution | Download the standalone model package, configure an ONNX Runtime provider, and run the scripts directly. |

# Usage Guide

## 1. OneCode Usage

Experience intelligent one-click AI4S programming through the OneCode online environment:

[Click to Experience Intelligent One-Click AI4S Programming](https://web-2069360198568017922-iaaj.ksai.scnet.cn:58043/home)

## 2. Manual Installation and Usage

**Hardware Requirements**

- A GPU or DCU is recommended for practical inference. CPU can be used for import and small-scale connectivity checks, but full-resolution inference will be slow.
- Install the ONNX Runtime build that provides the execution provider required by your hardware.
- DCU users must install DTK in advance. DTK 25.04.2 or above, or the OneScience recommended version matching your cluster, is recommended.

### Download the Model Package

```bash
hf download OneScience-Group/FuXi-S2S --local-dir ./FuXi-S2S
cd FuXi-S2S
```

### Install the Runtime Environment

**DCU Environment**

```bash
# Please activate DTK and CONDA first
conda create -n onescience311 python=3.11 -y
conda activate onescience311
# uv installation is supported
pip install onescience[earth-dcu] -i http://mirrors.onescience.ai:3141/pypi/simple/  --trusted-host mirrors.onescience.ai
```

**GPU Environment**
```bash
# Please 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
# uv installation is supported
pip install onescience[earth-gpu] -i http://mirrors.onescience.ai:3141/pypi/simple/  --trusted-host mirrors.onescience.ai
```

Install or select an ONNX Runtime provider matching the target hardware, then update `model.providers` in `conf/config.yaml` if necessary. The default configuration targets a DCU-compatible provider list.

### Training Data Introduction

The official model uses daily mean ERA5 states with a fixed 76-channel order. The OneScience community provides an ERA5 data slice:

```bash
hf download --repo-type dataset OneScience-Group/ERA5 --local-dir ./data
```

The adapter expects yearly files under `data/data/` and normalization arrays under `data/stats/`. Confirm the variable order in `conf/config.yaml` before inference.

### Generate Synthetic Data

When real ERA5 data is unavailable, generate native-grid HDF5 files for interface checks:

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

For a smaller smoke fixture, pass `--height 32 --width 64`; synthetic data does not reproduce the official forecast quality.

### Pre-trained Weights

The official ONNX graph requires both files below:

```text
weight/fuxi_s2s.onnx
weight/fuxi_s2s
```

The large weight files are not bundled in this working copy and must be supplied from the authorized release. The `weight/` directory is reserved for these files.

### Inference

Inference reads `weight/fuxi_s2s.onnx` and its external data file by default. It converts ERA5 fields to the model's `121x240` grid and writes ONNX outputs to `result/output/`:

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

Use `--device cpu`, `--device cuda`, or `--device dcu` and configure `model.providers` for the selected runtime.

### Evaluation and Visualization

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

The result script reads the newest NPY output and writes multi-variable forecast figures to `result/visualization/`.

# Official OneScience Resources

| 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 model package contains an adapter for the official FuXi-S2S ONNX release.
- The official ONNX graph, external data file, and related data are subject to the CC BY-NC-ND 4.0 terms stated by the authorized release.