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

Update Tutorials (#544)

Browse Source 
* update tutorials
* tutorial guidelines
* doc
This commit is contained in:
Dario Coscia
2025-04-23 16:19:07 +02:00
parent 7e403acf58
commit 29b14ee9b6
45 changed files with 6279 additions and 6726 deletions
Download Patch File Download Diff File Expand all files Collapse all files

149
tutorials/tutorial12/tutorial.ipynb vendored
View File

@@ -4,50 +4,37 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"# Tutorial: The `Equation` Class\n",
"# Tutorial: Introduction to PINA `Equation` class\n",
"\n",
"[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/mathLab/PINA/blob/master/tutorials/tutorial12/tutorial.ipynb)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"In this tutorial, we will show how to use the `Equation` Class in PINA. Specifically, we will see how use the Class and its inherited classes to enforce residuals minimization in PINNs."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Example: The Burgers 1D equation"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/mathLab/PINA/blob/master/tutorials/tutorial12/tutorial.ipynb)\n",
"\n",
"\n",
"In this tutorial, we will explore how to use the `Equation` class in **PINA**. We will focus on how to leverage this class, along with its inherited subclasses, to enforce residual minimization in **Physics-Informed Neural Networks (PINNs)**.\n",
"\n",
"By the end of this guide, you'll understand how to integrate physical laws and constraints directly into your model training, ensuring that the solution adheres to the underlying differential equations.\n",
"\n",
"\n",
"## Example: The Burgers 1D equation\n",
"We will start implementing the viscous Burgers 1D problem Class, described as follows:\n",
"\n",
"\n",
"$$\n",
"\\begin{equation}\n",
"\\begin{cases}\n",
"\\frac{\\partial u}{\\partial t} + u \\frac{\\partial u}{\\partial x} &= \\nu \\frac{\\partial^2 u}{ \\partial x^2}, \\quad x\\in(0,1), \\quad t>0\\\\\n",
"u(x,0) &= -\\sin (\\pi x)\\\\\n",
"u(x,t) &= 0 \\quad x = \\pm 1\\\\\n",
"u(x,0) &= -\\sin (\\pi x), \\quad x\\in(0,1)\\\\\n",
"u(x,t) &= 0, \\quad x = \\pm 1, \\quad t>0\\\\\n",
"\\end{cases}\n",
"\\end{equation}\n",
"$$\n",
"\n",
"where we set $ \\nu = \\frac{0.01}{\\pi}$.\n",
"\n",
"In the class that models this problem we will see in action the `Equation` class and one of its inherited classes, the `FixedValue` class. "
"In the class that models this problem we will see in action the `Equation` class and one of its inherited classes, the `FixedValue` class."
]
},
{
"cell_type": "code",
"execution_count": 1,
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
@@ -59,7 +46,7 @@
"except:\n",
" IN_COLAB = False\n",
"if IN_COLAB:\n",
" !pip install \"pina-mathlab\"\n",
" !pip install \"pina-mathlab[tutorial]\"\n",
"\n",
"import torch\n",
"\n",
@@ -68,7 +55,14 @@
"from pina.problem import SpatialProblem, TimeDependentProblem\n",
"from pina.equation import Equation, FixedValue\n",
"from pina.domain import CartesianDomain\n",
"from pina.operator import grad, laplacian"
"from pina.operator import grad, fast_grad, laplacian"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Let's begin by defining the Burgers equation and its initial condition as Python functions. These functions will take the model's `input` (spatial and temporal coordinates) and `output` (predicted solution) as arguments. The goal is to compute the residuals for the Burgers equation, which we will minimize during training."
]
},
{
@@ -79,7 +73,7 @@
"source": [
"# define the burger equation\n",
"def burger_equation(input_, output_):\n",
" du = grad(output_, input_)\n",
" du = fast_grad(output_, input_, components=[\"u\"], d=[\"x\"])\n",
" ddu = grad(du, input_, components=[\"dudx\"])\n",
" return (\n",
" du.extract([\"dudt\"])\n",
@@ -91,9 +85,32 @@
"# define initial condition\n",
"def initial_condition(input_, output_):\n",
" u_expected = -torch.sin(torch.pi * input_.extract([\"x\"]))\n",
" return output_.extract([\"u\"]) - u_expected\n",
" return output_.extract([\"u\"]) - u_expected"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Above we use the `grad` operator from `pina.operator` to compute the gradient. In PINA each differential operator takes the following inputs:\n",
"- `output_`: A tensor on which the operator is applied.\n",
"- `input_`: A tensor with respect to which the operator is computed.\n",
"- `components`: The names of the output variables for which the operator is evaluated.\n",
"- `d`: The names of the variables with respect to which the operator is computed.\n",
"\n",
"Each differential operator has its **fast** version, which performs no internal checks on input and output tensors. For these methods, the user is always required to specify both ``components`` and ``d`` as lists of strings.\n",
"\n",
"Let's define now the problem!\n",
"\n",
"> **👉 Do you want to learn more on Problems? Check the dedicated [tutorial](https://mathlab.github.io/PINA/tutorial16/tutorial.html) to learn how to build a Problem from scratch.**"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"class Burgers1D(TimeDependentProblem, SpatialProblem):\n",
"\n",
" # assign output/ spatial and temporal variables\n",
@@ -128,36 +145,29 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"The `Equation` class takes as input a function (in this case it happens twice, with `initial_condition` and `burger_equation`) which computes a residual of an equation, such as a PDE. In a problem class such as the one above, the `Equation` class with such a given input is passed as a parameter in the specified `Condition`. \n",
"\n",
"The `FixedValue` class takes as input a value of same dimensions of the output functions; this class can be used to enforce a fixed value for a specific condition, e.g. Dirichlet boundary conditions, as it happens for instance in our example.\n",
"The `FixedValue` class takes as input a value of the same dimensions as the output functions. This class can be used to enforce a fixed value for a specific condition, such as Dirichlet boundary conditions, as demonstrated in our example.\n",
"\n",
"Once the equations are set as above in the problem conditions, the PINN solver will aim to minimize the residuals described in each equation in the training phase. "
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Available classes of equations include also:\n",
"- `FixedGradient` and `FixedFlux`: they work analogously to `FixedValue` class, where we can require a constant value to be enforced, respectively, on the gradient of the solution or the divergence of the solution;\n",
"- `Laplace`: it can be used to enforce the laplacian of the solution to be zero;\n",
"- `SystemEquation`: we can enforce multiple conditions on the same subdomain through this class, passing a list of residual equations defined in the problem.\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Defining a new Equation class"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"`Equation` classes can be also inherited to define a new class. As example, we can see how to rewrite the above problem introducing a new class `Burgers1D`; during the class call, we can pass the viscosity parameter $\\nu$:"
"Once the equations are set as above in the problem conditions, the PINN solver will aim to minimize the residuals described in each equation during the training phase. \n",
"\n",
"### Available classes of equations:\n",
"- `FixedGradient` and `FixedFlux`: These work analogously to the `FixedValue` class, where we can enforce a constant value on the gradient or the divergence of the solution, respectively.\n",
"- `Laplace`: This class can be used to enforce that the Laplacian of the solution is zero.\n",
"- `SystemEquation`: This class allows you to enforce multiple conditions on the same subdomain by passing a list of residual equations defined in the problem.\n",
"\n",
"## Defining a new Equation class\n",
"`Equation` classes can also be inherited to define a new class. For example, we can define a new class `Burgers1D` to represent the Burgers equation. During the class call, we can pass the viscosity parameter $\\nu$:\n",
"\n",
"```python\n",
"class Burgers1D(Equation):\n",
" def __init__(self, nu):\n",
" self.nu = nu\n",
"\n",
" def equation(self, input_, output_):\n",
" ...\n",
"```\n",
"In this case, the `Burgers1D` class will inherit from the `Equation` class and compute the residual of the Burgers equation. The viscosity parameter $\\nu$ is passed when instantiating the class and used in the residual calculation. Let's see it in more details:"
]
},
{
@@ -239,17 +249,18 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"# What's next?"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Congratulations on completing the `Equation` class tutorial of **PINA**! As we have seen, you can build new classes that inherit `Equation` to store more complex equations, as the Burgers 1D equation, only requiring to pass the characteristic coefficients of the problem. \n",
"From now on, you can:\n",
"- define additional complex equation classes (e.g. `SchrodingerEquation`, `NavierStokeEquation`..)\n",
"- define more `FixedOperator` (e.g. `FixedCurl`)"
"## What's Next?\n",
"\n",
"Congratulations on completing the `Equation` class tutorial of **PINA**! As we've seen, you can build new classes that inherit from `Equation` to store more complex equations, such as the 1D Burgers equation, by simply passing the characteristic coefficients of the problem.\n",
"\n",
"From here, you can:\n",
"\n",
"- **Define Additional Complex Equation Classes**: Create your own equation classes, such as `SchrodingerEquation`, `NavierStokesEquation`, etc.\n",
"- **Define More `FixedOperator` Classes**: Implement operators like `FixedCurl`, `FixedDivergence`, and others for more advanced simulations.\n",
"- **Integrate Custom Equations and Operators**: Combine your custom equations and operators into larger systems for more complex simulations.\n",
"- **and many more!**: Explore for example different residual minimization techniques to improve the performance and accuracy of your models.\n",
"\n",
"For more resources and tutorials, check out the [PINA Documentation](https://mathlab.github.io/PINA/)."
]
}
],

