[M4-P11] Jupytext Migration: Simulations - Cloud Chamber (2 long-running notebooks)

[Gorkowski]

Dependencies:

#992 [M4-P10] ──► #THIS [M4-P11]

Dependencies:

• M4-P10: [M4-P10] Jupytext Migration: Dynamics/Condensation Part 2 + Customization (2 notebooks) #992

Description

Convert 2 long-running notebooks from the Simulations directory to Jupytext paired sync format (.py:percent). This is Phase 11 of the M4 Jupytext Full Migration maintenance plan, covering cloud chamber simulation tutorials.

Important: These are long-running notebooks. Profile execution time and determine appropriate handling (pre-commit exclusion vs CI-only). If any notebooks contain outdated API calls, update them to use the current API.

Context

This is part of the M4 maintenance plan to complete Jupytext paired sync migration for all remaining notebooks in docs/Examples/. Continues from M4-P10 which completed Condensation and Customization notebooks.

Value:

• Enables editing notebooks as plain Python files (better diffs, linting, IDE support)
• Validates notebook content through linting
• Documents execution times for slow notebook handling strategy
• Ensures notebooks use current API (no deprecated calls)

Scope

Estimated Lines of Code: ~50-150 lines (metadata + formatting + any API updates)
Complexity: Medium (long-running execution)

Notebooks to Convert (2) - Long-Running:

• docs/Examples/Simulations/Notebooks/Cloud_Chamber_Single_Cycle.ipynb
• docs/Examples/Simulations/Notebooks/Cloud_Chamber_Multi_Cycle.ipynb

Files Created:

• docs/Examples/Simulations/Notebooks/Cloud_Chamber_Single_Cycle.py (~100-300 LOC)
• docs/Examples/Simulations/Notebooks/Cloud_Chamber_Multi_Cycle.py (~100-300 LOC)

Acceptance Criteria

Execution Time Profiling

• Profile execution time for Cloud_Chamber_Single_Cycle.ipynb
• Profile execution time for Cloud_Chamber_Multi_Cycle.ipynb
• Document times in PR description for future reference
• Determine handling: < 60s = pre-commit, 60-300s = CI only, > 300s = nightly CI

Conversion

• Both notebooks converted to .py:percent format using validate_notebook --convert-to-py
• Each .py file has proper Jupytext header with py:percent format

API Updates (REQUIRED if outdated)

• Review execution output for deprecation warnings or API errors
• Update any outdated import paths to current API
• Update any deprecated function calls to current equivalents
• Update any changed function signatures (parameters renamed/added/removed)
• Verify updated code produces equivalent results

Linting

• Run ruff check --fix on all new .py files
• Run ruff format on all new .py files
• Final ruff check passes with no errors

Sync Validation

• Sync .py changes back to .ipynb using validate_notebook --sync
• Validate sync status with validate_notebook --check-sync (must pass)

Execution

• Both notebooks execute successfully using run_notebook with extended timeout (1200s)
• No API deprecation warnings in output
• No errors or exceptions during execution

Technical Notes

Conversion Workflow

For each notebook:

# 1. Convert to .py:percent format
python3 .opencode/tool/validate_notebook.py docs/Examples/Simulations/Notebooks/Cloud_Chamber_Single_Cycle.ipynb --convert-to-py

# 2. Lint the new .py file
ruff check docs/Examples/Simulations/Notebooks/Cloud_Chamber_Single_Cycle.py --fix
ruff format docs/Examples/Simulations/Notebooks/Cloud_Chamber_Single_Cycle.py

# 3. Sync linted .py back to .ipynb
python3 .opencode/tool/validate_notebook.py docs/Examples/Simulations/Notebooks/Cloud_Chamber_Single_Cycle.ipynb --sync

# 4. Execute with extended timeout to profile time
time python3 .opencode/tool/run_notebook.py docs/Examples/Simulations/Notebooks/Cloud_Chamber_Single_Cycle.ipynb --timeout 1200

# 5. If deprecation warnings or errors found:
#    - Edit the .py file to update API calls
#    - Re-lint and re-sync
#    - Re-execute to verify fix

