README.md

---
license: mit
language:
- en
tags:
- OneScience
- fluid-mechanics
- flow-field-prediction
- neural-operator
- Navier-Stokes
frameworks: PyTorch
---
<p align="center">
  <strong>
    <span style="font-size: 30px;">FNO</span>
  </strong>
</p>

# Model Introduction

FNO (Fourier Neural Operator) is a class of neural operators for parameterized partial differential equations. It directly learns mappings from input functions to solution functions by parameterizing integral kernels in Fourier space. Using the OneScience skill workflow, this project independently reproduces the FNO-2D experiment for predicting the vorticity of two-dimensional incompressible Navier–Stokes flows.

Paper: [Fourier Neural Operator for Parametric Partial Differential Equations](https://arxiv.org/abs/2010.08895)

# Model Description

This implementation takes 10 consecutive 64 × 64 vorticity fields as input and autoregressively predicts the next 10 frames. It first maps the historical fields and two-dimensional periodic coordinates into a latent space of width 32, then applies four Fourier layers. Each layer retains 12 Fourier modes along each spatial dimension, adds a 1 × 1 local convolution to the spectral convolution, and applies BatchNorm and ReLU. A 32 → 128 → 1 projection head generates the vorticity field for the next time step. Each prediction is appended to the input window for closed-loop rollout inference.

## Use Cases

| Use case | Description |
| --- | --- |
| Parameterized PDE operator learning | Learns mappings from PDE parameters, coefficient fields, or initial conditions to solution fields, especially when a PDE must be solved repeatedly for many parameter settings. |
| Burgers' equation prediction | Predicts future states from initial conditions for the one-dimensional Burgers' equation, demonstrating operator learning for nonlinear evolution equations. |
| Darcy flow prediction | Predicts steady-state solutions from two-dimensional diffusion or permeability coefficient fields for applications such as porous-media flow and groundwater seepage. |
| Navier–Stokes flow prediction | Autoregressively predicts the evolution of two-dimensional incompressible flow from historical vorticity fields. |

# Usage

## 1. Using OneCode

Try intelligent, one-click AI4S programming in the OneCode online environment:

[Try 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.
- A CPU can be used for import checks and small-scale connectivity tests, but full training and inference will be slow.
- DCU users must install DTK in advance. DTK 25.04.2 or later, or the OneScience-recommended version for the current cluster, is recommended.

### Download the Model Package

```bash
modelscope download --model OneScience/FNO --local_dir ./FNO
cd FNO
```

### Set Up the Runtime Environment

**DCU environment**

```bash
# Activate DTK and Conda first
conda create -n onescience311 python=3.11 -y
conda activate onescience311
# Installation with uv is also supported
pip install onescience[cfd-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
# Installation with uv is also supported
pip install onescience[cfd-gpu] -i http://mirrors.onescience.ai:3141/pypi/simple/  --trusted-host mirrors.onescience.ai
```

### Training Data

The experiment uses `NavierStokes_V1e-5_N1200_T20.mat`, whose shape is `[N,H,W,T]=[1200,64,64,20]`. For each trajectory, the first 10 frames are inputs and the final 10 frames are prediction targets. The first 1,000 trajectories are used for training and the remaining 200 for testing. There is no separate validation set, and no normalization is applied.

Download the data with:

```bash
modelscope download --dataset OneScience/fno --local_dir ./data
```

After downloading, set `data.root` in `config/config.yaml` to the data directory and confirm that `data.file` matches the MAT filename above. The training script strictly validates the field name, shape, dtype, and finite values.

### Training

The default configuration corresponds to the FNO-2D experiment with `ν=1e-5` and `T=20` in the paper. It trains for 500 epochs with a batch size of 20, uses Adam with an initial learning rate of `1e-3`, and halves the learning rate every 100 epochs.

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

The weights with the best full-trajectory relative L2 error on the training set are saved to `weight/best_model.pth`. The latest complete training state from every epoch is saved to `weight/last_model.pth`, and the training history is written to `results/train_history.json`.

### Trained Weights

`weight/best_model.pth` contains the best weights from the full training run and can be used directly for inference.

### Inference

Before running inference, make sure the configured data path is valid and `weight/best_model.pth` exists. The standard inference run uses the 200 configured test trajectories and a 10-step closed-loop rollout, printing batch progress and the final relative L2 error in real time:

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

Inference outputs are saved as:

- `results/predictions.npz`: predictions, ground truth, sample indices, and prediction times;
- `results/metrics.json`: overall and per-step metrics, including comparisons with the reference values from the paper;
- `results/per_sample_metrics.csv`: per-sample relative L2 errors.

### Evaluation and Visualization

After training and inference, run:

```bash
python scripts/result.py --config config/config.yaml --sample-index 0
```

The script recomputes metrics from `predictions.npz`, cross-checks the JSON and CSV outputs, best epoch, and prediction shape, and then generates:

- `results/training_curves.png`: training/test errors and training-objective curves;
- `results/sample_000_rollout.png`: ground truth, predictions, and absolute errors at `t=11, 16, 20` for a representative sample;
- `results/run_metadata.json`: configuration, runtime environment, assumptions, file hashes, and quality checks;
- `results/summary.md`: a summary of experimental results.

# 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

- Paper: [Fourier Neural Operator for Parametric Partial Differential Equations](https://arxiv.org/abs/2010.08895)
- The code in this model package is licensed under the MIT License. Use of the model weights is also subject to the licenses and applicable terms of the training data and third-party dependencies.