README.md

---
license: mit
language:
- en
library_name: pytorch
tags:
- OneScience
- fluid-dynamics
- turbulence
- fourier-neural-operator
- physics-informed
datasets:
- OneScience-Group/fno
---

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

# Model Introduction

Spectral-Refiner is a physics-residual fine-tuning method for spatiotemporal Fourier neural operators. This project reproduces the two-dimensional forced-turbulence experiment from Table 2 of the paper: an SFNO is first trained on `64 x 64` vorticity trajectories, then its spectral output layer is fine-tuned at `256 x 256` resolution using the \(H^{-1}\) negative Sobolev norm of the Navier–Stokes PDE residual.

Paper: [Spectral-Refiner: Accurate Fine-Tuning of Spatiotemporal Fourier Neural Operator for Turbulent Flows](https://arxiv.org/abs/2405.17211)

# Model Description

The model takes the first 10 time steps of a two-dimensional vorticity field and predicts the next 40. The base SFNO has four spatiotemporal spectral layers, `12 x 12` spatial modes, 5 temporal modes, and width 20. Spectral-Refiner freezes the base network, expands the output spectral layer to `64 x 64 x 6`, and fine-tunes it for 50 steps with an \(H^{-1}\) PDE-residual objective. This project is an independent OneScience reproduction.

## Intended Uses

| Use case | Description |
| :--- | :--- |
| 2D turbulence prediction | Predict future spatiotemporal evolution from historical vorticity fields. |
| PDE surrogate | Accelerate periodic fluid problems with a Fourier neural operator. |
| Physics-residual fine-tuning | Constrain the predicted PDE residual with a negative Sobolev norm. |

# Usage

## 1. OneCode

[Launch the OneCode AI-for-Science environment](https://web-2069360198568017922-iaaj.ksai.scnet.cn:58043/home)

## 2. Manual Setup

**Hardware requirements**

- A GPU or DCU is recommended for full training and inference.
- A CPU can run imports and the `--smoke` connectivity test.
- The reported validation used PyTorch 2.5.1 on one DCU.

### Download the model repository from Hugging Face

```bash
pip install -U huggingface_hub
hf download OneScience-Group/Spectral-Refiner --local-dir ./Spectral-Refiner
cd Spectral-Refiner
```

### Install the runtime environment

**DCU environment**

```bash
conda create -n onescience311 python=3.11 -y
conda activate onescience311
pip install onescience[cfd-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[cfd-gpu] -i http://mirrors.onescience.ai:3141/pypi/simple/ --trusted-host mirrors.onescience.ai
```

### Download the training dataset from Hugging Face

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

The required files are:

```text
data/
├── fnodata_extra_64x64_N1280_v1e-3_T50_steps100_alpha2.5_tau7.pt
└── fnodata_extra_fp64_256x256_N16_v1e-3_T50_steps100_alpha2.5_tau7.pt
```

Set `data.train_file` and `data.test_file` in `config/config.yaml` to these files. The default experiment uses 1,152 low-resolution trajectories for training and 128 for validation, mapping 10 input steps to 40 output steps. The high-resolution data is used for evaluation and \(H^{-1}\) spectral fine-tuning on the `256 x 256` grid.

### Train

```bash
python scripts/train.py --config config/config.yaml
```

`weight/best_model.pt` stores the base SFNO, Spectral-Refiner output layer, configuration, and weight-selection metric.

### Inference

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

Predictions are saved to `results/predictions.pt`.

### Evaluation

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

Metrics are printed and saved to `results/metrics.json`.

# OneScience

| Platform | OneScience repository | OneSkills 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

- Paper: [Spectral-Refiner, arXiv:2405.17211](https://arxiv.org/abs/2405.17211).
- Public implementation: [scaomath/torch-cfd](https://github.com/scaomath/torch-cfd).
- This repository uses the Hugging Face-compatible MIT identifier (`mit`). Dataset files and other third-party assets retain their original licenses and terms.