Update Tutorials (#544)

* update tutorials
* tutorial guidelines
* doc

Author: dario-coscia

docs/source/_tutorial.rst

@@ -1,35 +1,43 @@
-PINA Tutorials
-======================
+🚀 Welcome to the PINA Tutorials!
+==================================
 
 
-In this folder we collect useful tutorials in order to understand the principles and the potential of **PINA**.
+In this folder we collect useful tutorials in order to understand the principles and the potential of **PINA**. 
+Whether you're just getting started or looking to deepen your understanding, these resources are here to guide you.
 
 Getting started with PINA
 -------------------------
 
-- `Introduction to PINA for Physics Informed Neural Networks training <tutorial1/tutorial.html>`_
+- `Introductory Tutorial: A Beginner's Guide to PINA <tutorial17/tutorial.html>`_
+- `How to build a Problem in PINA <tutorial16/tutorial.html>`_
+- `Introduction to Solver classes <tutorial18/tutorial.html>`_
+- `Introduction to Trainer class <tutorial11/tutorial.html>`_
+- `Data structure for SciML: Tensor, LabelTensor, Data and Graph <tutorial19/tutorial.html>`_
+- `Building geometries with DomainInterface class <tutorial6/tutorial.html>`_
 - `Introduction to PINA Equation class <tutorial12/tutorial.html>`_
-- `PINA and PyTorch Lightning, training tips and visualizations <tutorial11/tutorial.html>`_
-- `Building custom geometries with PINA Location class <tutorial6/tutorial.html>`_
-
 
 Physics Informed Neural Networks
 --------------------------------
 
-- `Two dimensional Poisson problem using Extra Features Learning <tutorial2/tutorial.html>`_
-- `Two dimensional Wave problem with hard constraint <tutorial3/tutorial.html>`_
-- `Resolution of a 2D Poisson inverse problem <tutorial7/tutorial.html>`_
-- `Periodic Boundary Conditions for Helmotz Equation <tutorial9/tutorial.html>`_
-- `Multiscale PDE learning with Fourier Feature Network <tutorial13/tutorial.html>`_
+- `Introductory Tutorial: Physics Informed Neural Networks with PINA <tutorial1/tutorial.html>`_
+- `Enhancing PINNs with Extra Features to solve the Poisson Problem <tutorial2/tutorial.html>`_
+- `Applying Hard Constraints in PINNs to solve the Wave Problem <tutorial3/tutorial.html>`_
+- `Applying Periodic Boundary Conditions in PINNs to solve the Helmotz Problem <tutorial9/tutorial.html>`_
+- `Inverse Problem Solving with Physics-Informed Neural Network <tutorial7/tutorial.html>`_
+- `Learning Multiscale PDEs Using Fourier Feature Networks <tutorial13/tutorial.html>`_
+- `Learning Bifurcating PDE Solutions with Physics-Informed Deep Ensembles <tutorial14/tutorial.html>`_
 
 Neural Operator Learning
 ------------------------
 
-- `Two dimensional Darcy flow using the Fourier Neural Operator <tutorial5/tutorial.html>`_
-- `Time dependent Kuramoto Sivashinsky equation using the Averaging Neural Operator <tutorial10/tutorial.html>`_
+- `Introductory Tutorial: Neural Operator Learning with PINA <tutorial21/tutorial.html>`_
+- `Modeling 2D Darcy Flow with the Fourier Neural Operator <tutorial5/tutorial.html>`_
+- `Solving the Kuramoto-Sivashinsky Equation with Averaging Neural Operator <tutorial10/tutorial.html>`_
 
 Supervised Learning
 -------------------
 
-- `Unstructured convolutional autoencoder via continuous convolution <tutorial4/tutorial.html>`_
-- `POD-RBF and POD-NN for reduced order modeling <tutorial8/tutorial.html>`_
+- `Introductory Tutorial: Supervised Learning with PINA  <tutorial20/tutorial.html>`_
+- `Chemical Properties Prediction with Graph Neural Networks <tutorial25/tutorial.html>`_
+- `Unstructured Convolutional Autoencoders with Continuous Convolution <tutorial4/tutorial.html>`_
+- `Reduced Order Modeling with POD-RBF and POD-NN Approaches for Fluid Dynamics <tutorial8/tutorial.html>`_

tutorials/README.md

@@ -1,36 +1,47 @@
-# PINA Tutorials
+# 🚀 Welcome to the PINA Tutorials!
+
+In this folder we collect useful tutorials in order to understand the principles and the potential of **PINA**. Whether you're just getting started or looking to deepen your understanding, these resources are here to guide you.
+
+The table below provides an overview of each tutorial. All tutorials are also available in HTML in the official [PINA documentation](http://mathlab.github.io/PINA/).
 
-In this folder we collect useful tutorials in order to understand the principles and the potential of **PINA**. Please read the following table for details about the tutorials. The HTML version of all the tutorials is available also within the [documentation](http://mathlab.github.io/PINA/).
 
 ## Getting started with PINA
 
 | Description   | Tutorial |
 |---------------|-----------|
-Introduction to PINA for Physics Informed Neural Networks training|[[.ipynb](tutorial1/tutorial.ipynb), [.py](tutorial1/tutorial.py), [.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial1/tutorial.html)]|
-Introduction to PINA `Equation` class|[[.ipynb](tutorial12/tutorial.ipynb), [.py](tutorial12/tutorial.py), [.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial12/tutorial.html)]|
-PINA and PyTorch Lightning, training tips and visualizations|[[.ipynb](tutorial11/tutorial.ipynb), [.py](tutorial11/tutorial.py), [.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial11/tutorial.html)]|
-Building custom geometries with PINA `Location` class|[[.ipynb](tutorial6/tutorial.ipynb), [.py](tutorial6/tutorial.py), [.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial6/tutorial.html)]|
+Introductory Tutorial: A Beginner’s Guide to PINA|[[.ipynb](tutorial17/tutorial.ipynb),[.py](tutorial17/tutorial.py),[.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial17/tutorial.html)]|
+How to build a `Problem` in PINA|[[.ipynb](tutorial16/tutorial.ipynb),[.py](tutorial16/tutorial.py),[.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial16/tutorial.html)]|
+Introduction to Solver classes|[[.ipynb](tutorial18/tutorial.ipynb),[.py](tutorial18/tutorial.py),[.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial18/tutorial.html)]|
+Introduction to `Trainer` class|[[.ipynb](tutorial11/tutorial.ipynb),[.py](tutorial11/tutorial.py),[.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial11/tutorial.html)]|
+Data structure for SciML: `Tensor`, `LabelTensor`, `Data` and `Graph` |[[.ipynb](tutorial19/tutorial.ipynb),[.py](tutorial19/tutorial.py),[.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial19/tutorial.html)]|
+Building geometries with `DomainInterface` class|[[.ipynb](tutorial6/tutorial.ipynb),[.py](tutorial6/tutorial.py),[.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial6/tutorial.html)]|
+Introduction to PINA `Equation` class|[[.ipynb](tutorial12/tutorial.ipynb),[.py](tutorial12/tutorial.py),[.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial12/tutorial.html)]|
 
 
 ## Physics Informed Neural Networks
 | Description   | Tutorial  |
 |---------------|-----------|
-Two dimensional Poisson problem using Extra Features Learning     |[[.ipynb](tutorial2/tutorial.ipynb), [.py](tutorial2/tutorial.py), [.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial2/tutorial.html)]|
-Two dimensional Wave problem with hard constraint |[[.ipynb](tutorial3/tutorial.ipynb), [.py](tutorial3/tutorial.py), [.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial3/tutorial.html)]|
-Resolution of a 2D Poisson inverse problem |[[.ipynb](tutorial7/tutorial.ipynb), [.py](tutorial7/tutorial.py), [.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial7/tutorial.html)]|
-Periodic Boundary Conditions for Helmotz Equation |[[.ipynb](tutorial9/tutorial.ipynb), [.py](tutorial9/tutorial.py), [.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial9/tutorial.html)]|
-Multiscale PDE learning with Fourier Feature Network |[[.ipynb](tutorial13/tutorial.ipynb), [.py](tutorial13/tutorial.py), [.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial13/tutorial.html)]|
+Introductory Tutorial:  Physics Informed Neural Networks with PINA |[[.ipynb](tutorial1/tutorial.ipynb),[.py](tutorial1/tutorial.py),[.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial1/tutorial.html)]|
+Enhancing PINNs with Extra Features to solve the Poisson Problem |[[.ipynb](tutorial2/tutorial.ipynb),[.py](tutorial2/tutorial.py),[.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial2/tutorial.html)]|
+Applying Hard Constraints in PINNs to solve the Wave Problem |[[.ipynb](tutorial3/tutorial.ipynb),[.py](tutorial3/tutorial.py),[.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial3/tutorial.html)]|
+Applying Periodic Boundary Conditions in PINNs to solve the Helmotz Problem |[[.ipynb](tutorial9/tutorial.ipynb),[.py](tutorial9/tutorial.py),[.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial9/tutorial.html)]|
+Inverse Problem Solving with Physics-Informed Neural Network |[[.ipynb](tutorial7/tutorial.ipynb),[.py](tutorial7/tutorial.py),[.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial7/tutorial.html)]|
+Learning Multiscale PDEs Using Fourier Feature Networks|[[.ipynb](tutorial13/tutorial.ipynb),[.py](tutorial13/tutorial.py),[.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial13/tutorial.html)]|
+Learning Bifurcating PDE Solutions with Physics-Informed Deep Ensembles|[[.ipynb](tutorial14/tutorial.ipynb),[.py](tutorial14/tutorial.py),[.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial14/tutorial.html)]|
 
 
 ## Neural Operator Learning
 | Description   | Tutorial  |
 |---------------|-----------|
-Two dimensional Darcy flow using the Fourier Neural Operator          |[[.ipynb](tutorial5/tutorial.ipynb), [.py](tutorial5/tutorial.py), [.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial5/tutorial.html)]|
-Time dependent Kuramoto Sivashinsky equation using the Averaging Neural Operator          |[[.ipynb](tutorial10/tutorial.ipynb), [.py](tutorial10/tutorial.py), [.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial10/tutorial.html)]|
+Introductory Tutorial: Neural Operator Learning with PINA |[[.ipynb](tutorial21/tutorial.ipynb),[.py](tutorial21/tutorial.py),[.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial21/tutorial.html)]|
+Modeling 2D Darcy Flow with the Fourier Neural Operator |[[.ipynb](tutorial5/tutorial.ipynb),[.py](tutorial5/tutorial.py),[.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial5/tutorial.html)]|
+Solving the Kuramoto–Sivashinsky Equation with Averaging Neural Operator |[[.ipynb](tutorial10/tutorial.ipynb),[.py](tutorial10/tutorial.py),[.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial10/tutorial.html)]|
 
 ## Supervised Learning
 | Description   | Tutorial  |
 |---------------|-----------|
-Unstructured convolutional autoencoder via continuous convolution |[[.ipynb](tutorial4/tutorial.ipynb), [.py](tutorial4/tutorial.py), [.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial4/tutorial.html)]|
-POD-RBF and POD-NN for reduced order modeling| [[.ipynb](tutorial8/tutorial.ipynb), [.py](tutorial8/tutorial.py), [.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial8/tutorial.html)]|
-POD-RBF for modelling Lid Cavity| [[.ipynb](tutorial14/tutorial.ipynb), [.py](tutorial14/tutorial.py), [.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial14/tutorial.html)]|
+Introductory Tutorial: Supervised Learning with PINA |[[.ipynb](tutorial20/tutorial.ipynb),[.py](tutorial20/tutorial.py),[.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial20/tutorial.html)]|
+Chemical Properties Prediction with Graph Neural Networks |[[.ipynb](tutorial15/tutorial.ipynb),[.py](tutorial15/tutorial.py),[.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial15/tutorial.html)]|
+Unstructured Convolutional Autoencoders with Continuous Convolution |[[.ipynb](tutorial4/tutorial.ipynb),[.py](tutorial4/tutorial.py),[.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial4/tutorial.html)]|
+Reduced Order Modeling with POD-RBF and POD-NN Approaches for Fluid Dynamics| [[.ipynb](tutorial8/tutorial.ipynb),[.py](tutorial8/tutorial.py),[.html](http://mathlab.github.io/PINA/_rst/tutorials/tutorial8/tutorial.html)]|
+

tutorials/TUTORIAL_GUIDELINES.md

@@ -0,0 +1,128 @@
+# PINA Tutorial Guidelines
+
+Welcome to the **PINA Tutorial Guidelines** — a guiding document that defines the structure, style, and pedagogical philosophy for all tutorials in the **PINA** package. The goal of this guideline is to ensure that all learning materials are **clear, consistent, pedagogically sound, and beginner-friendly**, while remaining powerful enough to support advanced use cases.
+
+
+## Purpose
+
+The purpose of the PINA tutorials is to help users:
+
+- Gaining a solid understanding of the PINA library and its core functionalities.
+- Learning how to work with the PINA modules.
+- Explore practical and advanced applications using consistent, hands-on code examples.
+
+
+## Guiding Principles
+
+1. **Clarity Over Cleverness**  
+   Tutorials should aim to teach, not impress. Prioritize readable and understandable code and explanations.
+
+2. **Progressive Disclosure of Complexity**  
+   Start simple and gradually introduce complexity. Avoid overwhelming users early on.
+
+3. **Consistency is Key**  
+   All tutorials should follow a common structure (see below), use the same markdown and code formatting, and have a predictable flow.
+
+4. **Real Applications, Real Problems**  
+   Ground tutorials in real Scientific Applications or datasets, wherever possible. Bridge theory and implementation.
+
+
+## Tutorial Structure
+
+To ensure clarity, consistency, and accessibility, all PINA tutorials should follow the same standardized format.
+
+### 1. Title
+
+Each tutorial must begin with a clear and descriptive title in the following format: **Tutorial: TUTORIAL_TITLE**. The title should succinctly communicate the focus and objective of the tutorial.
+
+### 2. Introducing the Topic
+
+Immediately after the title, include a short introduction that outlines the tutorial's purpose and scope.
+
+- Briefly explain what the tutorial covers and why it’s useful.
+- Link to relevant research papers, publications, or external resources if applicable.
+- List the core PINA components or modules that will be utilized.
+
+### 3. Imports and Setup
+
+Include a Python code cell with the necessary setup. This ensures that the tutorial runs both locally and on platforms like Google Colab.
+
+```python
+## Routine needed to run the notebook on Google Colab
+try:
+    import google.colab
+    IN_COLAB = True
+except:
+    IN_COLAB = False
+
+if IN_COLAB:
+    !pip install "pina-mathlab[tutorial]"
+
+import torch                        # if used
+import matplotlib.pyplot as plt     # if used
+import warnings                     # if needed
+
+warnings.filterwarnings("ignore")
+
+# Additional PINA and problem-specific imports
+...
+```
+
+### 3. Data Generation or Loading
+* Describe how the data is generated or loaded.
+* Include commentary on data structure, format, and content.
+* If applicable, visualize key features of the dataset or simulation domain.
+
+### 4. Main Body
+The core section of the tutorial should present the problem-solving process in a clear, structured, and pedagogical way. This is where the tutorial delivers the key learning objectives.
+
+- Guide the user step-by-step through the PINA workflow.
+- Introduce relevant PINA components as they are used.
+- Provide context and explain the rationale behind modeling decisions.
+- Break down complex sections with inline comments and markdown explanations.
+- Emphasize the relevance of each step to the broader goal of the tutorial.
+
+### 5. Results, Visualization and Error Analysis
+- Show relevant plots of results (e.g., predicted vs. ground truth).
+- Quantify performance using metrics like loss or relative error.
+- Discuss the outcomes: strengths, limitations, and any unexpected behavior
+
+### 6. What's Next?
+All the tutorials are concluded with the **What's Next?** section,giving suggestions for further exploration. For this use the following format:
+```markdown
+## What's Next?
+
+Congratulations on completing the ..., here are a few directions you can explore:
+
+1. **Direction 1** — Suggestion ....
+
+2. **Direction 2** — Suggestion ....
+
+3. **...and many more!** — Other suggestions ....
+
+For more resources and tutorials, check out the [PINA Documentation](https://mathlab.github.io/PINA/).
+```
+
+## Writing Style
+
+- Use **clear markdown headers** to segment sections.
+- Include **inline math** with `$...$` and display math with `$$...$$`.
+- Keep paragraphs short and focused.
+- Use **bold** and *italic* for emphasis and structure.
+- Include comments in code for clarity.
+
+
+## Testing Tutorials
+
+Every tutorial should:
+- Be executable from top to bottom.
+- Use the `tutorial` requirements in the [`pyproject.toml`](https://github.com/mathLab/PINA/blob/6ed3ca04fee3ae3673d53ea384437ce270f008da/pyproject.toml#L40) file.
+
+
+## Contributing Checklist
+
+We welcome contributions! If you’re writing a tutorial:
+1. The tutorial follows this guidelines for structure and tone.
+2. The tutorial is simple and modular — one tutorial per concept.
+3. The tutorial PRs contains only the `.ipynb` file, and the updated `README.md` file.
+