README.md

---
license: apache-2.0
language:
- en
tags:
- OneScience
- fluid dynamics
- unsteady turbulent flow prediction
- long-range mesh dependency modeling
frameworks: PyTorch
---
<p align="center">
  <strong>
    <span style="font-size: 30px;">EagleMeshTransformer</span>
  </strong>
</p>

# Model Overview

EagleMeshTransformer is a multiscale Mesh Transformer developed by the LIRIS research laboratory in Lyon, France, for fluid prediction on dynamic unstructured meshes. It is particularly well suited to unsteady turbulent flows and problems involving long-range dependencies in flow fields.

Paper: [EAGLE: Large-scale Learning of Turbulent Fluid Dynamics with Mesh Transformers](https://arxiv.org/abs/2302.10803).

# Model Description

EagleMeshTransformer uses a multiscale Mesh Transformer architecture trained on the EAGLE dataset to predict velocity and pressure fields in complex unsteady flows.
   


## Use Cases

| Use Case | Description |
|---|---|
| Unsteady turbulent flow prediction | Predict velocity and pressure fields in complex, aperiodic turbulent flows involving drones, jets, wakes, and similar systems |
| Unstructured-mesh simulation | Process irregular mesh data defined on complex geometries |
| CFD surrogate acceleration | Provide fast approximations of conventional Navier–Stokes and CFD simulations |
| Long-horizon physical prediction | Predict the evolution of physical states through autoregressive rollouts |

# Usage

## 1. OneCode

Use the online OneCode environment for an intelligent, one-click AI for Science (AI4S) programming experience:

[Launch OneCode for one-click AI4S programming](https://web-2069360198568017922-iaaj.ksai.scnet.cn:58043/home)

## 2. Manual Setup

**Hardware Requirements**

- A GPU or DCU is recommended.
- A CPU can be used for import checks and small-scale pipeline validation, 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 target cluster, is recommended.

### Download the Model Package

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

### 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
```

### Synthetic Data Validation

The default configuration points to the synthetic data directory in this repository and sets `training.max_epoch` to `1`. Generate a minimal EAGLE NPZ dataset to validate the training and inference pipelines:

```bash
python scripts/fake_data.py
```
### Training Data
The OneScience community provides the EAGLE dataset for training. Download it with the command below and verify that the data path in `conf/config.yaml` is configured correctly.

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

### Training

Single GPU:

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

Multiple GPUs:

```bash
torchrun --nproc_per_node=8 --nnodes=1 --rdzv_id=1000 --rdzv_backend=c10d --max_restarts=0 --master_addr="localhost" --master_port=29500 scripts/train.py
```

Training saves `best_model.pth` in the `weight/` directory.

### Model Weights
This repository will provide pretrained EagleMeshTransformer weights in the `weights/` directory. The weights will be uploaded soon.

### Inference

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

Inference results are saved to `result/output/`.

### Evaluation and Visualization

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


# Official OneScience Resources

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

# Citations and License
- Original EagleMeshTransformer paper: [EAGLE: Large-scale Learning of Turbulent Fluid Dynamics with Mesh Transformers](https://arxiv.org/abs/2302.10803).
- This repository retains source attribution and has been adapted for automated execution through OneScience and ModelScope.