README.md

---
license: apache-2.0
language:
- en
tags:
- OneScience
- computational-fluid-dynamics
- natural-convection
datasets:
- NurshatMenglik/NeuralConvection_2D_TrainTest
---

<p align="center">
  <strong>
    <span style="font-size: 30px;">NeuralConvection-2D-CompactFNO</span>
  </strong>
</p>

# Model Introduction

NeuralConvection-2D-CompactFNO is a surrogate for two-dimensional natural convection. It maps velocity, temperature, and pressure fields from a Boussinesq simulation to the corresponding compressible-flow fields.

Paper: [A Neural Surrogate Approach for Simulating Natural Convection Problems](https://arxiv.org/abs/2606.25259)

# Model Description

This package reproduces the compact FNO in Table 5: four Fourier blocks, width 64, and 16 retained spectral modes per direction. Inputs and outputs are four-channel `64x64` fields in `[u_x, u_y, T, p]` order. The model was trained for 200 epochs on the authors' stochastic-temperature-boundary dataset.

## Use Cases

| Scenario | Description |
| :--- | :--- |
| Natural-convection correction | Predict compressible fields from Boussinesq fields |
| Industrial thermal-flow simulation | Accelerate field estimation in two-dimensional coupled flow and heat-transfer studies |

# Usage

## 1. OneCode

[Open the OneCode AI4S environment](https://web-2069360198568017922-iaaj.ksai.scnet.cn:58043/home)

## 2. Manual Setup

**Hardware requirements**

- GPU or DCU is recommended. CPU is suitable for small import and forward checks.
- For DCU, load the matching DTK environment before running PyTorch.

### Download the Model Package

```bash
hf download OneScience-Group/NeuralConvection-2D-CompactFNO --local-dir ./NeuralConvection-2D-CompactFNO
cd NeuralConvection-2D-CompactFNO
```

### Install the Runtime

**DCU**

```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
pip install scikit-image PyYAML
```

**GPU**

```bash
conda create -n onescience311 python=3.11 -y
conda activate onescience311
pip install onescience[cfd-gpu] -i http://mirrors.onescience.ai:3141/pypi/simple/ --trusted-host mirrors.onescience.ai
pip install scikit-image PyYAML
```

### Training Data

The authors' [NeuralConvection 2D dataset](https://huggingface.co/datasets/NurshatMenglik/NeuralConvection_2D_TrainTest) provides 4,000 training pairs and three 200-pair test splits. Download the fixed `v1.0-legacy` revision used for this reproduction:

```bash
hf download NurshatMenglik/NeuralConvection_2D_TrainTest --repo-type dataset --revision v1.0-legacy --local-dir ./data
```

The public package sets `data.root_dir` in `config/config.yaml` to `./data`, so the commands below use the downloaded data when run from the project directory.

### Training

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

The best checkpoint is saved to `weight/best_model.pth`.

### Model Weights

The package includes the best checkpoint from a complete 200-epoch DCU training run.

### Inference

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

### Evaluation and Visualization

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

# OneScience Repositories

| Platform | 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: [A Neural Surrogate Approach for Simulating Natural Convection Problems](https://arxiv.org/pdf/2606.25259).
- This reproduction package is released under Apache-2.0. The authors' dataset is CC BY 4.0 and requires attribution; the official research code uses the NCSA license.