README.md

---
license: mit
language:
- en
tags:
- OneScience
- fluid-mechanics
- flow-field-prediction
- point-cloud
frameworks: PyTorch
---
<p align="center">
  <strong>
    <span style="font-size: 30px;">PointNetCFD</span>
  </strong>
</p>

# Model Introduction

PointNetCFD is a point-cloud model for flow-field prediction proposed by Ali Kashefi, Davis Rempe, and Leonidas J. Guibas. It directly represents nodes of unstructured CFD meshes in irregular geometries as point clouds, uses PointNet to encode geometry and spatial position, and predicts two velocity components and pressure at each point. This repository is an independent reproduction based on the paper and implemented through the OneScience skill workflow.

Paper: [A Point-Cloud Deep Learning Framework for Prediction of Fluid Flow Fields on Irregular Geometries](https://arxiv.org/abs/2010.09469)

# Model Description

PointNetCFD is a pointwise CFD regression model for unstructured meshes. Each sample contains 1,024 points. It takes node coordinates `(x, y)` as input and predicts `(u, v, p)` at every point. T-Nets align the inputs and features; shared MLPs and global max pooling extract local and global features; and a `512 → 256 → 128 → 128 → 3` decoder predicts the flow field from the fused representation. Coordinates retain their original physical scale, while output variables are normalized to `[0, 1]` using training-set statistics.

## Use Cases

| Use case | Description |
| --- | --- |
| CFD flow-field prediction | Predicts velocity components `(u, v)` and pressure `p` point by point from the two-dimensional coordinates `(x, y)` of unstructured-mesh nodes. |
| Irregular-geometry modeling | Directly represents object boundaries and unstructured meshes as point clouds without interpolating CFD data onto a regular grid. |
| Geometry generalization | The corresponding experiment evaluates predictive performance on previously unseen geometries. |

# 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/PointNetCFD --local_dir ./PointNetCFD
cd PointNetCFD
```

### 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 OneScience community provides PointNetCFD training data. Download it with the command below, then make sure `paths.data_dir` in `config/config.yaml` points to the downloaded data directory:

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

Each sample in `CFDdata.npy` is a 1,024 × 5 point-cloud data matrix with columns `[x, y, p, u, v]`. Index files for the training, validation, and test sets are also provided.

### Training

The default `config/config.yaml` corresponds to the main experimental setup in the paper.

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

During training, the training loss, validation loss, and evaluation metrics for each epoch are printed to standard output. The checkpoint with the best validation MSE is saved to:

```text
weight/best_model.pth
```

The training history, effective configuration, and training summary are stored in the `results/` directory. For an environment-connectivity check, run the minimal smoke test, which uses a separate output path:

```bash
python scripts/train.py --smoke-test
```

### Trained Weights

The `weight/` directory contains weights pretrained on the PointNetCFD data and ready for inference.

### Inference

Before running inference, make sure the data path in `config/config.yaml` is valid and `weight/best_model.pth` exists. The following command runs inference on the fixed test set and prints the normalized MSE, RMSE for each physical variable, and relative L2 error in real time:

```bash
python scripts/inference.py \
  --config config/config.yaml \
  --checkpoint weight/best_model.pth \
  --device auto \
  --output-dir results
```

Inference outputs are saved as:

- `results/test_metrics.json`: test metrics and reference metrics from the paper;
- `results/predictions.npz`: coordinates, predictions, ground truth, and sample indices.

### Evaluation and Visualization

Numerical evaluation is performed by `scripts/inference.py` during inference. The visualization script depends on `results/predictions.npz`, so complete the inference step above before running:

```bash
python scripts/result.py \
  --predictions results/predictions.npz \
  --output-dir results/figures \
  --num-cases 3
```

# 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: [A Point-Cloud Deep Learning Framework for Prediction of Fluid Flow Fields on Irregular Geometries](https://arxiv.org/abs/2010.09469), [DOI: 10.1063/5.0033376](https://doi.org/10.1063/5.0033376)
- This repository preserves the attribution and copyright information of the original paper and official implementation. The official code is licensed under the MIT License; the paper, dataset, and other related resources remain subject to their respective copyright notices and terms of use.