fix: #983 - [M4-P1] Jupytext Migration: Aerosol + Equilibria (3 notebooks)

[Gorkowski]

Target Branch: main

Fixes #983 | Workflow: 24208117

Summary

Converted the three remaining Aerosol and Equilibria example notebooks listed in the M4 migration plan to Jupytext py:percent paired-sync scripts. Each notebook now has a linted Python source, synced metadata that preserves the original kernelspecs, and a clean execution run so the examples remain up to date.

What Changed

New Components

• docs/Examples/Aerosol/Aerosol_Tutorial.py - Percent-format script paired with the Aerosol tutorial notebook, mirroring cell structure and metadata.
• docs/Examples/Equilibria/Notebooks/equilibria_part1.py - New paired Python source for the equilibria Part 1 notebook, enabling IDE-friendly edits.
• docs/Examples/Equilibria/Notebooks/activity_part1.py - New paired Python source for Activity Part 1 with matching cell markers and metadata headers.

Modified Components

• docs/Examples/Aerosol/Aerosol_Tutorial.ipynb - Synced cells, updated metadata, and outputs refreshed after executing the linted script.
• docs/Examples/Equilibria/Notebooks/equilibria_part1.ipynb - Synced with the new .py file and rerun to confirm outputs.
• docs/Examples/Equilibria/Notebooks/activity_part1.ipynb - Synced with the new .py file, keeping kernelspec/time stamps in lock-step.
• maintenance/M4-jupytext-full-migration.md - Notes progress for the Phase 1 migration batch.

Tests Added/Updated

• ruff check docs/Examples/Aerosol/Aerosol_Tutorial.py --fix && ruff format docs/Examples/Aerosol/Aerosol_Tutorial.py
• ruff check docs/Examples/Equilibria/Notebooks/equilibria_part1.py --fix && ruff format docs/Examples/Equilibria/Notebooks/equilibria_part1.py
• ruff check docs/Examples/Equilibria/Notebooks/activity_part1.py --fix && ruff format docs/Examples/Equilibria/Notebooks/activity_part1.py
• python3 .opencode/tool/validate_notebook.py <notebook>.ipynb --sync and --check-sync for each pair.
• python3 .opencode/tool/run_notebook.py <notebook>.ipynb for all three notebooks.

How It Works

Each notebook was converted using validate_notebook --convert-to-py, producing a py:percent script with the required jupytext header (format 1.3 and the original kernelspec display name). The scripts were linted and formatted with Ruff, then synced back to the .ipynb files and validated (--check-sync) before executing them with run_notebook.py. This workflow keeps markdown/code cells, metadata, and outputs aligned between the notebook and its paired script, making future edits possible directly in the Python sources.

Implementation Notes

• Consistency: Headers retain format_name: percent / format_version: '1.3' / jupytext_version: 1.17.3 and the kernelspec display names observed in each notebook.
• Ruff: Running ruff check --fix followed by ruff format ensures the paired scripts match repository style rules before syncing.
• Migration tracking: The maintenance document now references this Phase 1 conversion, documenting the notebooks covered by the plan.

Testing

• Linting: Ruff applied (check --fix + format) to every generated .py script.
• Sync validation: .ipynb files sync-validated via validate_notebook --sync / --check-sync.
• Execution: run_notebook.py executed each notebook successfully to refresh outputs and confirm there are no runtime/API issues.

[Copilot]

Pull request overview

This PR implements Phase 1 of the M4 Jupytext migration plan, converting 3 example notebooks (Aerosol_Tutorial, equilibria_part1, and activity_part1) to Jupytext paired-sync format. Each notebook now has a paired Python source file in py:percent format that has been linted with Ruff and re-executed to ensure functionality.

Changes:

• Converts 3 notebooks to Jupytext paired sync (py:percent format)
• Adds linted Python source files for IDE-friendly editing
• Refreshes notebook outputs after clean execution
• Updates M4 migration plan to reflect phase structure

Reviewed changes

Copilot reviewed 5 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
docs/Examples/Equilibria/Notebooks/equilibria_part1.py	New paired Python source for equilibria Part 1 notebook in percent format
docs/Examples/Equilibria/Notebooks/equilibria_part1.ipynb	Synced notebook with updated metadata and refreshed outputs
docs/Examples/Equilibria/Notebooks/activity_part1.py	New paired Python source for Activity Part 1 with proper Jupytext headers
docs/Examples/Aerosol/Aerosol_Tutorial.py	New paired Python source for Aerosol tutorial
docs/Examples/Aerosol/Aerosol_Tutorial.ipynb	Synced notebook with cell IDs and execution timestamps
adw-docs/dev-plans/maintenance/M4-jupytext-full-migration.md	Updated maintenance plan with revised phase structure (max 3 notebooks per phase)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.