# 6. Validate sync status
python3 .opencode/tool/validate_notebook.py docs/Examples/Simulations/Notebooks/Cloud_Chamber_Single_Cycle.ipynb --check-sync

Execution Time Handling Strategy

Execution Time	Handling
< 60 seconds	Include in pre-commit hook
60-300 seconds	Exclude from pre-commit, include in CI
> 300 seconds	Nightly CI job only (exclude from PR CI)

Document execution times in PR for M4-P14 (pre-commit hook configuration).

API Update Guidelines

When updating outdated API calls:

1. Import path changes: Update from particula.old.path import X to from particula.new.path import X
2. Function renames: Replace old_function() with new_function()
3. Parameter changes: Update function calls with renamed/new parameters
4. Class changes: Update class instantiation if constructors changed
5. Return type changes: Adjust any code that depends on return values

Reference current API: Check particula/ source code for current function signatures and import paths.

References

Maintenance Plan:

• adw-docs/dev-plans/maintenance/M4-jupytext-full-migration.md - Full migration plan

Related:

• [M4-P10] Jupytext Migration: Dynamics/Condensation Part 2 + Customization (2 notebooks) #992 - M4-P10 (dependency)
• adw-docs/documentation_guide.md - Notebook editing guidelines

[Gorkowski]

[ADW-AGENTS] # 🤖 ADW Workflow Status

Description: Complete workflow: plan → build → validate → test → format → document → ship

ADW ID: 67e25a87
Current Phase: Workflow completed successfully
Started: 2026-01-31T02:52:26.671815Z
Last Update: 2026-01-31T04:06:24.973317Z

Current Status

✅ Workflow completed in 1h 13m

Workflow Plan

• ✅ Generate Multi-Review Implementation Plan (at 2026-01-31T03:00:53.254166Z)
• ✅ Build Implementation (at 2026-01-31T03:19:54.372246Z)
• ✅ Validate Implementation and Fix Gaps (at 2026-01-31T03:36:50.794104Z)
• ✅ Run Tests (at 2026-01-31T03:57:30.486809Z)
• ✅ Format Code and Add Docstrings (at 2026-01-31T03:59:24.907245Z)
• ✅ Generate Documentation (at 2026-01-31T04:04:29.918065Z)
• ✅ Ship Implementation (at 2026-01-31T04:06:23.376981Z)

📋 Recent Activity

[2026-01-31T03:36:50.794123Z] Completed step 3/7: Validate Implementation and Fix Gaps
[2026-01-31T03:36:52.329949Z] Starting step 4/7: Run Tests
[2026-01-31T03:57:30.486829Z] Completed step 4/7: Run Tests
[2026-01-31T03:57:31.968676Z] Starting step 5/7: Format Code and Add Docstrings
[2026-01-31T03:59:24.907276Z] Completed step 5/7: Format Code and Add Docstrings
[2026-01-31T03:59:26.378490Z] Starting step 6/7: Generate Documentation
[2026-01-31T04:04:29.918086Z] Completed step 6/7: Generate Documentation
[2026-01-31T04:04:32.019603Z] Starting step 7/7: Ship Implementation
[2026-01-31T04:06:23.377001Z] Completed step 7/7: Ship Implementation
[2026-01-31T04:06:24.971455Z] Workflow complete finished: 7/7 steps completed

🔍 Archived Updates

[2026-01-31T02:52:26.753947Z] Workflow complete started with 7 steps
[2026-01-31T02:52:28.888790Z] Starting step 1/7: Generate Multi-Review Implementation Plan
[2026-01-31T03:00:53.254200Z] Completed step 1/7: Generate Multi-Review Implementation Plan
[2026-01-31T03:00:54.890748Z] Starting step 2/7: Build Implementation
[2026-01-31T03:19:54.372278Z] Completed step 2/7: Build Implementation
[2026-01-31T03:19:55.925482Z] Starting step 3/7: Validate Implementation and Fix Gaps

---

This comment is automatically updated as the workflow progresses

Resume command: adw workflow run complete 993 --adw-id 67e25a87 --resume