control-toolbox / control-toolbox/CTDirect.jl
[Roadmap] Consolidate CTDirect following the Handbook philosophy
- Dominant language
- Julia
- Stars
- 12
- Forks
- 5
- Avg merge
- 2h 44m
- Merged PRs (30d)
- 1
Description
## Objective
Consolidate CTDirect following the [control-toolbox Handbook philosophy](https://github.com/control-toolbox/Handbook) to build a better base for future extensions.
## Context
CTDirect (v1.0.12) transcribes a continuous OCP (from CTModels) into an NLP solved through CTSolvers (ADNLPModels / ExaModels backends). The current code is a flat module with symbol-based dispatch, raw field access, duplicated scheme code, and an ExaModels transcription that lives in CTParser instead of CTDirect. A [detailed roadmap](https://github.com/control-toolbox/CTDirect.jl/discussions/609) has been written, following the spirit of what was done for CTFlows.
## Central theme
Abstract the founding ingredients of a transcription so that discretization methods become **recipes** — generic on abstract types (e.g. driven by an arbitrary Butcher tableau), yet overridable with optimized specializations (e.g. midpoint avoiding duplicate evaluations). Everything else follows from getting this abstraction right.
## Key points (from the [detailed roadmap](https://github.com/control-toolbox/CTDirect.jl/discussions/609))
1. **Architecture overhaul** — Move from flat `src/*.jl` to one submodule per responsibility (Schemes, Layouts, Transcriptions, Sparsity, Grids, Discretizers, Solutions), with a strict dependency DAG.
2. **Types, traits, interfaces** — Replace Symbol dispatch with scheme types, use traits for scheme properties (control parametrization, explicit/implicit, stage count, order), define accessor interfaces instead of raw field access, and typed extractors for post-processing (eliminating `occursin` string matching).
3. **Transcription recipe** (the heart) — Reify the ingredients of a direct transcription (unknowns, layout, reconstruction, defects, cost quadrature, constraints, initial guess, work arrays) so that building a DOCP is a generic recipe over abstract types. Two NLP emission backends (ADNLP callables and ExaModels generators) must be an explicit axis from day one.
4. **Butcher tableau as user input** — Users can pass any Butcher tableau directly; named schemes become constructors returning tableaux. Control parametrization becomes an orthogonal option (`:stepwise | :stagewise`).
5. **Own the ExaModels transcription** — Move the ExaModels transcription from CTParser into CTDirect, eliminating duplicated logic that can silently drift, enabling the full scheme catalogue on Exa, and making Exa available for non-`@def` problems.
6. **Sparsity & AD separation** — Split "pattern provision" from "backend choice" — two orthogonal axes currently conflated in a single `backend == :manual` knob.
7. **1-D = scalar** — Pass scalars for 1-D state/control/variable to user OCP functions, consistent with CTFlows. https://github.com/control-toolbox/CTDirect.jl/issues/613
8. **Initial guess** — Pluggable and comparable strategies, with problem-informed defaults at the CTModels level (median of boxes, interpolation between boundary conditions) and proper NLP-level injection (including internal unknowns like stage slopes).
9. **Solution building & outputs** — Typed extractors, duals consolidation, costate/multiplier handling and rescaling.
10. **Direct multiple shooting** — Control/state parametrization decoupled from the ODE scheme; control parametrization as an ingredient independent of the integration scheme.
11. **Free node times, grid rebalancing, mesh refinement** — Free interior nodes as NLP unknowns (switching-time optimization), outer-loop refinement with warm restart.
12. **Impulsive case** — State jumps at selected nodes as a recipe extension — a first step toward non-conventional problems.
13. **Documentation** — Vitepress migration + a "Transcription" guide explaining the exact NLP produced for each scheme family.
14. **Test suite restructuring** — Adopt the Handbook testing template, organize by functionality, add contract tests with fakes.
## Why
A cleaner architectural base will make CTDirect easier to extend and maintain. This consolidation will enable:
- **Direct shooting** extensions (control/state parametrization decoupled from ODE scheme)
- **Multi-phase problems** (via the recipe abstraction)
- **Grid refinement** (via first-class Grids with free nodes)
- **Non-conventional problems** (impulsive, hybrid — via recipe extensions)
- Moving the ExaModels transcription here (from CTParser) separates concerns: CTParser handles parsing, CTDirect handles discretization
## References
- [CTDirect roadmap discussion](https://github.com/control-toolbox/CTDirect.jl/discussions/609)
- [Constructive code review](https://github.com/control-toolbox/CTDirect.jl/discussions/594)
- [Handbook](https://github.com/control-toolbox/Handbook)
- [Roadmap comment](https://github.com/orgs/control-toolbox/discussions/68#discussioncomment-17584843)
Contributor guide
Assessment
This issue has not been assessed yet.