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

[Gorkowski]

Dependencies:

#991 [M4-P9] ──► #THIS [M4-P10]

Dependencies:

• M4-P9: [M4-P9] Jupytext Migration: Dynamics/Condensation Part 1 (3 notebooks) #991

---

Description

Convert 2 notebooks from the Dynamics/Condensation and Dynamics/Customization directories to Jupytext paired sync format (.py:percent). This is Phase 10 of the M4 Jupytext Full Migration maintenance plan, completing the condensation and customization tutorials.

Important: If any notebooks contain outdated API calls, update them to use the current API before completing the conversion.

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-P9 which converted core Condensation notebooks.

Value:

• Enables editing notebooks as plain Python files (better diffs, linting, IDE support)
• Validates notebook content through linting
• Covers staggered condensation and simulation customization examples
• Ensures notebooks use current API (no deprecated calls)

Scope

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

Notebooks to Convert (2):

• docs/Examples/Dynamics/Condensation/Staggered_Condensation_Example.ipynb
• docs/Examples/Dynamics/Customization/Adding_Particles_During_Simulation.ipynb

Files Created:

• docs/Examples/Dynamics/Condensation/Staggered_Condensation_Example.py (~100-200 LOC)
• docs/Examples/Dynamics/Customization/Adding_Particles_During_Simulation.py (~100-200 LOC)

Acceptance Criteria

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
• 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/Dynamics/Condensation/Staggered_Condensation_Example.ipynb --convert-to-py

# 2. Lint the new .py file
ruff check docs/Examples/Dynamics/Condensation/Staggered_Condensation_Example.py --fix
ruff format docs/Examples/Dynamics/Condensation/Staggered_Condensation_Example.py

# 3. Sync linted .py back to .ipynb
python3 .opencode/tool/validate_notebook.py docs/Examples/Dynamics/Condensation/Staggered_Condensation_Example.ipynb --sync

# 4. Execute to check for API issues
python3 .opencode/tool/run_notebook.py docs/Examples/Dynamics/Condensation/Staggered_Condensation_Example.ipynb

# 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/Dynamics/Condensation/Staggered_Condensation_Example.ipynb --check-sync

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-P9] Jupytext Migration: Dynamics/Condensation Part 1 (3 notebooks) #991 - M4-P9 (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: 7f764ec1
Current Phase: Workflow completed successfully
Started: 2026-01-31T02:30:23.890041Z
Last Update: 2026-01-31T04:16:45.768088Z

Current Status

✅ Workflow completed in 1h 46m

Workflow Plan

• ✅ Generate Multi-Review Implementation Plan (at 2026-01-31T02:36:31.668396Z)
• ✅ Build Implementation (at 2026-01-31T02:52:03.587435Z)
• ✅ Validate Implementation and Fix Gaps (at 2026-01-31T03:13:18.409615Z)
• ✅ Run Tests (at 2026-01-31T03:33:58.593846Z)
• ✅ Format Code and Add Docstrings (at 2026-01-31T03:34:41.180254Z)
• ✅ Generate Documentation (at 2026-01-31T04:14:50.252306Z)
• ✅ Ship Implementation (at 2026-01-31T04:16:44.229085Z)

📋 Recent Activity

[2026-01-31T03:13:18.409635Z] Completed step 3/7: Validate Implementation and Fix Gaps
[2026-01-31T03:13:19.991046Z] Starting step 4/7: Run Tests
[2026-01-31T03:33:58.593877Z] Completed step 4/7: Run Tests
[2026-01-31T03:34:00.126882Z] Starting step 5/7: Format Code and Add Docstrings
[2026-01-31T03:34:41.180272Z] Completed step 5/7: Format Code and Add Docstrings
[2026-01-31T03:34:42.785942Z] Starting step 6/7: Generate Documentation
[2026-01-31T04:14:50.252327Z] Completed step 6/7: Generate Documentation
[2026-01-31T04:14:52.166910Z] Starting step 7/7: Ship Implementation
[2026-01-31T04:16:44.229101Z] Completed step 7/7: Ship Implementation
[2026-01-31T04:16:45.766200Z] Workflow complete finished: 7/7 steps completed

🔍 Archived Updates

[2026-01-31T02:30:23.971034Z] Workflow complete started with 7 steps
[2026-01-31T02:30:25.807051Z] Starting step 1/7: Generate Multi-Review Implementation Plan
[2026-01-31T02:36:31.668421Z] Completed step 1/7: Generate Multi-Review Implementation Plan
[2026-01-31T02:36:33.274762Z] Starting step 2/7: Build Implementation
[2026-01-31T02:52:03.587459Z] Completed step 2/7: Build Implementation
[2026-01-31T02:52:05.073716Z] Starting step 3/7: Validate Implementation and Fix Gaps

---

This comment is automatically updated as the workflow progresses

Resume command: adw workflow run complete 992 --adw-id 7f764ec1 --resume