Update README and model configuration

README.md

@@ -0,0 +1,165 @@
+---
+license: other
+language:
+- en
+library_name: pytorch
+datasets:
+- OneScience-Group/ShapeNetCar
+tags:
+- OneScience
+- computational-fluid-dynamics
+- graph-neural-operator
+- automotive-aerodynamics
+- pde-surrogate-modeling
+---
+<p align="center">
+  <strong>
+    <span style="font-size: 30px;">AMG</span>
+  </strong>
+</p>
+
+# Model Overview
+
+AMG is a multi-graph neural operator for solving partial differential equations on arbitrary geometries. It was proposed by researchers from the Hong Kong University of Science and Technology (Guangzhou), Beihang University, and other institutions. The model uses multiscale graphs, a physics graph, and the dynamic graph-attention mechanism in GraphFormer to learn PDE solution operators on regularly or irregularly discretized domains. This package is trained for the ShapeNet-Car/CarCFD experiment. Given a three-dimensional vehicle geometry and mesh-node features, it predicts surface pressure and the surrounding airflow velocity field for rapid aerodynamic evaluation and drag-coefficient estimation.
+
+This repository is an independent reproduction of the AMG ShapeNet-Car experiment, implemented through the OneScience workflow from the paper description and official configuration.
+
+Paper: [Harnessing Scale and Physics: A Multi-Graph Neural Operator Framework for PDEs on Arbitrary Geometries](https://arxiv.org/abs/2411.15178)
+
+# Model Description
+
+AMG uses an encoder, a multi-graph processor, and a decoder. It takes discrete mesh-point coordinates and node features as input. A local graph captures high-frequency local variations, a global graph models long-range spatial dependencies, and a physics graph aggregates and propagates latent physical properties. The GraphFormer module performs cross-node interaction with dynamic graph attention and produces the PDE solution at the original discrete points. For the ShapeNet-Car/CarCFD task, the model predicts three velocity components and pressure on a three-dimensional unstructured mesh containing 32,186 points.
+
+## Use Cases
+
+| Use Case | Description |
+| --- | --- |
+| Three-dimensional automotive external-flow prediction | Predict the three-dimensional velocity field around complex vehicle geometries and pressure on the vehicle surface |
+| Automotive aerodynamic evaluation | Use predicted velocity and pressure fields to support drag-coefficient estimation and aerodynamic assessment |
+| PDE learning on unstructured meshes | Build PDE surrogate models for three-dimensional unstructured meshes and irregular geometric domains |
+| CFD surrogate modeling | Replace part of a costly numerical-simulation workflow to accelerate vehicle-shape design and batch evaluation of design candidates |
+
+# 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 from Hugging Face
+
+```bash
+pip install -U huggingface_hub
+hf download OneScience-Group/AMG-ShapeNet-Car --local-dir ./AMG-ShapeNet-Car
+cd AMG-ShapeNet-Car
+```
+
+### 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 the ShapeNetCar training data on Hugging Face. Download it with the command below, then update `data.root` in `config/config.yaml` so that it points to the downloaded `preprocessed_data` directory.
+
+```bash
+hf download OneScience-Group/ShapeNetCar --repo-type dataset --local-dir ./data
+```
+
+The dataset contains 889 three-dimensional automotive external-flow samples organized into nine shards, `param0` through `param8`. It includes 690 training samples, 99 validation samples, and 100 test samples. Each sample contains 32,186 unstructured mesh points and the following files:
+
+- `x.npy`: node input features with shape `(32186, 7)`; AMG uses the four features at indices `[3, 4, 5, 6]`
+- `y.npy`: ground-truth CFD solution with shape `(32186, 4)`, containing three velocity components followed by pressure
+- `pos.npy`: three-dimensional mesh-point coordinates with shape `(32186, 3)`
+- `surf.npy`: vehicle-surface node mask with shape `(32186,)`
+- `edge_index.npy`: unstructured-mesh edge connectivity with shape `(2, E)`
+
+### Training
+
+Single-device training:
+
+- Training parameters are read from the `data`, `model`, and `training` sections of `config/config.yaml`.
+- The default configuration follows the paper and trains for 500 epochs. Add `--smoke` for a minimal end-to-end test.
+- Before training, set `data.root` to the ShapeNetCar dataset's `preprocessed_data` directory.
+- For the two-device, eight-hour profile, use `--profile fast_8h_2dcu`.
+
+```bash
+python scripts/train.py
+```
+
+Multi-device training:
+
+```bash
+torchrun --standalone --nproc_per_node=<num_GPUs> scripts/train.py
+```
+
+Two-device, eight-hour training profile:
+
+```bash
+torchrun --standalone --nproc_per_node=2 scripts/train.py --profile fast_8h_2dcu
+```
+
+Training reports the training loss, validation pressure relative L2 error, and validation velocity relative L2 error. The best checkpoint is selected using the mean validation relative L2 error and saved to:
+
+```text
+./weight/best_model.pt
+```
+
+### Model Weights
+
+The `weight/` directory contains `best_model.pt`, the best AMG checkpoint obtained from this ShapeNet-Car/CarCFD reproduction. It can be loaded directly for inference.
+
+### Inference
+
+```bash
+python scripts/inference.py
+```
+
+Predictions, per-sample metrics, and aggregate metrics are saved under `results/`.
+
+### Evaluation and Visualization
+
+```bash
+python scripts/result.py
+```
+
+The evaluation report, paper-metric comparison plots, training curves, and flow-field visualizations are saved under `results/`.
+
+# 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 AMG paper: [Harnessing Scale and Physics: A Multi-Graph Neural Operator Framework for PDEs on Arbitrary Geometries](https://arxiv.org/abs/2411.15178)
+- This repository retains attribution to the original paper and the ShapeNet-Car/CarCFD dataset. Use of this project must comply with the licenses and terms that apply to the original paper, dataset, and related resources.