@@ -9,8 +9,14 @@ It provides the **mathematical model layer** for optimal control problems:
99
1010- ** types and building blocks** for states, controls, variables, time grids, and constraints;
1111- an ` AbstractModel ` /` Model ` and ` AbstractSolution ` /` Solution ` hierarchy for optimal control problems;
12- - tools to build ** initial guesses** , connect to ** NLP backends** , and interpret their solutions;
13- - optional extensions for ** exporting solutions** (JSON/JLD) and ** plotting** .
12+ - tools to build ** initial guesses** for optimization;
13+ - optional extensions for ** exporting/importing solutions** (JSON/JLD) and ** plotting** .
14+
15+ !!! info "CTModels vs CTSolvers"
16+
17+ **CTModels** focuses on **defining** optimal control problems and representing their solutions.
18+ For **solving** these problems (discretization, NLP backends, optimization strategies),
19+ see [CTSolvers.jl](https://github.com/control-toolbox/CTSolvers.jl).
1420
1521!!! note
1622
@@ -64,25 +70,11 @@ At a high level, CTModels is responsible for:
6470 ` AbstractSolution ` / ` Solution ` store state, control, dual variables, and solver information.
6571- ** Managing time grids and dimensions** through convenient type aliases.
6672- ** Structuring constraints** (path, boundary, box constraints on state, control, and variables).
67- - ** Connecting to NLP backends** (ADNLPModels, ExaModels, etc.) via modelers and builders.
68- - ** Strategy architecture** (NEW):
69- - ** Options** : Generic option handling with aliases and validation
70- - ** Strategies** : Configurable components (modelers, solvers, discretizers)
7173- ** Providing utilities** for initial guesses, export/import, and plotting of solutions.
7274
7375Most of the public API is organized in a way that closely mirrors the mathematical
7476objects you manipulate when formulating an optimal control problem.
7577
76- ## Strategy Architecture
77-
78- CTModels provides a modern, type-stable architecture for configurable components:
79-
80- - ** Options Module** : Low-level option extraction, validation, and alias resolution.
81- - ** Strategies Module** : Strategy contract, metadata, registry, and builders.
82-
83- This architecture replaces the legacy ` AbstractOCPTool ` interface with a cleaner,
84- more maintainable design. See the ** Developer Guide → Interfaces → Strategies** section for details.
85-
8678## Time grids and basic aliases
8779
8880CTModels defines a few central type aliases that appear throughout the API:
@@ -121,37 +113,30 @@ These objects are the main bridge between the mathematical problem and the NLP b
121113## Initial guesses
122114
123115Good initial guesses are crucial for challenging optimal control problems.
124- CTModels provides a small layer to organize them:
116+ CTModels provides a layer to organize them:
125117
126118- ` pre_initial_guess ` builds an ` OptimalControlPreInit ` object from raw user data
127119 (functions, vectors, or constants for state, control, and variables).
128120- ` initial_guess ` turns this into an ` OptimalControlInitialGuess ` , checking consistency
129- with the chosen ` AbstractOptimalControlProblem ` .
130-
131- The corresponding API is implemented in ` src/init/initial_guess.jl ` and is documented
132- in the * Initial Guess* section of the API reference.
133-
134- ## NLP backends and modelers
135-
136- CTModels does ** not** solve the NLP itself. Instead, it connects to external NLP
137- backends via modelers and builders defined in ` src/nlp/ ` :
121+ with the chosen ` AbstractModel ` .
122+ - ` build_initial_guess ` constructs initial guess objects from various input formats.
123+ - ` validate_initial_guess ` ensures consistency with the problem dimensions.
138124
139- - ` ADNLPModeler ` (based on ` ADNLPModels.jl ` ),
140- - ` ExaModeler ` (based on ` ExaModels.jl ` ),
141- - additional builder types and helper functions.
125+ The corresponding API is documented in the * InitialGuess* section of the API reference.
142126
143- These modelers:
127+ ## Solving optimal control problems
144128
145- - expose options through the generic ` AbstractOCPTool ` interface from CTBase
146- (see the * Interfaces → OCP Tools* page),
147- - build backend-specific NLP models from an ` AbstractOptimizationProblem ` ,
148- - optionally map NLP solutions back to ` CTModels.Solution ` objects.
129+ CTModels defines the ** problem structure** but does ** not** solve it.
130+ For solving optimal control problems, use [ CTSolvers.jl] ( https://github.com/control-toolbox/CTSolvers.jl ) ,
131+ which provides:
149132
150- The * Interfaces* section of the documentation contains detailed guides for:
133+ - ** Discretization strategies** (direct collocation, multiple shooting, etc.)
134+ - ** NLP backends** (ADNLPModels, ExaModels, etc.)
135+ - ** Optimization modelers** to connect problems to solvers
136+ - ** Strategy architecture** for configurable components
151137
152- - implementing new ** optimization problems** ,
153- - implementing new ** optimization modelers** , and
154- - implementing new ** OCP solution builders** .
138+ CTModels provides the ` AbstractModel ` type alias ` AbstractOptimalControlProblem `
139+ for compatibility with CTSolvers.
155140
156141## Extensions: JSON, JLD, and plotting
157142
@@ -183,56 +168,37 @@ throw a descriptive `CTBase.ExtensionError`.
183168
184169## How this documentation is organized
185170
186- The documentation is split into two main parts:
187-
188- - ** Interfaces**
189- - * OCP Tools* : how to implement new configurable tools (backends, discretizers, solvers).
190- - * Optimization Problems* : how to define ` AbstractOptimizationProblem ` types.
191- - * Optimization Modelers* : how to map optimization problems to specific NLP backends.
192- - * Solution Builders* : how to turn NLP execution statistics into ` CTModels.Solution ` objects.
193-
194- - ** API Reference**
195- - * Types* : core types for models, solutions, and internal structures.
196- - * Model / Times / Dynamics / Objective / Constraints* : detailed API for building OCP models.
197- - * Solution & Dual* : how solutions and dual variables are represented.
198- - * Initial Guess* : utilities to build and validate initial guesses.
199- - * NLP Backends* : ADNLPModels/ExaModels-based backends and related options.
200- - * Extensions* : Plot, JSON, and JLD extensions.
201-
202- You can start by reading the ** Interfaces** pages to understand the high-level
203- design, then use the ** API Reference** to look up the details of particular
204- functions and types.
205-
206- ## I am X, I want to do Y → read…
207-
208- ### User Guide
209-
210- - ** I want to formulate a new optimal control / optimization problem**
211- Read ** User Guide → Optimization Problems** , then ** API Reference → Model / Times / Dynamics / Objective / Constraints**
212- for details about fields and conventions.
213- - ** I want to build good initial guesses for my problems**
214- Read ** User Guide → Solution Builders** for the overall philosophy, then ** API Reference → Initial Guess**
215- for the ` pre_initial_guess ` and ` initial_guess ` functions.
216- - ** I want to save / reload solutions (for example for numerical experiments)**
217- Read ** API Reference → Extensions (JSON & JLD)** and the pages associated with the ` CTModelsJSON ` and ` CTModelsJLD ` modules.
218- - ** I want to plot solution trajectories nicely**
219- Read ** API Reference → Extensions (Plot Extension)** , and look at the examples using ` Plots.plot(sol) ` and ` Plots.plot!(sol) ` .
220- - ** I use OptimalControl.jl and I just want to understand what CTModels does in the background**
221- Read this introduction page, then skim through the ** User Guide** section to see how
222- problems, modelers, and builders fit together.
223-
224- ### Developer Guide
225-
226- - ** I want to create a new strategy (modeler, solver, discretizer)**
227- Read ** Developer Guide → Tutorials → Creating a Strategy** , then ** Developer Guide → Interfaces → Strategies**
228- for the complete contract specification.
229- - ** I want to create a family of related strategies**
230- Read ** Developer Guide → Tutorials → Creating a Strategy Family** , then ** Developer Guide → Interfaces → Strategy Families**
231- for registry integration and best practices.
232- - ** I want to migrate from AbstractOCPTool to AbstractStrategy**
233- Read ** Developer Guide → Interfaces → Strategies → Migration Guide** for step-by-step instructions.
234- - ** I want to connect a new NLP backend or tweak an existing backend**
235- Read ** Developer Guide → Interfaces → Optimization Modelers** (updated) and the ** API Reference → NLP Backends** section.
236- - ** I want to contribute to the core of CTModels (types, constraints, dual variables, etc.)**
237- Start with ** API Reference → Types** , then ** Solution & Dual** and ** Constraints** to understand the internal structures
238- before modifying or adding new fields.
171+ The documentation consists of:
172+
173+ - ** Introduction** (this page): Overview of CTModels and its role in the control-toolbox ecosystem.
174+
175+ - ** API Reference** : Complete documentation of all modules and functions:
176+ - * CTModels* : Main module and exports
177+ - * Utils* : Utilities (interpolation, macros, matrix operations)
178+ - * OCP* : Optimal Control Problem types, components, building, and validation
179+ - * Display* : Text display and printing
180+ - * Serialization* : Export/import functionality
181+ - * InitialGuess* : Initial guess management
182+ - * Extensions* : Plots, JSON, and JLD2 extensions
183+
184+ Use the ** API Reference** to look up the details of particular functions and types.
185+
186+ ## Quick start guide
187+
188+ - ** I want to define an optimal control problem**
189+ See ** API Reference → OCP Components** for ` state! ` , ` control! ` , ` dynamics! ` , ` objective! ` , ` constraint! ` , etc.
190+
191+ - ** I want to build initial guesses**
192+ See ** API Reference → InitialGuess** for ` pre_initial_guess ` , ` initial_guess ` , and ` build_initial_guess ` .
193+
194+ - ** I want to save/load solutions**
195+ See ** API Reference → Serialization** and the JSON/JLD2 extension pages for ` export_ocp_solution ` and ` import_ocp_solution ` .
196+
197+ - ** I want to plot solution trajectories**
198+ See ** API Reference → Plots Extension** for ` plot(sol) ` and ` plot!(sol) ` with ` Plots.jl ` .
199+
200+ - ** I want to solve an optimal control problem**
201+ Use [ CTSolvers.jl] ( https://github.com/control-toolbox/CTSolvers.jl ) which provides discretization, NLP backends, and optimization strategies.
202+
203+ - ** I use OptimalControl.jl**
204+ CTModels provides the underlying types and building blocks. OptimalControl.jl offers a higher-level interface.
0 commit comments