# 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.