[Phase E3-F4-P5] Documentation, migration guide, and update dev-docs

[Gorkowski]

Dependencies:

#1068 [E3-F4-P1] ──┐
│
#1069 [E3-F4-P2] ──┼──► #THIS [E3-F4-P5]
│
#1070 [E3-F4-P3] ──┤
│
#1071 [E3-F4-P4] ──┘

Parent Issue: #1020

Dependencies:

• E3-F4-P1: [Phase E3-F4-P1] Create ParticleRepresentation facade over ParticleData with deprecation warnings and tests #1068
• E3-F4-P2: [Phase E3-F4-P2] Create GasSpecies facade over GasData with deprecation warnings and tests #1069
• E3-F4-P3: [Phase E3-F4-P3] Update CondensationIsothermal to accept both old and new data types with tests #1070
• E3-F4-P4: [Phase E3-F4-P4] Update Coagulation strategies to accept both old and new data types with tests #1071

---

Description

Create comprehensive documentation for the ParticleData/GasData migration, including a user-facing migration guide, updated architecture documentation, and README migration notes. This phase documents the work completed in P1-P4 and provides clear guidance for users transitioning from the legacy ParticleRepresentation/GasSpecies APIs to the new data containers.

Context

This is the fifth and final phase of E3-F4. All implementation work is complete by this point - the facades (P1 #1068, P2 #1069) and dual-type dynamics support (P3 #1070, P4 #1071) are in place. This phase focuses exclusively on documentation.

Parent Issue: #1020 (E3-F4: Facade and Migration)
Depends on: #1068, #1069, #1070, #1071 (all implementation phases must be complete)

Value:

• Clear migration path reduces user friction during transition
• Architecture documentation captures design decisions for future maintainers
• Updated README alerts new users to the preferred API

Scope

Estimated Lines of Code: ~300 lines of documentation
Complexity: Medium

Files to Create:

• docs/migration/particle-data.md (~300 lines) - User-facing migration guide

Files to Modify:

• adw-docs/architecture/architecture_guide.md (~50 LOC additions) - Document facade pattern and data container architecture
• readme.md (~20 LOC additions) - Migration notes section
• adw-docs/dev-plans/features/E3-F4-facade-migration.md - Update status to Shipped

Acceptance Criteria

Migration Guide (docs/migration/particle-data.md)

• Overview section explaining the motivation for ParticleData/GasData
• "Why Migrate?" section listing benefits (extensibility, GPU acceleration, immutability, cleaner code)
• "Quick Migration" section with before/after code examples
• "ParticleRepresentation to ParticleData" subsection with:
  • Constructor migration (old __init__ args -> ParticleData dataclass)
  • Method mapping table (e.g., get_radius() -> .radii, get_mass() -> .total_mass)
  • Strategy separation explanation (activity, surface strategies are now separate)
• "GasSpecies to GasData" subsection with:
  • Constructor migration (old __init__ args -> GasData dataclass)
  • Method mapping table (e.g., get_concentration() -> .concentration[0])
  • Vapor pressure strategy separation explanation
• "Gradual Migration" section showing how to use .data property from facades
• "Using New Types in Dynamics" section showing condensation and coagulation with ParticleData/GasData
• "Conversion Helpers" section documenting from_representation(), to_representation(), from_species(), to_species()
• "Deprecation Timeline" section: deprecated in v0.3.0, removal planned for v1.0
• "Troubleshooting" section for common migration issues

Architecture Documentation Updates

• Document the facade pattern in adw-docs/architecture/architecture_guide.md
• Add data container section explaining ParticleData and GasData design
• Document the dual-type support pattern in dynamics modules
• Update module dependency diagram if present

README Updates

• Add "Migration" or "What's New" section noting the ParticleData/GasData transition
• Link to the migration guide
• Note that ParticleRepresentation and GasSpecies are deprecated but still functional

Dev-Docs Updates

• Update E3-F4-facade-migration.md status from Planning to Shipped
• Update phase checklist with issue numbers ([Phase E3-F4-P1] Create ParticleRepresentation facade over ParticleData with deprecation warnings and tests #1068-[Phase E3-F4-P4] Update Coagulation strategies to accept both old and new data types with tests #1071)
• Update Last Updated date

Technical Notes

Migration Guide Structure

The guide should follow this structure based on the feature plan:

# Migration Guide: ParticleRepresentation to ParticleData

## Overview
In particula v0.3.0, we introduced `ParticleData` and `GasData` as pure
data containers, separating data from behavior...

## Why Migrate?
1. **Extensibility**: Add custom fields by subclassing ParticleData
2. **GPU Acceleration**: ParticleData works with NVIDIA Warp backend
3. **Immutability**: Data containers prevent accidental mutations
4. **Cleaner Code**: Separate data from behavior strategies

## Quick Migration

### Before (Legacy)
    from particula.particles import ParticleRepresentation
    rep = ParticleRepresentation(strategy=..., activity=..., ...)
    rep.add_mass(added_mass)  # Mutates in place

### After (New)
    from particula.particles.particle_data import ParticleData
    data = ParticleData(masses=..., concentration=..., ...)
    # Use functional operations that return new instances

## Method Mapping

| Legacy (`ParticleRepresentation`) | New (`ParticleData`) |
|---|---|
| `get_radius()` | `.radii[box_idx]` |
| `get_mass()` | `.total_mass[box_idx]` |
| `get_species_mass()` | `.masses[box_idx]` |
| `get_concentration()` | `.concentration[box_idx]` |
| `get_charge()` | `.charge[box_idx]` |
| `get_effective_density()` | `.effective_density[box_idx]` |
| `get_density()` | `.density` |
| `get_volume()` | `.volume[box_idx]` |

| Legacy (`GasSpecies`) | New (`GasData`) |
|---|---|
| `get_name()` | `.name` |
| `get_molar_mass()` | `.molar_mass` |
| `get_concentration()` | `.concentration[box_idx]` |
| `get_partitioning()` | `.partitioning` |

## Gradual Migration
    # Existing code still works (with deprecation warning)
    rep = ParticleRepresentation(...)
    # Access new data container
    data = rep.data  # ParticleData instance

## Conversion Helpers
    from particula.particles.particle_data import from_representation, to_representation
    from particula.gas.gas_data import from_species, to_species

## Using New Types in Dynamics
    # Condensation with ParticleData
    new_particle, new_gas = strategy.step(particle_data, gas_data, ...)
    
    # Coagulation with ParticleData
    updated = coag_strategy.step(particle_data, 298.15, 101325.0, 1.0)

## Deprecation Timeline
- v0.3.0: ParticleRepresentation and GasSpecies deprecated
- v1.0.0: Legacy classes removed (planned)

## Troubleshooting
- DeprecationWarning on construction: Expected, use ParticleData/GasData
- Suppress warnings: warnings.filterwarnings("ignore", category=DeprecationWarning)

Integration Points

• Links to particula/particles/particle_data.py API
• Links to particula/gas/gas_data.py API
• Links to conversion helpers (from_representation, to_representation, from_species, to_species)

References

Feature Plan:

• adw-docs/dev-plans/features/E3-F4-facade-migration.md - Feature plan to update status

Related Issues:

• [E3-F4] Facade and Migration #1020 - Parent feature issue
• [Phase E3-F4-P1] Create ParticleRepresentation facade over ParticleData with deprecation warnings and tests #1068 - E3-F4-P1: ParticleRepresentation facade
• [Phase E3-F4-P2] Create GasSpecies facade over GasData with deprecation warnings and tests #1069 - E3-F4-P2: GasSpecies facade
• [Phase E3-F4-P3] Update CondensationIsothermal to accept both old and new data types with tests #1070 - E3-F4-P3: Condensation dual-type support
• [Phase E3-F4-P4] Update Coagulation strategies to accept both old and new data types with tests #1071 - E3-F4-P4: Coagulation dual-type support

Related Code:

• particula/particles/particle_data.py - ParticleData container
• particula/gas/gas_data.py - GasData container
• particula/particles/representation.py - ParticleRepresentation facade
• particula/gas/species.py - GasSpecies facade

Coding Standards:

• adw-docs/code_style.md - Python standards
• adw-docs/docstring_guide.md - Documentation format