control-toolbox · ocots · Jun 17, 2025 · Jun 15, 2025 · Jun 15, 2025 · Jun 15, 2025
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -6,6 +6,7 @@ CTFlows = "1c39547c-7794-42f7-af83-d98194f657c2"
 CTModels = "34c4fa32-2049-4079-8329-de33c2a22e2d"
 CTParser = "32681960-a1b1-40db-9bff-a1ca817385d1"
 CommonSolve = "38540f10-b2f7-11e9-35d8-d573e4eb0ff2"
+DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
 DocumenterMermaid = "a078cd44-4d9c-4618-b545-3ab9d77f9177"

diff --git a/docs/make.jl b/docs/make.jl
@@ -101,7 +101,7 @@ cp("./docs/Project.toml", "./docs/src/assets/Project.toml"; force=true)
 repo_url = "github.com/control-toolbox/OptimalControl.jl"
 
 makedocs(;
-    draft=false, # if draft is true, then the julia code from .md is not executed
+    draft=true, # if draft is true, then the julia code from .md is not executed
     # to disable the draft mode in a specific markdown file, use the following:
     # ```@meta
     # Draft = false
@@ -125,11 +125,13 @@ makedocs(;
         ],
         "Manual" => [
             "Define a problem" => "manual-abstract.md",
+            "Problem characteristics" => "manual-model.md",
             "Set an initial guess" => "manual-initial-guess.md",
             "Solve a problem" => "manual-solve.md",
+            "Solution characteristics" => "manual-solution.md",
             "Plot a solution" => "manual-plot.md",
             "Compute flows" => [
-                "Getting started" => "manual-flow-api.md",
+                "Flow API" => "manual-flow-api.md",
                 "From optimal control problems" => "manual-flow-ocp.md",
                 "From Hamiltonian and others" => "manual-flow-others.md",
             ],

diff --git a/docs/src/api-ctbase.md b/docs/src/api-ctbase.md
@@ -29,4 +29,4 @@ M --> B
 style B fill:#FBF275
 ```
 
-OptimalControl heavily relies on CTBase. Refer to the [CTBase API documentation](@extref CTBase index) for more details.
+OptimalControl heavily relies on CTBase. We refer to [CTBase API](@extref CTBase index) for more details.
diff --git a/docs/src/api-ctdirect.md b/docs/src/api-ctdirect.md
@@ -29,4 +29,4 @@ M --> B
 style D fill:#FBF275
 ```
 
-OptimalControl heavily relies on CTDirect. Refer to the [CTDirect API documentation](@extref CTDirect index) for more details.
+OptimalControl heavily relies on CTDirect. We refer to [CTDirect API](@extref CTDirect index) for more details.
diff --git a/docs/src/api-ctflows.md b/docs/src/api-ctflows.md
@@ -29,4 +29,4 @@ M --> B
 style F fill:#FBF275
 ```
 
-OptimalControl heavily relies on CTFlows. Refer to the [CTFlows API documentation](@extref CTFlows index) for more details.
+OptimalControl heavily relies on CTFlows. We refer to [CTFlows API](@extref CTFlows index) for more details.
diff --git a/docs/src/api-ctmodels.md b/docs/src/api-ctmodels.md
@@ -29,4 +29,4 @@ M --> B
 style M fill:#FBF275
 ```
 
-OptimalControl heavily relies on CTModels. Refer to the [CTModels API documentation](@extref CTModels index) for more details.
+OptimalControl heavily relies on CTModels. We refer to [CTModels API](@extref CTModels index) for more details.
diff --git a/docs/src/api-ctparser.md b/docs/src/api-ctparser.md
@@ -29,4 +29,4 @@ M --> B
 style P fill:#FBF275
 ```
 
-OptimalControl heavily relies on CTParser. Refer to the [CTParser API documentation](@extref CTParser index) for more details.
+OptimalControl heavily relies on CTParser. We refer to [CTParser API](@extref CTParser index) for more details.
diff --git a/docs/src/api-optimalcontrol-user.md b/docs/src/api-optimalcontrol-user.md
@@ -28,31 +28,6 @@ Order   = [:module]
 Private = false
 ```
 
-## Index
-
-```@index
-Pages   = ["api-optimalcontrol-user.md"]
-Modules = [
-    OptimalControl,
-    CommonSolve, 
-    RecipesBase,
-    CTBase, 
-    CTDirect, 
-    CTFlows, 
-    CTModels, 
-    CTParser, 
-    CTFlowsODE, 
-    CTModelsPlots, 
-    CTModelsJSON, 
-    CTModelsJLD,
-    CTSolveExtIpopt,
-    CTSolveExtKnitro,
-    CTSolveExtMadNLP,
-]
-
-Order = [:module, :constant, :type, :function, :macro]
-```
-
 ## Documentation
 
 ```@docs; canonical=true
@@ -70,15 +45,12 @@ Poisson
 Solution
 VectorField
 available_methods
-boundary_constraints_dual
 build_OCP_solution
 constraint
+constraints
 constraints_violation
 control
 control_components
-control_constraints_box
-control_constraints_lb_dual
-control_constraints_ub_dual
 control_dimension
 control_name
 costate
@@ -91,6 +63,7 @@ dynamics
 export_ocp_solution
 final_time
 final_time_name
+get_build_examodel
 has_fixed_final_time
 has_fixed_initial_time
 has_free_final_time
@@ -107,26 +80,20 @@ lagrange
 mayer
 message
 objective
-path_constraints_dual
 plot(::Solution, ::Symbol...)
 plot!(::Plots.Plot, ::Solution, ::Symbol...)
 set_initial_guess
 solve(::Model, ::Symbol...)
 state
 state_components
-state_constraints_box
-state_constraints_lb_dual
-state_constraints_ub_dual
 state_dimension
 state_name
 stopping
 time_grid
 time_name
+times
 variable
 variable_components
-variable_constraints_box
-variable_constraints_lb_dual
-variable_constraints_ub_dual
 variable_dimension
 variable_name
 ⋅

diff --git a/docs/src/assets/Manifest.toml b/docs/src/assets/Manifest.toml
@@ -2,7 +2,7 @@
 
 julia_version = "1.11.5"
 manifest_format = "2.0"
-project_hash = "619f0fb19f859094e1399a5b2427138fe211e67a"
+project_hash = "aedb19159ec43d1fc78401e06abaeeb58fd73c61"
 
 [[deps.ADNLPModels]]
 deps = ["ADTypes", "ForwardDiff", "LinearAlgebra", "NLPModels", "Requires", "ReverseDiff", "SparseArrays", "SparseConnectivityTracer", "SparseMatrixColorings"]
@@ -180,9 +180,9 @@ version = "0.2.6"
 
 [[deps.CTBase]]
 deps = ["DocStringExtensions"]
-git-tree-sha1 = "1e0fb19f883cda373412fd40f2ccad71758cb876"
+git-tree-sha1 = "ebc7d07d0bf4db7a841c5e7d51b4271bcf1e921c"
 uuid = "54762871-cc72-4466-b8e8-f6c8b58076cd"
-version = "0.16.1"
+version = "0.16.2"
 
 [[deps.CTDirect]]
 deps = ["ADNLPModels", "CTBase", "CTModels", "CTParser", "DocStringExtensions", "HSL", "MKL", "NLPModelsIpopt", "SparseArrays"]
@@ -208,9 +208,9 @@ weakdeps = ["OrdinaryDiffEq"]
 
 [[deps.CTModels]]
 deps = ["CTBase", "DocStringExtensions", "Interpolations", "LinearAlgebra", "MLStyle", "MacroTools", "OrderedCollections", "Parameters", "PrettyTables", "RecipesBase"]
-git-tree-sha1 = "dec8ae920442bbb4deedb9ca40619c58702b94a5"
+git-tree-sha1 = "73b95a01af8369b5b08d1ecf3edf6b0bb79ce2c3"
 uuid = "34c4fa32-2049-4079-8329-de33c2a22e2d"
-version = "0.5.3"
+version = "0.5.4"
 weakdeps = ["JLD2", "JSON3", "Plots"]
 
     [deps.CTModels.extensions]
@@ -371,6 +371,12 @@ git-tree-sha1 = "abe83f3a2f1b857aac70ef8b269080af17764bbe"
 uuid = "9a962f9c-6df0-11e9-0e5d-c546b8b5ee8a"
 version = "1.16.0"
 
+[[deps.DataFrames]]
+deps = ["Compat", "DataAPI", "DataStructures", "Future", "InlineStrings", "InvertedIndices", "IteratorInterfaceExtensions", "LinearAlgebra", "Markdown", "Missings", "PooledArrays", "PrecompileTools", "PrettyTables", "Printf", "Random", "Reexport", "SentinelArrays", "SortingAlgorithms", "Statistics", "TableTraits", "Tables", "Unicode"]
+git-tree-sha1 = "fb61b4812c49343d7ef0b533ba982c46021938a6"
+uuid = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
+version = "1.7.0"
+
 [[deps.DataStructures]]
 deps = ["Compat", "InteractiveUtils", "OrderedCollections"]
 git-tree-sha1 = "4e1fe97fdaed23e9dc21d4d664bea76b65fc50a0"
@@ -857,6 +863,19 @@ git-tree-sha1 = "debdd00ffef04665ccbb3e150747a77560e8fad1"
 uuid = "615f187c-cbe4-4ef1-ba3b-2fcf58d6d173"
 version = "0.1.1"
 
+[[deps.InlineStrings]]
+git-tree-sha1 = "8594fac023c5ce1ef78260f24d1ad18b4327b420"
+uuid = "842dd82b-1e85-43dc-bf29-5d0ee9dffc48"
+version = "1.4.4"
+
+    [deps.InlineStrings.extensions]
+    ArrowTypesExt = "ArrowTypes"
+    ParsersExt = "Parsers"
+
+    [deps.InlineStrings.weakdeps]
+    ArrowTypes = "31f734f8-188a-4ce0-8406-c8a06bd891cd"
+    Parsers = "69de0a69-1ddd-5017-9359-2bf0b02dc9f0"
+
 [[deps.IntelOpenMP_jll]]
 deps = ["Artifacts", "JLLWrappers", "LazyArtifacts", "Libdl"]
 git-tree-sha1 = "0f14a5456bdc6b9731a5682f439a672750a09e48"
@@ -889,6 +908,11 @@ weakdeps = ["Dates", "Test"]
     InverseFunctionsDatesExt = "Dates"
     InverseFunctionsTestExt = "Test"
 
+[[deps.InvertedIndices]]
+git-tree-sha1 = "6da3c4316095de0f5ee2ebd875df8721e7e0bdbe"
+uuid = "41ab1584-1d38-5bbf-9106-f11c6c58b48f"
+version = "1.3.1"
+
 [[deps.Ipopt]]
 deps = ["Ipopt_jll", "LinearAlgebra", "OpenBLAS32_jll", "PrecompileTools"]
 git-tree-sha1 = "4ad0d2dea51e5d49866b40a2d2521da6a1be7097"
@@ -1799,9 +1823,9 @@ version = "1.4.3"
 
 [[deps.Plots]]
 deps = ["Base64", "Contour", "Dates", "Downloads", "FFMPEG", "FixedPointNumbers", "GR", "JLFzf", "JSON", "LaTeXStrings", "Latexify", "LinearAlgebra", "Measures", "NaNMath", "Pkg", "PlotThemes", "PlotUtils", "PrecompileTools", "Printf", "REPL", "Random", "RecipesBase", "RecipesPipeline", "Reexport", "RelocatableFolders", "Requires", "Scratch", "Showoff", "SparseArrays", "Statistics", "StatsBase", "TOML", "UUIDs", "UnicodeFun", "UnitfulLatexify", "Unzip"]
-git-tree-sha1 = "809ba625a00c605f8d00cd2a9ae19ce34fc24d68"
+git-tree-sha1 = "28ea788b78009c695eb0d637587c81d26bdf0e36"
 uuid = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
-version = "1.40.13"
+version = "1.40.14"
 
     [deps.Plots.extensions]
     FileIOExt = "FileIO"
@@ -1829,6 +1853,12 @@ git-tree-sha1 = "645bed98cd47f72f67316fd42fc47dee771aefcd"
 uuid = "1d0040c9-8b98-4ee7-8388-3f51789ca0ad"
 version = "0.2.2"
 
+[[deps.PooledArrays]]
+deps = ["DataAPI", "Future"]
+git-tree-sha1 = "36d8b4b899628fb92c2749eb488d884a926614d3"
+uuid = "2dfb63ee-cc39-5dd5-95bd-886bf059d720"
+version = "1.4.3"
+
 [[deps.PreallocationTools]]
 deps = ["Adapt", "ArrayInterface", "ForwardDiff"]
 git-tree-sha1 = "6d98eace73d82e47f5b16c393de198836d9f790a"
@@ -2064,6 +2094,12 @@ git-tree-sha1 = "3bac05bc7e74a75fd9cba4295cde4045d9fe2386"
 uuid = "6c6a2e73-6563-6170-7368-637461726353"
 version = "1.2.1"
 
+[[deps.SentinelArrays]]
+deps = ["Dates", "Random"]
+git-tree-sha1 = "712fb0231ee6f9120e005ccd56297abbc053e7e0"
+uuid = "91c51154-3ec4-41a3-a24f-3f23e20d615c"
+version = "1.4.8"
+
 [[deps.Serialization]]
 uuid = "9e88b42a-f829-5b0c-bbe9-9e923198166b"
 version = "1.11.0"

diff --git a/docs/src/assets/Project.toml b/docs/src/assets/Project.toml
@@ -6,6 +6,7 @@ CTFlows = "1c39547c-7794-42f7-af83-d98194f657c2"
 CTModels = "34c4fa32-2049-4079-8329-de33c2a22e2d"
 CTParser = "32681960-a1b1-40db-9bff-a1ca817385d1"
 CommonSolve = "38540f10-b2f7-11e9-35d8-d573e4eb0ff2"
+DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
 DocumenterMermaid = "a078cd44-4d9c-4618-b545-3ab9d77f9177"
@@ -21,19 +22,22 @@ Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 Suppressor = "fd094767-a336-5f1f-9728-57cf17d0bbfb"
 
 [compat]
+ADNLPModels = "0.8"
 CTBase = "0.16"
 CTDirect = "0.14"
 CTFlows = "0.8"
 CTModels = "0.5"
 CTParser = "0.4"
 CommonSolve = "0.2"
 Documenter = "1.8"
+DocumenterInterLinks = "1"
 DocumenterMermaid = "0.2"
 JLD2 = "0.5"
 JSON3 = "1.14"
 LinearAlgebra = "1"
 MadNLP = "0.8"
 NLPModelsIpopt = "0.10"
+NLPModelsKnitro = "0.9"
 OrdinaryDiffEq = "6.93"
 Plots = "1.40"
 Suppressor = "0.2"

diff --git a/docs/src/manual-flow-ocp.md b/docs/src/manual-flow-ocp.md
@@ -468,6 +468,22 @@ From the maximizing condition, along a boundary arc, we have $p(t) = 0$. Differe
 \mu(x) = 2x.
 ```
 
+!!! note
+
+    Within OptimalControl.jl, the constraint must be given in the form:
+    ```julia
+    c([t, ]x, u[, v])
+    ```
+    the control law in feedback form must be given as:
+    ```julia
+    u([t, ]x, p[, v])
+    ```
+    and the dual variable:
+    ```julia
+    μ([t, ]x, p[, v])
+    ```
+    The time `t` must be provided when the problem is [non-autonomous](@ref manual-model-time-dependence) and the variable `v` must be given when the optimal control problem contains a [variable](@ref manual-abstract-variable) to optimise.
+
 The optimal control is a concatenation of 3 arcs: a negative bang arc followed by a boundary arc, followed by a positive bang arc. The initial covector is approximately $p(0)=-0.982237546583301$, the first switching time is $t_1 = 0.9$, and the exit time of the boundary is $t_2 = 1.6$. Let us check this by concatenating the three flows.
 
 ```@example main