README.md

---
license: mit
language:
- en
library_name: pytorch
tags:
- OneScience
- fluid-dynamics
- functional-attention
- neural-operator
- operator-learning
datasets:
- OneScience-Group/airfrans
---

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

# Model Introduction

Functional Attention is a resolution-independent operator-learning framework developed by researchers affiliated with the Technical University of Munich. It predicts continuous functions such as PDE solutions, aerodynamic fields, and three-dimensional point-cloud segmentation outputs.

Paper: [Functional Attention: From Pairwise Affinities to Functional Correspondences](https://arxiv.org/abs/2605.31559)

# Model Description

Functional Attention uses adaptive basis functions and functional mappings. This package trains and evaluates the model on AirfRANS aerodynamic data for PDE solving, 3D segmentation, and regression across discretizations and resolutions.

# Intended Uses

| Use case | Description |
| --- | --- |
| 2D airfoil-flow surrogate | Predict pointwise velocity, pressure, and turbulent-viscosity fields on unstructured AirfRANS meshes. |
| Reynolds OOD evaluation | Use `reynolds_train -> reynolds_test` to measure out-of-distribution generalization across Reynolds numbers. |
| CFD surrogate acceleration | Approximate RANS simulations for fast field prediction and design screening. |
| Hugging Face/OneCode execution | Download the standalone model package, install its dependencies, and run the scripts directly. |

# 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, DCU, or HCU is recommended for full training.
- A CPU can be used for import checks and very small connectivity tests.
- DCU users should install DTK 25.04.2 or later, or the OneScience-recommended version for the cluster.

### Download the model repository from Hugging Face

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

### Install the runtime environment

**DCU environment**

```bash
# Activate DTK first.
conda create -n onescience311 python=3.11 -y
conda activate onescience311
pip install onescience[cfd] -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/airfrans --repo-type dataset --local-dir ./data
```

Verify that the data path in `config/config.yaml` points to the downloaded dataset. The original data is also available from:

```text
https://data.isir.upmc.fr/extrality/NeurIPS_2022/Dataset.zip
```

### Train

The default command runs the Reynolds OOD experiment:

```bash
python scripts/train.py \
  --config config/config.yaml \
  --task reynolds
```

The checkpoint with the best validation `Lv + Ls` is saved to `weight/best_model.pth`. It contains the model, optimizer, learning-rate scheduler, training epoch, experiment configuration, and normalization statistics.

### Inference

Run inference on three Reynolds OOD test cases:

```bash
python scripts/inference.py \
  --config config/config.yaml \
  --checkpoint weight/best_model.pth \
  --task reynolds \
  --max-cases 3
```

Reported metrics include relative L2 errors for four physical fields, surface-pressure relative L2, and explicitly labeled `pressure_only_*` lift and drag metrics.

### Visualization

`result.py` reads the training history and inference `.npz` files and produces training curves plus ground-truth, prediction, and absolute-error fields:

```bash
python scripts/result.py \
  --config config/config.yaml \
  --task reynolds
```

Outputs are saved to:

```text
results/figures/
results/visualization_manifest_reynolds.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: [Functional Attention: From Pairwise Affinities to Functional Correspondences](https://arxiv.org/abs/2605.31559).
- Upstream code and weights: [xjffff/FUNCATTN](https://github.com/xjffff/FUNCATTN) and [JayXI/FuncAttn](https://huggingface.co/JayXI/FuncAttn).
- This repository uses the Hugging Face-compatible MIT identifier (`mit`). AirfRANS and other third-party resources retain their own licenses and terms.