Update README and model configuration

README.md

@@ -0,0 +1,167 @@
+---
+license: mit
+language:
+- en
+library_name: pytorch
+tags:
+- OneScience
+- fluid-dynamics
+- neural-operator
+- transformer
+- point-cloud
+datasets:
+- OneScience-Group/ShapeNetCar
+---
+
+<p align="center">
+  <strong><span style="font-size: 30px;">UPT</span></strong>
+</p>
+
+# Model Introduction
+
+UPT (Universal Physics Transformer), proposed by Benedikt Alkin and collaborators, is a general-purpose physics Transformer. It encodes irregular meshes or particle data into a compact latent representation and propagates information in latent space for flexible, scalable physical-surrogate modeling.
+
+This repository is an independent OneScience reproduction of the UPT ShapeNetCar experiment without an SDF. The model predicts steady surface pressure from three-dimensional vehicle-surface coordinates and does not use SDF values, normals, mesh connectivity, or flow variables as model inputs.
+
+Paper: [Universal Physics Transformers: A Framework For Efficiently Scaling Neural Operators](https://proceedings.neurips.cc/paper_files/paper/2024/file/2cd36d327f33d47b372d4711edd08de0-Paper-Conference.pdf)
+
+# Model Description
+
+For ShapeNetCar, UPT takes vehicle-surface coordinates \((x,y,z)\) and predicts scalar pressure at specified surface-query coordinates.
+
+The architecture consists of coordinate encoding, a Perceiver encoder, a latent-space Transformer, a Perceiver decoder, and pressure projection. Continuous sine/cosine positional encodings and an MLP first map scaled coordinates to input features. Perceiver cross-attention compresses a variable number of input points into learnable latent tokens, and Transformer blocks model global geometric relationships in latent space. During decoding, encoded query coordinates attend to the latent representation before normalization and linear projection produce surface-pressure predictions.
+
+## Intended Uses
+
+| Use case | Description |
+| --- | --- |
+| Vehicle-surface pressure | Predict steady aerodynamic pressure from ShapeNetCar surface coordinates. |
+| Irregular point-set modeling | Regress physical values on 3D surface point sets without a regular grid or explicit mesh connectivity. |
+| Scientific surrogate | Approximate expensive numerical simulation within a fixed data distribution and flow regime. |
+| Variable-point inference | Accept variable-size input sets and query pressure at surface coordinates within the training distribution. |
+
+# 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 or DCU is recommended.
+- A CPU can run imports and small connectivity checks, but full training and inference will be slow.
+- 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/UPT --local-dir ./UPT
+cd UPT
+```
+
+### 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-dcu] -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/ShapeNetCar \
+  --repo-type dataset \
+  --local-dir ./data
+```
+
+Set `data.root` in `config/config.yaml` to the dataset's `preprocessed_data` directory. The dataset contains 889 vehicle geometries, split with a fixed random seed into 700 training and 189 test samples. Each preprocessed sample includes:
+
+- `pos.npy`: all node coordinates, shape `[num_nodes, 3]`.
+- `surf.npy`: surface-node mask, shape `[num_nodes]`.
+- `y.npy`: target physical fields, shape `[num_nodes, 4]`; the first three channels are velocity and the fourth is pressure.
+- `x.npy`: node features, shape `[num_nodes, 7]`. This implementation uses normals only to filter surface nodes; they are not model inputs.
+- `edge_index.npy`: graph connectivity, which is not used as a model input.
+
+The loader selects 3,586 valid surface points per mesh, rescales coordinates, and normalizes pressure with the configured mean and standard deviation. During training, 80%–100% of each sample's surface points are randomly selected as encoder inputs while the pressure loss is computed on all surface points. During testing, all valid surface points are used as both inputs and queries.
+
+### Train
+
+`config/config.yaml` contains the no-SDF ShapeNetCar reproduction configuration.
+
+```bash
+python scripts/train.py --config config/config.yaml
+```
+
+Training uses masked MSE on normalized surface pressure. Per-epoch training and test metrics are written to `results/train_metrics.jsonl`. The script prints batch loss, learning rate, normalized pressure MSE, normalized pressure MSE × 100, and original-scale pressure RMSE. The checkpoint with the lowest test normalized pressure MSE × 100 is saved to `weight/best_model.pth`.
+
+### Pretrained weights
+
+The repository includes `weight/best_model.pth`, trained on ShapeNetCar and ready for surface-pressure inference and numerical evaluation.
+
+### Inference and evaluation
+
+Run inference on the fixed set of 189 test samples:
+
+```bash
+python scripts/inference.py \
+  --config config/config.yaml \
+  --checkpoint weight/best_model.pth \
+  --device auto
+```
+
+The script reports normalized pressure MSE, normalized pressure MSE × 100, normalized pressure MAE, original-scale pressure MSE, and original-scale pressure RMSE. It writes:
+
+```text
+results/inference_metrics.json
+results/predictions/
+└── <sample_id>.npz
+```
+
+`inference_metrics.json` contains aggregate and per-sample metrics plus paper-reference values. Each `<sample_id>.npz` stores surface coordinates, normalized and original-scale predictions and targets, and absolute errors.
+
+### Visualization
+
+```bash
+python scripts/result.py --config config/config.yaml
+```
+
+Outputs:
+
+```text
+results/figures/
+├── training_metrics.png
+├── <sample_id>_pressure_comparison.png
+└── visualization_metadata.json
+```
+
+- `training_metrics.png` shows normalized training MSE and test normalized MSE × 100 with the paper reference.
+- `<sample_id>_pressure_comparison.png` compares target surface pressure, UPT prediction, and absolute pressure error in 3D.
+- `visualization_metadata.json` records prediction and evaluation sources, output paths, and plotting parameters.
+
+# 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: [Universal Physics Transformers: A Framework For Efficiently Scaling Neural Operators](https://proceedings.neurips.cc/paper_files/paper/2024/file/2cd36d327f33d47b372d4711edd08de0-Paper-Conference.pdf).
+- Official implementation: [ml-jku/UPT](https://github.com/ml-jku/UPT), released under the [MIT License](https://github.com/ml-jku/UPT/blob/main/LICENSE.md).
+- This repository uses the Hugging Face-compatible MIT identifier (`mit`). ShapeNetCar and all other third-party resources remain subject to their original licenses and terms.