feat: #990 - [M4-P8] Jupytext Migration: Dynamics/Coagulation Functional - Sync Existing (4 notebooks)

[Gorkowski]

Target Branch: main

Fixes #990 | Workflow: cd29178c

Summary

Ensures the four Dynamics/Coagulation/Functional notebooks keep their paired .py files in sync via the required py:percent format, cleans up stale backup artifacts, and reruns the notebook validation/execution workflow so the checked-in examples stay current with the public particula API.

What Changed

Updated Notebooks

• docs/Examples/Dynamics/Coagulation/Functional/Coagulation_Basic_1_PMF.*, Coagulation_Basic_2_PDF.*, Coagulation_Basic_3_compared.*, Coagulation_Basic_4_ParticleResolved.* – refreshed headers, outputs, and metadata so each .py is in py:percent format, linted/rerun, and fully synced with its .ipynb counterpart.

Repository Cleanup

• .trash/cleanup/* files that were generated during validation and execution runs have been removed so only the relevant examples remain under version control.

How It Works

The workflow for each notebook now follows the verified edit/format/sync/execute cycle:

.jupytext header edits
    │
    ▼
ruff check/--fix + ruff format (batched)
    │
    ▼
validate_notebook --sync/--check-sync
    │
    ▼
run_notebook (execution)

This cycle guarantees the .py sources stay in percent format, match the executed notebooks, and run successfully with the current API.

Implementation Notes

• Why this approach: The maintenance plan requires percent-formatted .py files that are formally synced to their notebooks; doing the whole lint→sync→execute pipeline proves the examples remain reproducible and API-compatible.
• Artifact cleanup: Removing .trash/cleanup files keeps the repository clean after the tool-based validation/execution runs.

Testing

• python3 .opencode/tool/validate_notebook.py docs/Examples/Dynamics/Coagulation/Functional --recursive --check-sync
• ruff check docs/Examples/Dynamics/Coagulation/Functional/*.py --fix
• ruff format docs/Examples/Dynamics/Coagulation/Functional/*.py
• ruff check docs/Examples/Dynamics/Coagulation/Functional/*.py
• python3 .opencode/tool/validate_notebook.py docs/Examples/Dynamics/Coagulation/Functional --recursive --sync
• python3 .opencode/tool/run_notebook.py docs/Examples/Dynamics/Coagulation/Functional/Coagulation_Basic_1_PMF.ipynb
• python3 .opencode/tool/run_notebook.py docs/Examples/Dynamics/Coagulation/Functional/Coagulation_Basic_2_PDF.ipynb
• python3 .opencode/tool/run_notebook.py docs/Examples/Dynamics/Coagulation/Functional/Coagulation_Basic_3_compared.ipynb
• python3 .opencode/tool/run_notebook.py docs/Examples/Dynamics/Coagulation/Functional/Coagulation_Basic_4_ParticleResolved.ipynb

[Copilot]

Pull request overview

This PR completes part of the Jupytext migration for the coagulation functional examples and tightens up a nucleation example, ensuring .ipynb and .py remain in sync while cleaning up backup artifacts.

Changes:

• Updated four coagulation functional notebooks (PMF, PDF, PMF vs PDF, ParticleResolved) and their .py counterparts to use py:percent format, refreshed headers/metadata, and aligned plotting/summary cells.
• Extended and clarified helper docstrings and minor loop style in Custom_Nucleation_Single_Species.py.
• Replaced generated backup/checkpoint artifacts in .trash/cleanup/ with lightweight .removed markers as part of repo hygiene.

Reviewed changes

Copilot reviewed 24 out of 29 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
docs/Examples/Nucleation/Notebooks/Custom_Nucleation_Single_Species.py	Clarifies single-species array helper docstrings, adjusts import order, and simplifies a time loop variable.
docs/Examples/Dynamics/Coagulation/Functional/Coagulation_Basic_1_PMF.py	Adds Jupytext formats: ipynb,py:percent header for consistent pairing with the notebook.
docs/Examples/Dynamics/Coagulation/Functional/Coagulation_Basic_1_PMF.ipynb	Reflows intro and summary text, adds Jupytext metadata, and keeps content aligned with the .py percent script.
docs/Examples/Dynamics/Coagulation/Functional/Coagulation_Basic_2_PDF.py	Adds Jupytext formats header for the PDF coagulation example script.
docs/Examples/Dynamics/Coagulation/Functional/Coagulation_Basic_2_PDF.ipynb	Tweaks markdown formatting, ensures consistent imports order, and adds Jupytext format metadata.
docs/Examples/Dynamics/Coagulation/Functional/Coagulation_Basic_3_compared.py	Adds Jupytext formats header for the PMF vs PDF comparison script.
docs/Examples/Dynamics/Coagulation/Functional/Coagulation_Basic_3_compared.ipynb	Updates explanatory markdown, normalizes import ordering, and adds Jupytext pairing metadata.
docs/Examples/Dynamics/Coagulation/Functional/Coagulation_Basic_4_ParticleResolved.py	Adds Jupytext formats header to the particle-resolved coagulation example script.
docs/Examples/Dynamics/Coagulation/Functional/Coagulation_Basic_4_ParticleResolved.ipynb	Small markdown/plot tweaks, bins now created as a list, and adds Jupytext pairing metadata.
docs/Examples/Dynamics/Coagulation/Functional/Coagulation_Basic_4_ParticleResolved.ipynb.bak	Removes a stale backup notebook now superseded by the synced primary notebook.
.trash/cleanup/Coagulation_Basic_4_ParticleResolved.py.touch.removed	Tracks removal of an intermediate .py.touch artifact for the particle-resolved notebook.
.trash/cleanup/Coagulation_Basic_4_ParticleResolved.py.tmp.removed	Tracks removal of a temporary .py.tmp artifact for the particle-resolved notebook.
.trash/cleanup/Coagulation_Basic_4_ParticleResolved.ipynb.bak.removed	Tracks removal of a backup .ipynb.bak for the particle-resolved notebook.
.trash/cleanup/Coagulation_Basic_4_ParticleResolved-executed.ipynb/Coagulation_Basic_4_ParticleResolved.ipynb.removed	Tracks removal of an executed copy of the particle-resolved notebook used during validation.
.trash/cleanup/Coagulation_Basic_3_compared.py.touch.removed	Tracks removal of an intermediate .py.touch artifact for the PMF vs PDF notebook.
.trash/cleanup/Coagulation_Basic_3_compared.py.tmp.removed	Tracks removal of a temporary .py.tmp artifact for the PMF vs PDF notebook.
.trash/cleanup/Coagulation_Basic_3_compared.ipynb.bak.removed	Tracks removal of a backup .ipynb.bak for the PMF vs PDF notebook.
.trash/cleanup/Coagulation_Basic_2_PDF.py.touch.removed	Tracks removal of an intermediate .py.touch artifact for the PDF notebook.
.trash/cleanup/Coagulation_Basic_2_PDF.py.tmp.removed	Tracks removal of a temporary .py.tmp artifact for the PDF notebook.
.trash/cleanup/Coagulation_Basic_2_PDF.ipynb.bak.removed	Tracks removal of a backup .ipynb.bak for the PDF notebook.
.trash/cleanup/Coagulation_Basic_1_PMF.py.touch.removed	Tracks removal of an intermediate .py.touch artifact for the PMF notebook.
.trash/cleanup/Coagulation_Basic_1_PMF.py.tmp.removed	Tracks removal of a temporary .py.tmp artifact for the PMF notebook.
.trash/cleanup/Coagulation_Basic_1_PMF.ipynb.bak.removed	Tracks removal of a backup .ipynb.bak for the PMF notebook.

---

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