maint: #995 - Jupytext Migration: Simulations - Organic + Biomass (2 long-running notebooks)

[Gorkowski]

Target Branch: main

Fixes #995 | Workflow: 44d30c2c

Summary

Converts 2 long-running simulation notebooks to Jupytext paired sync format (.py:percent). This is Phase 13 of the M4 Jupytext Full Migration maintenance plan, completing all simulation notebook conversions in the repository.

Critical fix applied: The Organic_Partitioning_and_Coagulation notebook contained a deprecated API import (from particula.activity.species_density import organic_array) that was updated to use the current public API (from particula.particles import get_organic_density_array) with the required unit conversion (kg/m³ → g/cm³).

What Changed

New Components

• docs/Examples/Simulations/Notebooks/Organic_Partitioning_and_Coagulation.py (+526 lines) - Jupytext paired Python script for SOA formation and coagulation simulation tutorial. Fixed deprecated API import with unit conversion.
• docs/Examples/Simulations/Notebooks/Biomass_Burning_Cloud_Interactions.py (+705 lines) - Jupytext paired Python script for biomass aerosol and cloud interactions tutorial. Uses current public API (no updates needed).

Modified Components

• docs/Examples/Simulations/Notebooks/Organic_Partitioning_and_Coagulation.ipynb - Added Jupytext metadata and synced with .py file, includes execution outputs for website rendering
• docs/Examples/Simulations/Notebooks/Biomass_Burning_Cloud_Interactions.ipynb - Added Jupytext metadata and synced with .py file, includes execution outputs for website rendering
• adw-docs/dev-plans/maintenance/M4-jupytext-full-migration.md - Updated migration tracking to mark Phase 13 as complete
• adw-docs/documentation_guide.md - Added notebook editing workflow documentation

How It Works

The Jupytext paired sync workflow enables editing notebooks as plain Python files:

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Edit .py file  │────▶│  Lint & Format  │────▶│  Sync to .ipynb │
│  (py:percent)   │     │  (ruff)         │     │  (jupytext)     │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                        │
                                                        ▼
                                               ┌─────────────────┐
                                               │ Execute .ipynb  │
                                               │ (validate code) │
                                               └─────────────────┘

API Migration performed:

OLD (deprecated):
from particula.activity.species_density import organic_array
density_organics_g_cm3 = organic_array(molar_mass=..., ...)  # g/cm³

NEW (current API):
from particula.particles import get_organic_density_array
density_organics_kg_m3 = get_organic_density_array(molar_mass=..., ...)  # kg/m³
density_organics_g_cm3 = density_organics_kg_m3 / 1000  # Convert to g/cm³

Implementation Notes

• Execution times: Both notebooks are long-running (>60s), recommended for CI-only execution, not pre-commit hooks
• API deprecation fixed: particula.activity.species_density module no longer exists; updated to use particula.particles.get_organic_density_array() with SI unit conversion
• Jupytext format: py:percent with YAML header, # %% cell markers for code, # %% [markdown] for markdown cells
• Outputs stored: Notebooks executed and outputs saved in .ipynb for MkDocs website rendering (mkdocs renders with execute=False)

Testing

• Notebook validation: Both notebooks validated using validate_notebook --check-sync (sync status confirmed)
• Notebook execution: Both notebooks executed successfully with 1200s timeout
• Linting: Both .py files pass ruff check and ruff format with no errors
• API verification: Confirmed get_organic_density_array returns correct density values in SI units (kg/m³)

Execution Time Handling

Notebook	Recommended Handling
Organic_Partitioning_and_Coagulation.ipynb	>60s → CI only
Biomass_Burning_Cloud_Interactions.ipynb	>60s → CI only

These times will be referenced in M4-P14 (pre-commit hook configuration) to exclude long-running notebooks from pre-commit validation.

References

• Maintenance Plan: adw-docs/dev-plans/maintenance/M4-jupytext-full-migration.md
• Documentation Guide: adw-docs/documentation_guide.md (Jupytext Paired Sync Workflow)
• Dependency: [M4-P12] Jupytext Migration: Simulations - Soot + Cough (2 long-running notebooks) #994 (M4-P12) - Previous simulation notebook conversions

[Copilot]

Pull request overview

This PR completes Phase 13 of the M4 Jupytext Full Migration maintenance plan by converting the final 2 long-running simulation notebooks to Jupytext paired sync format (.py:percent). The conversion includes a critical API migration fix in the Organic Partitioning notebook, updating from a deprecated density calculation API to the current public API with proper unit conversion.

Changes:

• Converted Organic_Partitioning_and_Coagulation notebook with API migration from deprecated particula.activity.species_density.organic_array to current particula.particles.get_organic_density_array (including kg/m³ to g/cm³ unit conversion)
• Converted Biomass_Burning_Cloud_Interactions notebook to paired format (no API updates needed)
• Updated documentation to reflect completion of all 35 notebook conversions

Reviewed changes

Copilot reviewed 4 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
Organic_Partitioning_and_Coagulation.py	New 526-line Jupytext paired script for SOA simulation with fixed API import and unit conversion
Biomass_Burning_Cloud_Interactions.py	New 705-line Jupytext paired script for biomass aerosol simulation using current APIs
Organic_Partitioning_and_Coagulation.ipynb	Updated with Jupytext metadata and synced with .py file
Biomass_Burning_Cloud_Interactions.ipynb	Updated with Jupytext metadata and synced with .py file
documentation_guide.md	Updated to reflect M4 migration completion (all 35 notebooks paired)
M4-jupytext-full-migration.md	Updated tracking to mark Phase 13 complete and document API deprecation fix

---

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

[Copilot]

There are two consecutive cell markers here which creates an empty cell between them. This should likely be either a single cell marker with a label # %% staggered time stepping (removing line 452), or line 453 should be changed to a regular comment # staggered time stepping without the cell marker syntax. The duplicate marker is unnecessary and could cause confusion.

Suggested change

	# %%
	# .

[Copilot]

For loop variable '_step' is not used in the loop body.

Suggested change

	for _step in tqdm(range(total_steps), desc="Running Sim", mininterval=0.5):
	for _ in tqdm(range(total_steps), desc="Running Sim", mininterval=0.5):