188
tutorials/tutorial12/tutorial.py vendored
View File

@@ -1,188 +0,0 @@
#!/usr/bin/env python
# coding: utf-8
# # Tutorial: The `Equation` Class
#
# [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/mathLab/PINA/blob/master/tutorials/tutorial12/tutorial.ipynb)
# In this tutorial, we will show how to use the `Equation` Class in PINA. Specifically, we will see how use the Class and its inherited classes to enforce residuals minimization in PINNs.
# # Example: The Burgers 1D equation
# We will start implementing the viscous Burgers 1D problem Class, described as follows:
#
#
# $$
# \begin{equation}
# \begin{cases}
# \frac{\partial u}{\partial t} + u \frac{\partial u}{\partial x} &= \nu \frac{\partial^2 u}{ \partial x^2}, \quad x\in(0,1), \quad t>0\\
# u(x,0) &= -\sin (\pi x)\\
# u(x,t) &= 0 \quad x = \pm 1\\
# \end{cases}
# \end{equation}
# $$
#
# where we set $ \nu = \frac{0.01}{\pi}$.
#
# In the class that models this problem we will see in action the `Equation` class and one of its inherited classes, the `FixedValue` class.
# In[1]:
## routine needed to run the notebook on Google Colab
try:
import google.colab
IN_COLAB = True
except:
IN_COLAB = False
if IN_COLAB:
get_ipython().system('pip install "pina-mathlab"')
import torch
# useful imports
from pina import Condition
from pina.problem import SpatialProblem, TimeDependentProblem
from pina.equation import Equation, FixedValue
from pina.domain import CartesianDomain
from pina.operator import grad, laplacian
# In[2]:
# define the burger equation
def burger_equation(input_, output_):
du = grad(output_, input_)
ddu = grad(du, input_, components=["dudx"])
return (
du.extract(["dudt"])
+ output_.extract(["u"]) * du.extract(["dudx"])
- (0.01 / torch.pi) * ddu.extract(["ddudxdx"])
)
# define initial condition
def initial_condition(input_, output_):
u_expected = -torch.sin(torch.pi * input_.extract(["x"]))
return output_.extract(["u"]) - u_expected
class Burgers1D(TimeDependentProblem, SpatialProblem):
# assign output/ spatial and temporal variables
output_variables = ["u"]
spatial_domain = CartesianDomain({"x": [-1, 1]})
temporal_domain = CartesianDomain({"t": [0, 1]})
domains = {
"bound_cond1": CartesianDomain({"x": -1, "t": [0, 1]}),
"bound_cond2": CartesianDomain({"x": 1, "t": [0, 1]}),
"time_cond": CartesianDomain({"x": [-1, 1], "t": 0}),
"phys_cond": CartesianDomain({"x": [-1, 1], "t": [0, 1]}),
}
# problem condition statement
conditions = {
"bound_cond1": Condition(
domain="bound_cond1", equation=FixedValue(0.0)
),
"bound_cond2": Condition(
domain="bound_cond2", equation=FixedValue(0.0)
),
"time_cond": Condition(
domain="time_cond", equation=Equation(initial_condition)
),
"phys_cond": Condition(
domain="phys_cond", equation=Equation(burger_equation)
),
}
#
# The `Equation` class takes as input a function (in this case it happens twice, with `initial_condition` and `burger_equation`) which computes a residual of an equation, such as a PDE. In a problem class such as the one above, the `Equation` class with such a given input is passed as a parameter in the specified `Condition`.
#
# The `FixedValue` class takes as input a value of same dimensions of the output functions; this class can be used to enforce a fixed value for a specific condition, e.g. Dirichlet boundary conditions, as it happens for instance in our example.
#
# Once the equations are set as above in the problem conditions, the PINN solver will aim to minimize the residuals described in each equation in the training phase.
# Available classes of equations include also:
# - `FixedGradient` and `FixedFlux`: they work analogously to `FixedValue` class, where we can require a constant value to be enforced, respectively, on the gradient of the solution or the divergence of the solution;
# - `Laplace`: it can be used to enforce the laplacian of the solution to be zero;
# - `SystemEquation`: we can enforce multiple conditions on the same subdomain through this class, passing a list of residual equations defined in the problem.
#
# # Defining a new Equation class
# `Equation` classes can be also inherited to define a new class. As example, we can see how to rewrite the above problem introducing a new class `Burgers1D`; during the class call, we can pass the viscosity parameter $\nu$:
# In[3]:
class Burgers1DEquation(Equation):
def __init__(self, nu=0.0):
"""
Burgers1D class. This class can be
used to enforce the solution u to solve the viscous Burgers 1D Equation.
:param torch.float32 nu: the viscosity coefficient. Default value is set to 0.
"""
self.nu = nu
def equation(input_, output_):
return (
grad(output_, input_, d="t")
+ output_ * grad(output_, input_, d="x")
- self.nu * laplacian(output_, input_, d="x")
)
super().__init__(equation)
# Now we can just pass the above class as input for the last condition, setting $\nu= \frac{0.01}{\pi}$:
# In[4]:
class Burgers1D(TimeDependentProblem, SpatialProblem):
# define initial condition
def initial_condition(input_, output_):
u_expected = -torch.sin(torch.pi * input_.extract(["x"]))
return output_.extract(["u"]) - u_expected
# assign output/ spatial and temporal variables
output_variables = ["u"]
spatial_domain = CartesianDomain({"x": [-1, 1]})
temporal_domain = CartesianDomain({"t": [0, 1]})
domains = {
"bound_cond1": CartesianDomain({"x": -1, "t": [0, 1]}),
"bound_cond2": CartesianDomain({"x": 1, "t": [0, 1]}),
"time_cond": CartesianDomain({"x": [-1, 1], "t": 0}),
"phys_cond": CartesianDomain({"x": [-1, 1], "t": [0, 1]}),
}
# problem condition statement
conditions = {
"bound_cond1": Condition(
domain="bound_cond1", equation=FixedValue(0.0)
),
"bound_cond2": Condition(
domain="bound_cond2", equation=FixedValue(0.0)
),
"time_cond": Condition(
domain="time_cond", equation=Equation(initial_condition)
),
"phys_cond": Condition(
domain="phys_cond", equation=Burgers1DEquation(nu=0.01 / torch.pi)
),
}
# # What's next?
# Congratulations on completing the `Equation` class tutorial of **PINA**! As we have seen, you can build new classes that inherit `Equation` to store more complex equations, as the Burgers 1D equation, only requiring to pass the characteristic coefficients of the problem.
# From now on, you can:
# - define additional complex equation classes (e.g. `SchrodingerEquation`, `NavierStokeEquation`..)
# - define more `FixedOperator` (e.g. `FixedCurl`)