This document outlines the recommended structure for educational notebooks in this repository. Following this template ensures consistency and improves usability for learners.

Format: Markdown cell with H1 heading

# [Notebook Title]

[One to three sentences describing what this notebook demonstrates and
what problem it solves.]

Format: Markdown cells with clear sections

## Prerequisites

Before working through this notebook, you should be familiar with:

- [Background knowledge topic 1]
- [Background knowledge topic 2]
- [Background knowledge topic 3]

## Learning Objectives

By the end of this notebook, you will be able to:

1. [Objective 1 - specific and measurable]
2. [Objective 2 - specific and measurable]
3. [Objective 3 - specific and measurable]

Format: Code cell with clear comments

# Setup: Imports and Environment Configuration
# This notebook assumes you have set up the base environment
# as described in the main README.md

# Core imports
import numpy as np
import matplotlib.pyplot as plt
# ... other standard library imports

# Quantum computing framework imports
from classiq import ...
# or
import pennylane as qml

# Optional dependency check (with clear comment)
# Note: [package_name] is optional and will be installed if missing
try:
    import optional_package
except ModuleNotFoundError:
    import sys
    import subprocess
    subprocess.check_call([
        sys.executable, '-m', 'pip', 'install', '-q', 'optional_package'
    ])
    import optional_package

File Path Assumptions: If the notebook reads/writes files, add:

## File Paths and Working Directory

This notebook assumes you are running from the `[module_name]/` directory.
It will generate/read the following files:

- `[filename].qmod` - [description]
- `[filename].qprog` - [description]

These files are saved in the current working directory.

Format: Markdown cells with mathematical notation

## Theory

[Mathematical background, definitions, theorems, and explanations]

### Subsection Title

[Detailed explanations with equations, proofs, or derivations]

Format: Alternating code and markdown cells

## Implementation

[High-level description of the implementation approach]

### Step 1: [Description]

[Code cell with implementation]

Format: Code cells with markdown explanations

## Results

[Description of what experiments were run]

[Code cells executing the experiments]

[Analysis and interpretation of results]

Format: Markdown cell

## Summary

[Key takeaways from the notebook]

- [Takeaway 1]
- [Takeaway 2]
- [Takeaway 3]

## Further Reading

- [Reference 1]: [Description]
- [Reference 2]: [Description]
- Related notebooks: [Link to related notebook]

1. Import Organization: Group imports logically (standard library, third-party, local) and keep them at the top.

2. Comments: Use clear, descriptive comments explaining why code does something, not just what it does.

3. Markdown Cells: Use markdown cells liberally to explain concepts between code cells. Don't rely solely on code comments.

4. Cell Outputs: For educational notebooks, consider clearing outputs before committing (or use nbstripout). However, some result outputs may be valuable to keep.

5. Error Handling: When checking for optional dependencies, use try/except blocks with clear error messages.

6. File Paths: Always document assumptions about working directories and file paths explicitly.

7. Mathematical Notation: Use LaTeX math notation consistently for equations and mathematical expressions.

• This template is a guideline, not a strict requirement. Adapt as needed for specific notebook content.

• Some notebooks may combine sections (e.g., Theory and Implementation interleaved) if that improves pedagogical flow.

• The goal is clarity and consistency, not rigid adherence to structure.