[V3] Phases 2+3: Flow API Simplification + SciMLBase Extension

[ocots]

[V3] Phases 2+3: Flow API Simplification + SciMLBase Extension

Overview

This issue tracks Phases 2 and 3 of the V3 refactoring: simplifying the Flow API with positional control arguments and implementing the SciMLBase extension architecture.

Related: Discussion #144
Branch: feature/v3-flow-api
Depends on: PR #1 (Differential Geometry Refactoring)
Documentation:

• V3 Architecture Report
• Planning Report

---

Changes

Phase 2: Flow API Simplification

Removed:

• Hamiltonian/VectorField flow constructors (ext/hamiltonian.jl, ext/vector_field.jl)
• Control wrappers: ControlLaw, FeedbackControl, StateConstraint, MixedConstraint, Multiplier
• Test files: test_flow_hamiltonian.jl, test_flow_vector_field.jl, test_flow_hamiltonian_vector_field.jl

Added/Modified:

• New OCP flow API with optional control_type (default :dynamic_feedback):
  • Flow(ocp, u)
  • Flow(ocp, u, :state_feedback)
  • Flow(ocp, u, :dynamic_feedback, g, μ) (with constraints)
• ODEFunction flow constructor (supports OOP and IP)
• Updated all flow tests

Phase 3: SciMLBase Extension

Added:

• src/stubs.jl with helpful error messages:
  • _ode_problem(system, tspan, z0, params)
  • _solve(problem, alg, options)
• Extension ext/CTFlowsSciMLBaseExt.jl (renamed from CTFlowsODE.jl)
• Updated Project.toml: replaced OrdinaryDiffEq with SciMLBase (lighter dependency)

---

API Changes

Before (V2):

u = ControlLaw((x, p) -> p[2])
f = Flow(ocp, u)

# With constraints
f = Flow(ocp, u, g, μ)

After (V3):

# Default :dynamic_feedback
f = Flow(ocp, (x, p) -> p[2])

# Explicit control type
f = Flow(ocp, x -> -x, :state_feedback)

# With constraints
f = Flow(ocp, (x, p) -> p[2], :dynamic_feedback, g, μ)

---

Breaking Changes

⚠️ Major impact - All Flow API users affected.

Users need to:

1. Remove control wrappers (ControlLaw(...), FeedbackControl(...))
2. Add optional control_type argument (or rely on default :dynamic_feedback)
3. Load a SciML solver package (using OrdinaryDiffEq)

---

Why Combine Phases 2+3?

The extension (Phase 3) is required to test the Flow API (Phase 2). Splitting would create an untestable PR.

---

Implementation Checklist

Phase 2: Flow API Simplification

• T2.1: Remove standalone Hamiltonian flow constructors (ext/hamiltonian.jl)
• T2.2: Remove VectorField flow constructors (ext/vector_field.jl)
• T2.3: Remove ControlLaw, FeedbackControl, StateConstraint, MixedConstraint, Multiplier wrappers from src/types.jl
• T2.4: Create new OCP flow constructors with optional control_type (default :dynamic_feedback)
• T2.5: Implement control type dispatch logic in ext/optimal_control_problem.jl
• T2.6: Update ODEFunction flow constructor (OOP and IP support)
• T2.7: Update all flow tests (test/test_flow_*.jl, test/test_optimal_control_problem.jl)
• T2.8: Remove test/test_flow_hamiltonian.jl, test/test_flow_vector_field.jl, test/test_flow_hamiltonian_vector_field.jl

Phase 3: Extension and Stub Implementation

• T3.1: Create src/stubs.jl with _ode_problem and _solve stubs
• T3.2: Implement helpful error messages in stubs
• T3.3: Rename ext/CTFlowsODE.jl to ext/CTFlowsSciMLBaseExt.jl
• T3.4: Update extension to override _ode_problem and _solve
• T3.5: Update Project.toml with SciMLBase extension (remove OrdinaryDiffEq)
• T3.6: Test extension loading and error messages

---

Testing

# Run flow tests
julia --project=. test/test_optimal_control_problem.jl
julia --project=. test/test_flow_function.jl

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

# Test extension loading
julia --project=. -e 'using CTFlows; Flow(ocp, u)'  # Should error with helpful message
julia --project=. -e 'using CTFlows, OrdinaryDiffEq; Flow(ocp, u)'  # Should work

Success criteria:

• All flow tests pass with new API
• Extension loads correctly
• Helpful error messages when extension not loaded
• Code coverage ≥ 90% for modified files

---

Documentation

• Update Flow API docstrings
• Update README.md with V3 examples
• Add migration examples in docstrings
• Document extension loading requirements