From 1c0323c272832f3479ce2ed0a8148d362da3d74d Mon Sep 17 00:00:00 2001 From: Nicola Demo Date: Mon, 17 Jul 2023 18:51:21 +0200 Subject: [PATCH] Update README.md --- README.md | 338 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 191 insertions(+), 147 deletions(-) diff --git a/README.md b/README.md index ff118d7e..59f2cc8a 100644 --- a/README.md +++ b/README.md @@ -1,64 +1,171 @@ -

- - Physics-Informed Neural networks for Advanced modeling - -

-

- - Software License - - - PyPI version - - - Build Status - - - + + + +

+ +[![PyPi][pypi-shield]][pypi-url] +[![PyPi][pypiversion-shield]][pypi-url] +[![PyPi][downloads-shield]][downloads-url] +[![License][license-shield]][license-url] + +
+ + + + + + + +[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/zenml/ + +[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 + +[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge&logo=linkedin&colorB=555 + + + +[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 + + +
+
+ + ZenML Logo + + +

Solve equations, intuitively.

+ +

+ A simple framework to solve difficult problems with neural networks. +
+ Explore the docs » +
+ +
+ + +

+
+ +
+ 🏁 Table of Contents +
    +
  1. Introduction
    2. +
  2. Quickstart
    3. +
  3. + Solve Your Differential Problem + +
    4. + +
  4. Contributing and Community
    5. + +
  5. License
    6. +
+
-**PINA**: Physics-Informed Neural networks for Advanced modeling - -## Table of contents -* [Description](#description) - * [Problem definition](#problem-definition) - * [Problem solution](#problem-solution) -* [Dependencies and installation](#dependencies-and-installation) - * [Installing via PIP](#installing-via-pip) - * [Installing from source](#installing-from-source) - - -* [Examples and Tutorials](#examples-and-tutorials) -* [References](#references) - -* [Authors and contributors](#authors-and-contributors) -* [How to contribute](#how-to-contribute) - * [Submitting a patch](#submitting-a-patch) -* [License](#license) - -## Description -**PINA** is a Python package providing an easy interface to deal with *physics-informed neural networks* (PINN) for the approximation of (differential, nonlinear, ...) functions. Based on Pytorch, PINA offers a simple and intuitive way to formalize a specific problem and solve it using PINN. 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. +
-

- - PINA interface for solving problems. - -

+# 🤖 Introduction + +🤹 PINA is a Python package providing an easy interface to deal with *physics-informed neural networks* (PINN) for the approximation of (differential, nonlinear, ...) functions. Based on Pytorch, PINA offers a simple and intuitive way to formalize a specific problem and solve it using PINN. +- 👨‍💻 Formulate your differential problem in few lines of code, just translating the mathematical equations into Python -#### Physics-informed neural network -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"*, such framework aims to solve problems in a continuous and nonlinear settings. +- 📄 Training your neural network in order to solve the problem + +- 🚀 Use the model to visualize and analyze the solution! + + +
+ +# 🤸 Quickstart + +[Install PINA](https://mathlab.github.io/PINA/_rst/installation.html) via +[PyPI](https://pypi.org/project/pina-mathlab/). Python 3 is required: + +```bash +pip install "pina-mathlab" +``` +
+ +# 🖼️ Solve Your Differential Problem + +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. + +## 🔋 1. Formulate the Problem -#### Problem definition 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. Consider: -$$\begin{cases} \Delta u = \sin(\pi x)\sin(\pi y)\quad& \text{in} \\ D \\\\ u = 0& \text{on} \\ \partial D \end{cases}$$ +$$ +\begin{cases} +\Delta u = \sin(\pi x)\sin(\pi y)\quad& \text{in}\, D \\ +u = 0& \text{on}\, \partial D \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: @@ -86,7 +193,7 @@ class Poisson(SpatialProblem): } ``` -#### Problem solution +## 👨‍🍳 2. Solve the 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. ```python @@ -108,68 +215,35 @@ After the training we can infer our model, save it or just plot the PINN approxi

Poisson approximation

+
+ -To install the package just type: -```bash -> pip install -e . -``` +# 🙌 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. - - - - - - - - - - - - - - - - - - -## Examples and Tutorials -The directory `Examples` contains some examples showing Poisson and Burgers problems solved in the PINN context. - -### References -To implement the package we follow these works: - -* Raissi, Maziar, Paris Perdikaris, and George E. Karniadakis. - *Physics-informed neural networks: A deep learning framework for solving - forward and inverse problems involving nonlinear partial differential - equations.* Journal of Computational Physics 378 (2019): 686-707. - - -## Authors and contributors -We warmly thank all the contributors that have supported PINA! +We warmly thank all the contributors that have supported PINA so far: @@ -178,48 +252,18 @@ We warmly thank all the contributors that have supported PINA! Made with [contrib.rocks](https://contrib.rocks). -## How to contribute -We'd love to accept your patches and contributions to this project. There are just a few small guidelines you need to follow. - -### Submitting a patch - - 1. It's generally best to start by opening a new issue describing the bug or - feature you're intending to fix. Even if you think it's relatively minor, - it's helpful to know what people are working on. Mention in the initial - issue that you are planning to work on that bug or feature so that it can - be assigned to you. - - 2. Follow the normal process of [forking][] the project, and setup a new - branch to work in. It's important that each group of changes be done in - separate branches in order to ensure that a pull request only includes the - commits related to that bug or feature. - - 3. To ensure properly formatted code, please make sure to use 4 - spaces to indent the code. The easy way is to run on your bash the provided - script: ./code_formatter.sh. You should also run [pylint][] over your code. - It's not strictly necessary that your code be completely "lint-free", - but this will help you find common style issues. - - 4. Any significant changes should almost always be accompanied by tests. The - project already has good test coverage, so look at some of the existing - tests if you're unsure how to go about it. We're using [coveralls][] that - is an invaluable tools for seeing which parts of your code aren't being - exercised by your tests. - - 5. Do your best to have [well-formed commit messages][] for each change. - This provides consistency throughout the project, and ensures that commit - messages are able to be formatted properly by various git tools. - - 6. Finally, push the commits to your fork and submit a [pull request][]. Please, - remember to rebase properly in order to maintain a clean, linear git history. + -## License +# 📜 License -See the [LICENSE](LICENSE.rst) file for license rights and limitations (MIT). +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.