[V3] Phase 4: Multi-Phase Concatenation with Solution Merging

[ocots]

[V3] Phase 4: Multi-Phase Concatenation with Solution Merging

Overview

This issue tracks Phase 4 of the V3 refactoring: multi-phase concatenation architecture with proper solution merging.

Related: Discussion #144
Branch: feature/v3-multi-phase
Depends on: PR #2 (Flow API + Extension)
Documentation:

• V3 Architecture Report
• Planning Report

---

Changes

Architecture

Added:

• src/concatenation.jl:

  • AbstractMultiPhaseSystem{S<:AbstractSystem} (abstract type)
  • MultiPhaseSystem{S} (concrete implementation)
  • PhaseTransition (stores transition time and jumps)
  • evaluate_point(mps, t0, z0, tf, v, options) - integrates each phase sequentially
  • evaluate_solution(mps, tspan, z0, v, options) - stores all phase solutions for merging
  • _merge_solutions(solutions, mps) stub

• ext/CTFlowsSciMLBaseExt.jl:

  • _merge_solutions implementation using batch merging strategy
  • Follows DiffEqParamEstim.jl pattern
  • Uses SciMLBase.build_solution for proper solution merging

Modified:

• Concatenation operator * now creates MultiPhaseSystem instead of concatenating RHS
• Updated test/test_concatenation.jl

---

Concatenation Strategy

V2 Approach (old):

• Concatenate RHS functions: rhs!(t) = t < t_switch ? F.rhs!(t) : G.rhs!(t)
• Single integration from t0 to tf

V3 Approach (new):

• Sequential integration: integrate each phase separately
• Batch merging: store all phase solutions, then merge at the end
• Proper jump handling: apply state/costate jumps between phases

---

API Changes

Before (V2):

f = f1 * (t1, f2)  # Creates concatenated RHS

After (V3):

f = f1 * (t1, f2)  # Creates MultiPhaseSystem{S}

# Point evaluation
xf, pf = f(t0, x0, p0, tf, v)  # Integrates each phase sequentially

# Complete solution
sol = f((t0, tf), x0, p0, v)  # Returns merged ODESolution

---

Breaking Changes

⚠️ Moderate impact - Affects users using flow concatenation.

Behavior change: Concatenation now uses multi-phase architecture instead of RHS switching. This provides:

• ✅ Better solution merging
• ✅ Proper handling of jumps
• ✅ Access to intermediate phase solutions

---

Implementation Checklist

• T4.1: Create src/concatenation.jl with AbstractMultiPhaseSystem{S}, MultiPhaseSystem{S}, and PhaseTransition types
• T4.2: Implement evaluate_point(mps::AbstractMultiPhaseSystem, ...) in src/ (integrates each phase sequentially, applies jumps)
• T4.3: Implement evaluate_solution(mps::AbstractMultiPhaseSystem, ...) in src/ (stores all phase solutions for merging)
• T4.4: Create _merge_solutions(solutions::Vector, mps::AbstractMultiPhaseSystem) stub in src/ with helpful error message
• T4.5: Implement _merge_solutions in ext/CTFlowsSciMLBaseExt.jl using batch merging strategy (concatenate u/t vectors, use SciMLBase.build_solution)
• T4.6: Update concatenation operator * to create MultiPhaseSystem instead of concatenating RHS
• T4.7: Update concatenation tests in test/test_concatenation.jl to test multi-phase evaluation and solution merging

---

Testing

# Run concatenation tests
julia --project=. test/test_concatenation.jl

# Run all tests
julia --project=. -e 'using Pkg; Pkg.test("CTFlows");'

Success criteria:

• All concatenation tests pass
• Multi-phase evaluation works correctly
• Solution merging produces valid ODESolution
• Jumps are applied correctly between phases
• Code coverage ≥ 90% for modified files

---

Documentation

• Update concatenation operator * docstrings
• Add multi-phase examples in docstrings
• Document MultiPhaseSystem architecture
• Add examples with jumps