README.md

---
frameworks:
  - pytorch
language:
  - en
license: apache-2.0
tags:
  - OneScience
  - gPINNs
  - physics-informed-neural-networks
  - partial-differential-equations
  - Poisson
  - Burgers
tasks:
  - pde-solving
---
<p align="center">
  <strong>
    <span style="font-size: 30px;">gPINNs</span>
  </strong>
</p>

# Model Overview

gPINNs (Gradient-enhanced Physics-Informed Neural Networks) augment the PDE residual constraints of conventional PINNs with constraints on residual gradients with respect to the input coordinates. This additional higher-order derivative information can improve sample efficiency and solution accuracy for selected forward and inverse problems.

This model package provides one-dimensional and two-dimensional Poisson examples, together with a Burgers equation example using residual-based adaptive refinement (RAR).

Paper: Gradient-enhanced physics-informed neural networks for forward and inverse PDE problems  
https://doi.org/10.1016/j.cma.2022.114823

# Model Description

gPINNs use automatic differentiation to compute both PDE residuals and their coordinate gradients, incorporating both as training constraints. The two-dimensional Poisson example applies a hard-boundary output transformation, while the Burgers example uses RAR to add collocation points progressively in high-residual regions.

# Use Cases

| Use Case | Description |
| :---: | :--- |
| One-dimensional Poisson equation | Validate joint training with residual-gradient constraints and boundary loss |
| Two-dimensional Poisson equation | Solve a homogeneous Dirichlet boundary-value problem using a hard-boundary output transformation |
| Burgers equation | Combine higher-order automatic differentiation with RAR in high-residual regions |
| Pipeline validation | Validate training, inference, and plotting with the bundled data and pretrained weights |

# 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 inference and small-scale pipeline validation, but full training will be slow.
- DCU users must install DTK and a PyTorch environment compatible with the target cluster.

### Download the Model Package

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

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

The one- and two-dimensional Poisson examples construct training and evaluation data from analytical solutions; the Burgers example uses the bundled reference solution `data/Burgers.npz`. Data and training parameters can be adjusted in `conf/config.yaml`.

### Training

To train all examples:

```bash
python scripts/train.py --case all
```

Alternatively, train an individual example with `--case 1d`, `--case 2d`, or `--case burgers`. The `--epochs` and `--nf` options override the defaults for the selected example; `--lbfgs-iters` applies only to the one-dimensional Poisson case, `--rar-rounds` controls the number of RAR rounds for the Burgers case, and `--quick` skips RAR for rapid pipeline validation.

### Model Weights

This model package provides pretrained weights for the one-dimensional Poisson, two-dimensional Poisson, and Burgers equation examples in the `weight/` directory.

### Inference, Evaluation, and Visualization

The model package provides weights for validating all three examples. Run:

```bash
python scripts/inference.py --case all
```

The script reports the relative L2 error for each example and saves prediction visualizations under `result/`. Use `--case` to select an individual example. Model, data, and training parameters can all 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

- Yu, J., Lu, L., Meng, X., and Karniadakis, G. E. Gradient-enhanced physics-informed neural networks for forward and inverse PDE problems. Computer Methods in Applied Mechanics and Engineering, 393, 114823, 2022.
- This model package is released under the Apache-2.0 license and retains attribution to the original paper and data sources.