PaddleScience: a PaddlePaddle SDK for physics-informed and data-driven scientific computing

What PaddleScience solves, and for whom

Writing a physics-informed neural network from scratch means rebuilding the same scaffolding every time: a sampling strategy over the problem domain, a way to express Dirichlet, Neumann and Robin boundary conditions, a residual term that differentiates the network output with respect to its inputs, and a training loop that balances those losses. PaddleScience packages that scaffolding on top of PaddlePaddle, which supplies the automatic differentiation, including the higher-order derivatives that residual terms need.

The README describes three solving modes: physics-driven, data-driven, and a combination of the two. The first covers unsupervised PINN-style training where the loss is the PDE residual itself. The second covers supervised learning on simulation or experimental data. The third mixes them. The intended reader is a researcher or engineer in fluid mechanics, structural analysis, meteorology or applied mathematics who already knows the equation they want to solve and does not want to write the solver infrastructure around it.

The case list makes the scope concrete. It spans Helmholtz, Allen-Cahn, Laplace, Burgers, Lorenz, Rossler, Volterra integral equations, fractional PDEs, optical solitons, domain decomposition with XPINN, symbolic regression, and engineering cases such as car surface drag prediction with Transolver and DrivAerNet. That breadth is the strongest argument for the library: the same abstractions are reused across very different equation families.

How the solver is assembled: Hydra config, equations, geometry, constraints

The repository layout puts the library under ppsci/ and every runnable case under examples/, one directory per case. Configuration is handled by Hydra, which the project advertises in its badge row. That choice explains the shape of a typical run: you do not write a training script, you write a YAML file that names a model, a geometry, a set of constraints and a solver, and Hydra composes the run.

The pieces visible in the feature list are the ones you would expect from that design. Geometry supports simple shapes and STL files, with sampling and boolean operations, so a domain can be carved out of CAD data. Boundary conditions include Dirichlet, Neumann and Robin plus custom ones. Equations can be expressed and combined through sympy, which means the residual is declared symbolically rather than hand-written as tensor operations. Results can be visualized and logs saved in a structured form. The README also mentions experiment source tracking and one-command parallel experiment launch, which matter when a study requires a sweep rather than a single run.

The data flow is therefore: config selects geometry and sampling points, the equation module builds a symbolic residual, the model produces field values at those points, autodiff differentiates them, constraints assemble the loss terms, and the solver drives optimization. Whether you find this pleasant depends on how much you like configuration over code. For a parameter sweep it is a clear win. For a one-off equation that does not resemble any existing case, you will spend time reading ppsci source to find the right extension point, because the README does not document the extension API.

Installing PaddleScience and running a first case

The distribution name on PyPI is paddlesci, not paddlescience, and the same name is used on the Anaconda channel PaddleScience. The package requires Python 3.8 or newer. Note that PaddleScience is a wrapper, so PaddlePaddle itself must be present in the environment; the install documentation linked from the README covers that step, and the README does not inline the PaddlePaddle install command.

A minimal install from PyPI looks like this:

pip install paddlesci

After installation the module is imported as ppsci. The conda route is also published:

conda install -c paddlescience paddlescience

The library's own dependencies are pinned in requirements.txt. Two pins are worth noticing before you build an environment: numpy is constrained to >=1.20.0,<2.0.0, and scikit-learn is constrained to <1.5.0. If your project already depends on numpy 2.x, the resolver will either downgrade it or fail, and that is a decision to make deliberately rather than discover later.

For a first real run, the documented path is the quickstart page and then an example directory. The examples are not part of the installed package: pyproject.toml explicitly excludes examples*, docs*, test* and tools* from the wheel. You therefore clone the repository to get a runnable case, and run it from inside its example directory, since the Hydra configs live there. The README's example table links each case to its documentation page, and those pages are the authoritative source for the exact command per case; the README does not print a single canonical run command that applies to all of them.

Where PaddleScience gets in the way

The documentation is Chinese-first. The badges and the link block at the top of the README point to /zh-cn/latest/ paths, and the case descriptions are in Chinese. There is no English documentation site referenced. For a team that cannot read Chinese, the example source code becomes the primary reference, which is slower and error-prone for anything beyond the simplest case.

Release cadence is another constraint. The listed releases are v1.2.0 in November 2023, v1.3.0 in July 2024 and v1.4.0 in April 2025. That is roughly one release per year, with the last push to the develop branch on 2026-07-22. The repository is not archived, and commits continue, but anyone planning around a documented, versioned API should assume that breaking changes arrive in annual steps rather than in a predictable minor-version stream. The README does not document a deprecation policy.

Two further limits are structural. First, the library is bound to PaddlePaddle; if your group standardizes on PyTorch, adopting PaddleScience means adopting a second framework and its ecosystem. Second, the pyproject classifiers claim Production/Stable, but the README's own feature list ends with "more features are being developed", and the extension API for new equations is not described in the README. Treat the stability claim as a statement about the released cases, not about the interfaces you would build on.

PaddleScience compared with DeepXDE

DeepXDE is the natural comparison, and the README itself makes it: several cases in the PaddleScience table cite DeepXDE as the data source or project reference, including the Volterra integral equation and the DeepONet anti-derivative dataset. That tells you the two libraries cover overlapping ground.

The difference in approach is the backend. DeepXDE is framework-agnostic at the front end and can run on TensorFlow, PyTorch or JAX, which means your existing model code and GPU stack are more likely to be reusable. PaddleScience commits to PaddlePaddle and, in exchange, gets direct access to PaddlePaddle's automatic differentiation machinery and the surrounding PaddlePaddle tooling. If you are already in that ecosystem, PaddleScience removes a translation layer. If you are not, DeepXDE asks less of you.

The second difference is configuration style. PaddleScience leans on Hydra YAML for the whole run definition and ships a case library organized that way. DeepXDE is more commonly used as a Python API where the PDE is defined in code. Neither is better in the abstract: YAML makes sweeps and reproducibility easier, Python makes unusual equations easier. The deciding question is whether your problem resembles one of the twenty-odd documented cases. If it does, the config-driven route saves real time.

Licence and upgrade cost

PaddleScience is Apache-2.0, stated in both the LICENSE file and the pyproject metadata. For most research and commercial use that is a permissive licence with a patent grant and a requirement to preserve notices. This is not legal advice; if you redistribute a modified version, read the licence text and your own organization's policy rather than relying on a summary.

The upgrade cost is dominated by the dependency pins and the absence of a documented deprecation policy. Upgrading PaddleScience means upgrading PaddlePaddle alongside it, and the numpy<2.0.0 and scikit-learn<1.5.0 pins constrain the rest of your environment. If you keep PaddleScience in the same environment as other scientific Python code, an upgrade is an environment-wide event, not a package bump. Isolating it in its own virtual environment or container is the practical mitigation, and the repository does ship a docker/ directory for that purpose.

Editorial conclusion

PaddleScience fits research groups already inside the PaddlePaddle stack, or teams reproducing a case from its documented example list, since the library ships the equation, geometry, boundary condition and optimizer layers those cases need. It is a poor fit if your work depends on PyTorch-only models, on GPU hardware outside PaddlePaddle's supported builds, or on a documented API stability guarantee, because the documentation is Chinese-first and the release cadence has been roughly annual. Before committing, verify that the example closest to your problem runs end to end on your target device, and read the requirements pin on numpy, which is capped below 2.0.0.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. PaddlePaddle/PaddleScience on GitHub
3. Project website
4. README
5. Releases