README.md

---
frameworks:
  - pytorch
language:
  - en
license: apache-2.0
tags:
  - OneScience
  - SA-PINNs
  - self-adaptive-physics-informed-neural-networks
  - soft-attention
  - partial-differential-equations
  - Laplace
  - Helmholtz
  - Burgers
tasks:
  - pde-solving
---
<p align="center">
  <strong>
    <span style="font-size: 30px;">SA-PINNs</span>
  </strong>
</p>

# Model Overview

SA-PINNs (Self-Adaptive Physics-Informed Neural Networks) assign learnable positive attention weights to observation points, boundary points, and PDE collocation points, enabling the model to focus automatically on regions that are difficult to fit during training.

This model package provides examples for the one-dimensional Laplace equation, the two-dimensional Helmholtz equation, and the one-dimensional time-dependent Burgers equation.

Paper: Self-Adaptive Physics-Informed Neural Networks using a Soft Attention Mechanism  
https://arxiv.org/abs/2009.04544

# Model Description

SA-PINNs use min–max saddle-point optimization: network parameters reduce the weighted physics loss through gradient descent, while attention parameters increase the weights assigned to difficult locations through gradient ascent. The attention weights are constructed from normalized `exp(alpha)`, ensuring that they remain positive with a mean close to 1. The Adam stage updates both the network and attention parameters, whereas the L-BFGS stage freezes the attention parameters and refines the network.

# Use Cases

| Use Case | Description |
| :---: | :--- |
| One-dimensional Laplace equation | Examine how attention focuses on collocation points with high residuals |
| Two-dimensional Helmholtz equation | Solve a two-dimensional analytical solution with high-frequency spatial variation |
| Burgers equation | Train jointly on initial conditions, boundary conditions, and nonlinear PDE residuals |
| Adaptive-weight research | Compare a standard PINN with pointwise soft-attention weighting |

# 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 for training.
- A CPU can be used for small-scale pipeline validation.
- DCU users must install DTK and a PyTorch environment compatible with the target cluster.

### Download the Model Package

```bash
modelscope download --model OneScience/SA-PINNs --local_dir ./SA-PINNs
cd SA-PINNs
```

### Set Up the Runtime Environment

**DCU Environment**

```bash
# Activate DTK and Conda 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
# 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
pip install onescience[cfd-gpu] -i http://mirrors.onescience.ai:3141/pypi/simple/ --trusted-host mirrors.onescience.ai
```

### Training Data

All three examples generate observation points, boundary points, and PDE collocation points from analytical equations and random sampling, with no dependency on external data files. The Burgers example does not include a reference solution and therefore outputs only the predicted field and attention distribution.

### Training

Select an example with `--case`:

```bash
python scripts/train.py --case laplace
python scripts/train.py --case helmholtz
python scripts/train.py --case burgers
```

Checkpoints and training histories are saved to `weight/` and `result/` by default. Command-line arguments such as `--epochs`, `--lbfgs-iters`, `--n-pde`, and `--device` can override values in `conf/config.yaml`.

### Model Weights

This repository provides weights trained for all three examples in the `weight/` directory.


### Inference, Evaluation, and Visualization

After training the selected example, run:

```bash
python scripts/inference.py --case laplace
python scripts/inference.py --case helmholtz
python scripts/inference.py --case burgers
```

Predictions, error plots, and PDE attention distributions are saved to the `result/` directory. The Laplace and Helmholtz examples report relative L2 errors. Default model and training parameters can be modified in `conf/config.yaml`.

# 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

- McClenny, L. and Braga-Neto, U. Self-Adaptive Physics-Informed Neural Networks using a Soft Attention Mechanism. arXiv:2009.04544, 2020.
- This model package is released under the Apache-2.0 license and retains attribution to the original paper.