folivo/PINA
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

new readme

Browse Source
This commit is contained in:
Dario Coscia
2025-04-22 10:31:06 +02:00
committed by Dario Coscia
parent 05d6913e04
commit 7e403acf58
4 changed files with 155 additions and 243 deletions
Download Patch File Download Diff File Expand all files Collapse all files

398
README.md
View File

@@ -1,288 +1,200 @@
<!-- PROJECT SHIELDS -->
<!-- <!--
*** I'm using markdown "reference style" links for readability. Copyright Contributors to the Pyro project.
*** Reference links are enclosed in brackets [ ] instead of parentheses ( ).
*** See the bottom of this document for the declaration of the reference variables SPDX-License-Identifier: Apache-2.0
*** for contributors-url, forks-url, etc. This is an optional, concise syntax you may use.
*** https://www.markdownguide.org/basic-syntax/#reference-style-links
--> -->
<div align="center"> <table>
<tr>
[![Docs][docs-shield]][docs-url] <td>
[![PyPi][pypiversion-shield]][pypi-url] <a href="https://github.com/mathLab/PINA/raw/master/readme/pina_logo.png">
[![PyPi][pypi-shield]][pypi-url] <img src="https://github.com/mathLab/PINA/raw/master/readme/pina_logo.png"
alt="PINA logo"
[![License][license-shield]][license-url] style="width: 220px; aspect-ratio: 1 / 1; object-fit: contain;">
[![PyPi][downloads-shield]][downloads-url] </a>
[![Joss][joss-shield]][joss-url] </td>
<td>
</div> <h2 style="margin-left: 20px; font-size: 1.8rem; line-height: 1.2;">
<!-- [![Contributors][contributors-shield]][contributors-url] --> Solving Scientific Problems with Machine Learning, Intuitively
<!-- [![Build][build-shield]][build-url] --> </h2>
<!-- [![CodeCov][codecov-shield]][codecov-url] --> </td>
</tr>
<!-- MARKDOWN LINKS & IMAGES --> </table>
<!-- https://www.markdownguide.org/basic-syntax/#reference-style-links -->
[docs-shield]: https://img.shields.io/badge/PINA-docs-blue?style=for-the-badge
[docs-url]: https://mathlab.github.io/PINA/
[pypi-shield]: https://img.shields.io/pypi/pyversions/pina-mathlab?style=for-the-badge
[pypi-url]: https://pypi.org/project/pina-mathlab/
[pypiversion-shield]: https://img.shields.io/pypi/v/pina-mathlab?style=for-the-badge
[downloads-shield]: https://img.shields.io/pypi/dm/pina-mathlab?style=for-the-badge
[downloads-url]: https://pypi.org/project/pina-mathlab/
[codecov-shield]: https://img.shields.io/codecov/c/gh/zenml-io/zenml?style=for-the-badge
[codecov-url]: https://codecov.io/gh/zenml-io/zenml
[contributors-shield]: https://img.shields.io/github/contributors/zenml-io/zenml?style=for-the-badge
[contributors-url]: https://github.com/othneildrew/Best-README-Template/graphs/contributors
[license-shield]: https://img.shields.io/github/license/mathLab/pina?style=for-the-badge
[license-url]: https://github.com/mathLab/PINA/blob/main/LICENSE.rst
[joss-shield]: https://img.shields.io/badge/JOSS-10.21105/joss.05352-red?style=for-the-badge
[joss-url]: https://joss.theoj.org/papers/10.21105/joss.05352
[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge&logo=linkedin&colorB=555
<!-- [linkedin-url]: https://www.linkedin.com/company/zenml/
[twitter-shield]: https://img.shields.io/twitter/follow/zenml_io?style=for-the-badge
[twitter-url]: https://twitter.com/zenml_io -->
[slack-shield]: https://img.shields.io/badge/-Slack-black.svg?style=for-the-badge&logo=linkedin&colorB=555
[slack-url]: https://zenml.io/slack-invite
[build-shield]: https://img.shields.io/github/workflow/status/zenml-io/zenml/Build,%20Lint,%20Unit%20&%20Integration%20Test/develop?logo=github&style=for-the-badge
[build-url]: https://github.com/zenml-io/zenml/actions/workflows/ci.yml
<!-- PROJECT LOGO -->
<br />
<div align="center">
<a href="https://zenml.io">
<img alt="ZenML Logo" src="https://github.com/mathLab/PINA/raw/master/readme/pina_logo.png" alt="Logo" width="200">
</a>
<h3 align="center">Solve equations, intuitively.</h3>
<p align="center">
A simple framework to solve difficult problems with neural networks.
<br />
<a href="https://mathlab.github.io/PINA/"><strong>Explore the docs »</strong></a>
<br />
<!-- <div align="center">
Join our <a href="https://zenml.io/slack-invite" target="_blank">
<img width="25" src="https://cdn3.iconfinder.com/data/icons/logos-and-brands-adobe/512/306_Slack-512.png" alt="Slack"/>
<b>Slack Community</b> </a> and be part of the ZenML family.
</div> -->
<br />
<!-- <a href="https://zenml.io/features">Features</a>
·
<a href="https://zenml.io/roadmap">Roadmap</a>
·
<a href="https://github.com/zenml-io/zenml/issues">Report Bug</a>
·
<a href="https://zenml.io/discussion">Vote New Features</a>
·
<a href="https://blog.zenml.io/">Read Blog</a>
·
<a href="#-meet-the-team">Meet the Team</a> -->
<!-- <br />
🎉 Version 0.41.0 is out. Check out the release notes
<a href="https://github.com/zenml-io/zenml/releases">here</a>.
<br />
<br />
<a href="https://www.linkedin.com/company/zenml/">
<img src="https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge&logo=linkedin&colorB=555" alt="Logo">
</a>
<a href="https://twitter.com/zenml_io">
<img src="https://img.shields.io/badge/-Twitter-black.svg?style=for-the-badge&logo=twitter&colorB=555" alt="Logo">
</a>
<a href="https://www.youtube.com/c/ZenML">
<img src="https://img.shields.io/badge/-YouTube-black.svg?style=for-the-badge&logo=youtube&colorB=555" alt="Logo">
</a> -->
</p>
</div>
<!-- TABLE OF CONTENTS -->
<details>
<summary>🏁 Table of Contents</summary>
<ol>
<li><a href="#-introduction">Introduction</a></li>
<li><a href="#-quickstart">Quickstart</a></li>
<li>
<a href="#%EF%B8%8F-solve-your-differential-problem">Solve Your Differential Problem</a>
<ul>
<li><a href="#-1-formulate-the-problem">Formulate the Problem</a></li>
<li><a href="#-2-solve-the-problem">Solve the Problem</a></li>
</ul>
</li>
<!-- <li><a href="#-roadmap">Roadmap</a></li> -->
<li><a href="#-contributing-and-community">Contributing and Community</a></li>
<!-- <li><a href="#-getting-help">Getting Help</a></li> -->
<li><a href="#-license">License</a></li>
</ol>
</details>
<br />
# 🤖 Introduction
🤹 PINA is an open-source Python library providing an intuitive interface for solving differential equations using PINNs, NOs or both together. Based on [PyTorch](https://pytorch.org/) and [PyTorchLightning](https://lightning.ai/docs/pytorch/stable/), PINA offers a simple and intuitive way to formalize a specific (differential) problem and solve it using neural networks . The approximated solution of a differential equation can be implemented using PINA in a few lines of code thanks to the intuitive and user-friendly interface.
- 👨‍💻 Formulate your differential problem in few lines of code, just translating the mathematical equations into Python
- 📄 Training your neural network in order to solve the problem
- 🚀 Use the model to visualize and analyze the solution!
<br> -----------------------------------------
# 🤸 Quickstart [![pages-build-deployment](https://github.com/mathLab/PINA/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/mathLab/PINA/actions/workflows/pages/pages-build-deployment)
[![Version](https://img.shields.io/pypi/v/pina-mathlab?label=version&logo=pypi)](https://pypi.org/project/pina-mathlab/)
[![Downloads](https://img.shields.io/pypi/dm/pina-mathlab?label=downloads&logo=pypi)](https://pypi.org/project/pina-mathlab/)
[![JOSS](https://img.shields.io/badge/JOSS-10.21105/JOSS.05352-blue?logo=open-access)](https://joss.theoj.org/papers/10.21105/joss.05352)
[![LICENSE](https://img.shields.io/github/license/mathLab/PINA)](https://github.com/mathLab/PINA/blob/main/LICENSE.rst)
[Install PINA](https://mathlab.github.io/PINA/_rst/installation.html) via
[PyPI](https://pypi.org/project/pina-mathlab/). Python 3 is required:
```bash [Getting Started](https://github.com/mathLab/PINA/tree/master/tutorials#pina-tutorials) |
[Documentation](https://mathlab.github.io/PINA/) |
[Contributing](https://github.com/mathLab/PINA/blob/master/CONTRIBUTING.md)
**PINA** is an open-source Python library designed to simplify and accelerate the development of Scientific Machine Learning (SciML) solutions. Built on top of [PyTorch](https://pytorch.org/), [PyTorch Lightning](https://lightning.ai/docs/pytorch/stable/), and [PyTorch Geometric](https://pytorch-geometric.readthedocs.io/en/latest/), PINA provides an intuitive framework for defining, experimenting with, and solving complex problems using Neural Networks, Physics-Informed Neural Networks (PINNs), Neural Operators, and more.
- **Modular Architecture**: Designed with modularity in mind and relying on powerful yet composable abstractions, PINA allows users to easily plug, replace, or extend components, making experimentation and customization straightforward.
- **Scalable Performance**: With native support for multi-device training, PINA handles large datasets efficiently, offering performance close to hand-crafted implementations with minimal overhead.
- **Highly Flexible**: Whether you're looking for full automation or granular control, PINA adapts to your workflow. High-level abstractions simplify model definition, while expert users can dive deep to fine-tune every aspect of the training and inference process.
## Installation
### Installing a stable PINA release
**Install using pip:**
```sh
pip install "pina-mathlab" pip install "pina-mathlab"
``` ```
<br>
# 🖼️ Solve Your Differential Problem **Install from source:**
```sh
git clone https://github.com/mathLab/PINA
cd PINA
git checkout master
pip install .
```
PINN is a novel approach that involves neural networks to solve supervised learning tasks while respecting any given law of physics described by general nonlinear differential equations. Proposed in [Physics-informed neural networks: A deep learning framework for solving forward and inverse problems involving nonlinear partial differential equations](https://www.sciencedirect.com/science/article/pii/S0021999118307125?casa_token=p0BAG8SoAbEAAAAA:3H3r1G0SJ7IdXWm-FYGRJZ0RAb_T1qynSdfn-2VxqQubiSWnot5yyKli9UiH82rqQWY_Wzfq0HVV), such framework aims to solve problems in a continuous and nonlinear settings. **Install with extra packages:**
Differenlty from PINNs, Neural Operators learn differential operators using supervised learning strategies. By learning the differential operator, the neural network is able to generalize across different instances of the differential equations (e.g. different forcing terms), without the need of re-training. To install extra dependencies required to run tests or tutorials directories, please use the following command:
```sh
pip install "pina-mathlab[extras]"
```
Available extras include:
* `dev` for development purpuses, use this if you want to [Contribute](https://github.com/mathLab/PINA/blob/master/CONTRIBUTING.md#contributing-to-pina).
* `test` for running test locally.
* `doc` for building documentation locally.
* `tutorial` for running [Tutorials](https://github.com/mathLab/PINA/tree/master/tutorials#pina-tutorials).
PINA can be used for PINN learning, Neural Operator learning, or both. Below is a simple example of PINN learning, for Neural Operator or more on PINNs look at our [tutorials](https://github.com/mathLab/PINA/tree/v0.1/tutorials) ## Quick Tour for New Users
Solving a differential problem in **PINA** follows the *four steps pipeline*:
## 🔋 1. Formulate the Problem 1. Define the problem to be solved with its constraints using the [Problem API](https://mathlab.github.io/PINA/_rst/_code.html#problems).
First step is formalization of the problem in the PINA framework. We take as example here a simple Poisson problem, but PINA is already able to deal with **multi-dimensional**, **parametric**, **time-dependent** problems. 2. Design your model using PyTorch, or for graph-based problems, leverage PyTorch Geometric to build Graph Neural Networks. You can also import models directly from the [Model API](https://mathlab.github.io/PINA/_rst/_code.html#models).
Consider:
3. Select or build a Solver for the Problem, e.g., supervised solvers, or physics-informed (e.g., PINN) solvers. [PINA Solvers](https://mathlab.github.io/PINA/_rst/_code.html#solvers) are modular and can be used as-is or customized.
4. Train the model using the [Trainer API](https://mathlab.github.io/PINA/_rst/trainer.html) class, built on PyTorch Lightning, which supports efficient, scalable training with advanced features.
Do you want to learn more about it? Look at our [Tutorials](https://github.com/mathLab/PINA/tree/master/tutorials#pina-tutorials).
### Solve Data Driven Problems
Data driven modelling aims to learn a function that given some input data gives an output (e.g. regression, classification, ...). In PINA you can easily do this by:
```python
from pina import Trainer
from pina.model import FeedForward
from pina.solver import SupervisedSolver
from pina.problem.zoo import SupervisedProblem
input_tensor = torch.rand((10, 1))
output_tensor = input_tensor.pow(3)
# Step 1. Define problem
problem = SupervisedProblem(input_tensor, target_tensor)
# Step 2. Design model (you can use your favourite torch.nn.Module in here)
model = FeedForward(input_dimensions=1, output_dimensions=1, layers=[64, 64])
# Step 3. Define Solver
solver = SupervisedSolver(problem, model)
# Step 4. Train
trainer = Trainer(solver, max_epochs=1000, accelerator='gpu')
trainer.train()
```
### Solve Physics Informed Problems
Physics-informed modeling aims to learn functions that not only fit data, but also satisfy known physical laws, such as differential equations or boundary conditions. For example, the following differential problem:
$$ $$
\begin{cases} \begin{cases}
\Delta u = \sin(\pi x)\sin(\pi y)\quad& \text{in } D \\ \frac{d}{dx}u(x) &= u(x) \quad x \in(0,1)\\
u = 0& \text{in } \partial D \end{cases}$$ u(x=0) &= 1
\end{cases}
$$
where $D = [0, 1]^2$ is a square domain, $u$ the unknown field, and $\partial D = \Gamma_1 \cup \Gamma_2 \cup \Gamma_3 \cup \Gamma_4$, where $\Gamma_i$ are the boundaries of the square for $i=1,\cdots,4$. The translation in PINA code becomes a new class containing all the information about the domain, about the `conditions` and nothing more: in PINA, can be easily implemented by:
```python ```python
class Poisson(SpatialProblem): from pina import Trainer, Condition
output_variables = ['u'] from pina.problem import SpatialProblem
spatial_domain = CartesianDomain({'x': [0, 1], 'y': [0, 1]}) from pina.operator import grad
from pina.solver import PINN
from pina.model import FeedForward
from pina.domain import CartesianDomain
from pina.equation import Equation, FixedValue
def laplace_equation(input_, output_): def ode_equation(input_, output_):
force_term = (torch.sin(input_.extract(['x'])*torch.pi) * u_x = grad(output_, input_, components=["u"], d=["x"])
torch.sin(input_.extract(['y'])*torch.pi)) u = output_.extract(["u"])
laplacian_u = laplacian(output_, input_, components=['u'], d=['x', 'y']) return u_x - u
return laplacian_u - force_term
# build the problem
class SimpleODE(SpatialProblem):
output_variables = ["u"]
spatial_domain = CartesianDomain({"x": [0, 1]})
domains = { domains = {
'g1': CartesianDomain({'x': [0, 1], 'y': 1}), "x0": CartesianDomain({"x": 0.0}),
'g2': CartesianDomain({'x': [0, 1], 'y': 0}), "D": CartesianDomain({"x": [0, 1]}),
'g3': CartesianDomain({'x': 1, 'y': [0, 1]}),
'g4': CartesianDomain({'x': 0, 'y': [0, 1]}),
'D': CartesianDomain({'x': [0, 1], 'y': [0, 1]})
} }
conditions = { conditions = {
'gamma1': Condition(domain='g1', equation=FixedValue(0.)), "bound_cond": Condition(domain="x0", equation=FixedValue(1.0)),
'gamma2': Condition(domain='g2', equation=FixedValue(0.)), "phys_cond": Condition(domain="D", equation=Equation(ode_equation)),
'gamma3': Condition(domain='g3', equation=FixedValue(0.)),
'gamma4': Condition(domain='g4', equation=FixedValue(0.)),
'D': Condition(domain='D', equation=Equation(laplace_equation)),
} }
```
## 👨‍🍳 2. Solve the Problem # Step 1. Define problem
After defining it, we want of course to solve such a problem. The only things we need is a `model`, in this case a feed forward network, and some samples of the domain and boundaries, here using a Cartesian grid. In these points we are going to evaluate the residuals, which is nothing but the loss of the network. We optimize the `model` using a solver, here a `PINN`. Other types of solvers are possible, such as supervised solver or GAN based solver. problem = SimpleODE()
# Step 2. Design model (you can use your favourite torch.nn.Module in here)
```python model = FeedForward(input_dimensions=1, output_dimensions=1, layers=[64, 64])
# make model + solver + trainer # Step 3. Define Solver
model = FeedForward( solver = PINN(problem, model)
layers=[10, 10], # Step 4. Train
func=Softplus, trainer = Trainer(solver, max_epochs=1000, accelerator='gpu')
output_dimensions=len(problem.output_variables),
input_dimensions=len(problem.input_variables)
)
optimizer = TorchOptimizer(torch.optim.Adam, lr=0.006, weight_decay=1e-8)
pinn = PINN(problem, model, optimizer=optimizer)
trainer = Trainer(pinn, max_epochs=1000, accelerator='gpu', enable_model_summary=False, batch_size=8)
# train
trainer.train() trainer.train()
``` ```
After the training we can infer our model, save it or just plot the approximation. Below the graphical representation of the PINN approximation, the analytical solution of the problem and the absolute error, from left to right.
<p align="center">
<img alt="Poisson approximation" src="readme/poisson_plot.png" width="100%" />
</p>
<br>
<!-- # 🗺 Roadmap ## Application Programming Interface
Here's a quick look at PINA's main module. For a better experience and full details, check out the [documentation](https://mathlab.github.io/PINA/).
ZenML is being built in public. The [roadmap](https://zenml.io/roadmap) is a <a href="https://github.com/mathLab/PINA/readme/PINA_API.png">
regularly updated source of truth for the ZenML community to understand where <img src="./readme/PINA_API.png" />
the product is going in the short, medium, and long term. </a>
ZenML is managed by a [core team](https://zenml.io/company#CompanyTeam) of ## Contributing and Community
developers that are responsible for making key decisions and incorporating
feedback from the community. The team oversees feedback via various channels,
and you can directly influence the roadmap as follows:
- Vote on your most wanted feature on our [Discussion We would love to develop PINA together with our community! Best way to get started is to select any issue from the [`good-first-issue` label](https://github.com/mathLab/PINA/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22). If you would like to contribute, please review our [Contributing Guide](CONTRIBUTING.md) for all relevant details.
board](https://zenml.io/discussion).
- Start a thread in our [Slack channel](https://zenml.io/slack-invite).
- [Create an issue](https://github.com/zenml-io/zenml/issues/new/choose) on our
Github repo.
-->
# 🙌 Contributing and Community
We would love to develop PINA together with our community! Best way to get
started is to select any issue from the [`good-first-issue`
label](https://github.com/mathLab/PINA/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22). If you
would like to contribute, please review our [Contributing
Guide](CONTRIBUTING.md) for all relevant details.
We warmly thank all the contributors that have supported PINA so far: We warmly thank all the contributors that have supported PINA so far:
<a href="https://github.com/mathLab/PINA/graphs/contributors"> <a href="https://github.com/mathLab/PINA/graphs/contributors">
<img src="https://contrib.rocks/image?repo=mathLab/PINA" /> <img src="https://contrib.rocks/image?repo=mathLab/PINA"
alt="Contributors"
style="max-width: 100%; height: auto; display: block;">
</a> </a>
Made with [contrib.rocks](https://contrib.rocks). Made with [contrib.rocks](https://contrib.rocks).
## Citation
If **PINA** has been significant in your research, and you would like to acknowledge the project in your academic publication, we suggest citing the following paper:
<!-- # 🆘 Getting Help ```
Coscia, D., Ivagnes, A., Demo, N., & Rozza, G. (2023). Physics-Informed Neural networks for Advanced modeling. Journal of Open Source Software, 8(87), 5352.
```
The first point of call should Or in BibTex format
be [our Slack group](https://zenml.io/slack-invite/). ```
Ask your questions about bugs or specific use cases, and someone from @article{coscia2023physics,
the [core team](https://zenml.io/company#CompanyTeam) will respond. title={Physics-Informed Neural networks for Advanced modeling},
Or, if you author={Coscia, Dario and Ivagnes, Anna and Demo, Nicola and Rozza, Gianluigi},
prefer, [open an issue](https://github.com/zenml-io/zenml/issues/new/choose) on journal={Journal of Open Source Software},
our GitHub repo. --> volume={8},
number={87},
pages={5352},
# 📜 License year={2023}
}
PINA is distributed under the terms of the MIT License. ```
A complete version of the license is available in the [LICENSE.rst](LICENSE.rst) file in this repository. Any contribution made to this project will be licensed under the MIT License.

BIN
readme/API_color.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 121 KiB

BIN
readme/PINA_API.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 234 KiB

BIN
readme/poisson_plot.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 44 KiB