Skip to content

[Roadmap] Consolidate CTDirect following ct-conventions #610

Open

Description

@ocots

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)

  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. 1-D = scalar: pass scalars for 1-D state/control/variable to user OCP functions (§7) #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 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

References

Activity

  1. changed the title [-][Roadmap] Consolidate CTDirect following the Handbook philosophy[/-] [+][Roadmap] Consolidate CTDirect following ct-conventions[/+] on Oct 16, 2026
  2. ocots commented on Nov 6, 2026

    @ocots
    MemberAuthor

    Notes from writing the schemes as Butcher tableaux in the JuMP models of OptimalControlProblems.jl (control-toolbox/OptimalControlProblems.jl#383), for when Schemes is written here.

    What was done there.

    • A tableau is a value (A::Matrix{Float64}, b, c).
    • Every property is computed from the tableau, never declared: stiffly accurate, explicit first stage, FSAL, final control, stage positions.
    • One trait selects the evaluation of the dynamics by dispatch: stage_reuse(tab) returns FirstSameAsLast() or NoStageReuse(), subtypes of CTBase.Traits.AbstractTrait. With FSAL, the dynamics are evaluated once per node (§3.3).

    This is enough for JuMP.

    • The traits run once per build, and their cost is too small to measure.
    • FSAL saves about 15 % memory and 3–7 % time at build (N = 1000).
    • It saves nothing at evaluation, because JuMP does not share a subexpression between constraints.

    Here evaluation is the hot path, so two points will matter:

    1. 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:

      • one type per scheme (Trapeze <: AbstractScheme), whose tableau is an isbits constant (tuples or SMatrix);
      • the traits computed from that constant.

      The traits then constant-fold and the dispatch is static. No trait is declared by hand, so none can contradict its tableau.

    2. Use exact coefficients for the comparisons. Tests such as A[end, :] == b (stiffly accurate) are exact for 0, ½ and 1. In Float64 they become fragile for 1/3 (Lobatto, Radau) or for the square roots of Gauss–Legendre. Store the catalogue tableaux as Rational where possible and convert to the working float type at evaluation; otherwise compare with a tolerance.

    OptimalControlProblems uses only AbstractTrait as a supertype. The full CTBase pattern (has_<family>_trait, accessor, predicates) belongs here.

  3. ocots commented on Nov 6, 2026

    @ocots
    MemberAuthor

    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:

    CTParser then only translates the problem and drops its :exa discretization (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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions