Repository navigation
Description
Objective
Consolidate CTDirect following the ct-conventions rules 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 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)
- Architecture overhaul — Move from flat
src/*.jlto one submodule per responsibility (Schemes, Layouts, Transcriptions, Sparsity, Grids, Discretizers, Solutions), with a strict dependency DAG. - 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
occursinstring matching). - 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.
- 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). - 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-
@defproblems. - Sparsity & AD separation — Split "pattern provision" from "backend choice" — two orthogonal axes currently conflated in a single
backend == :manualknob. - 1-D = scalar — Pass scalars for 1-D state/control/variable to user OCP functions, consistent with CTFlows. 1-D = scalar: pass scalars for 1-D state/control/variable to user OCP functions (§7) #613
- 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).
- Solution building & outputs — Typed extractors, duals consolidation, costate/multiplier handling and rescaling.
- Direct multiple shooting — Control/state parametrization decoupled from the ODE scheme; control parametrization as an ingredient independent of the integration scheme.
- Free node times, grid rebalancing, mesh refinement — Free interior nodes as NLP unknowns (switching-time optimization), outer-loop refinement with warm restart.
- Impulsive case — State jumps at selected nodes as a recipe extension — a first step toward non-conventional problems.
- Documentation — Vitepress migration + a "Transcription" guide explaining the exact NLP produced for each scheme family.
- Test suite restructuring — Adopt the ct-conventions test file template (
TST1), 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
Activity
Implement "1-D = scalar" call-boundary coercion (#610 §7 / #613)
[-][Roadmap] Consolidate CTDirect following the Handbook philosophy[/-][+][Roadmap] Consolidate CTDirect following ct-conventions[/+]ocots commentedon Nov 6, 2026
Notes from writing the schemes as Butcher tableaux in the JuMP models of OptimalControlProblems.jl (control-toolbox/OptimalControlProblems.jl#383), for when
Schemesis written here.What was done there.
A::Matrix{Float64},b,c).stage_reuse(tab)returnsFirstSameAsLast()orNoStageReuse(), subtypes ofCTBase.Traits.AbstractTrait. With FSAL, the dynamics are evaluated once per node (§3.3).This is enough for JuMP.
Here evaluation is the hot path, so two points will matter:
Take the traits from the type, but still compute them. §2.2 puts a trait in the type when it changes the layout of the variables, and the number of controls does. Both goals can hold:
Trapeze <: AbstractScheme), whose tableau is an isbits constant (tuples orSMatrix);The traits then constant-fold and the dispatch is static. No trait is declared by hand, so none can contradict its tableau.
Use exact coefficients for the comparisons. Tests such as
A[end, :] == b(stiffly accurate) are exact for 0, ½ and 1. InFloat64they become fragile for 1/3 (Lobatto, Radau) or for the square roots of Gauss–Legendre. Store the catalogue tableaux asRationalwhere possible and convert to the working float type at evaluation; otherwise compare with a tolerance.OptimalControlProblems uses only
AbstractTraitas a supertype. The full CTBase pattern (has_<family>_trait, accessor, predicates) belongs here.ocots commentedon Nov 6, 2026
Written by Claude (Claude Code) at the request of ocots.
To do before §3 and §5 of this roadmap: the modeler-agnostic transcription, tracked in #673.
The recipe of §3 must be written against an NLP emission axis, and §5 must give it to Exa. Rather than one emission per modeler inside CTDirect, the design of #673 makes CTDirect write each transcription once, holding the modeler and passing it to two APIs that dispatch on it:
CTModels.dynamics(ocp, modeler), selected throughCTModels.required_form(modeler)among redundant representations stored in CTModels (in-place, traceable, expression, sparsity): Components with several representations, selected by the modeler (required_form) CTModels.jl#516;add_variables!,add_constraints!,add_objective!,build, implemented by each modeler in CTSolvers, where the modelers stay: Generic NLP-building API dispatched on the modeler, and required_form for ADNLP and Exa CTSolvers.jl#319.CTParser then only translates the problem and drops its
:exadiscretization (control-toolbox/CTParser.jl#415). CTDirect no longer depends on ADNLPModels, ExaModels or CTParser, and a JuMP modeler (control-toolbox/CTSolvers.jl#320) needs no change in CTDirect.First deliverable: the prototype #674 (extends §5 item 1), which fixes the forms and the calling convention. Order: #674 → CTModels#516 → CTSolvers#319 and CTParser#415 → §3/§5 here → CTSolvers#320.