From feae72991804193ddd33340ee1cb91178826fe8d Mon Sep 17 00:00:00 2001
From: Nicola Demo <demo.nicola@gmail.com>
Date: Thu, 17 Feb 2022 12:06:46 +0100
Subject: [PATCH] Update README.md

---
 README.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 59 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index ca92662..5eb62aa 100644
--- a/README.md
+++ b/README.md
@@ -29,6 +29,8 @@
 
 ## 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)
@@ -45,10 +47,63 @@
 * [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.
+**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.
+
+#### 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.
+
+#### 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} 
+\nabla u = \sin(\pi x)  \sin(\pi y) & \quad\text{in}\, D,\\
+u = 0 &\quad\text{on}\, \Gamma_1 \cup\Gamma_2 \cup\Gamma_3 \cup\Gamma_4,  \\
+\end{cases}
+$$
+where $D= [0, 1]^2$ is a square domain, $\Gamma_1 \cup\Gamma_2 \cup\Gamma_3 \cup\Gamma_4$ are the boundaries and $u$ the unknown field. The translation in PINA code becomes a new class containing all the information about the domain, about the `conditions` and nothing more:
+```python
+class Poisson(SpatialProblem):
+	spatial_variables = ['x', 'y']
+	output_variables = ['u']
+	domain = Span({'x': [0, 1], 'y': [0, 1]})
+
+	def laplace_equation(input_, output_):
+		force_term = (torch.sin(input_['x']*torch.pi) *
+		              torch.sin(input_['y']*torch.pi))
+		return nabla(output_['u'], input_).flatten() - force_term
+
+	def nil_dirichlet(input_, output_):
+		value = 0.0
+		return output_['u'] - value
+
+	conditions = {
+		'gamma1': Condition(Span({'x': [-1, 1], 'y':  1}), nil_dirichlet),
+		'gamma2': Condition(Span({'x': [-1, 1], 'y': -1}), nil_dirichlet),
+		'gamma3': Condition(Span({'x':  1, 'y': [-1, 1]}), nil_dirichlet),
+		'gamma4': Condition(Span({'x': -1, 'y': [-1, 1]}), nil_dirichlet),
+		'D': Condition(Span({'x': [-1, 1], 'y': [-1, 1]}), laplace_equation),
+	}
+```
+
+#### Problem solution
+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
+poisson_problem = Poisson()
+
+model = FeedForward(layers=[10, 10],
+                    output_variables=poisson_problem.output_variables,
+                    input_variables=poisson_problem.input_variables)
+
+pinn = PINN(poisson_problem, model, lr=0.003, regularizer=1e-8)
+pinn.span_pts(20, 'grid', ['D'])
+pinn.span_pts(20, 'grid', ['gamma1', 'gamma2', 'gamma3', 'gamma4'])
+pinn.train(1000, 100)
+
+plotter = Plotter()
+plotter.plot(pinn)
+```
+After the training we can infer our model, save it or just plot the PINN approximation.
 
 
 ## Dependencies and installation