diff --git a/docs/make.jl b/docs/make.jl index 82cf9043..32692eda 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -27,8 +27,8 @@ makedocs( pages = [ "Introduction" => "index.md", "Basic examples" => [ - "Energy minimisation" => "tutorial-basic-example.md", - "Time mininimisation" => "tutorial-double-integrator.md", + "Energy minimisation" => "tutorial-double-integrator-energy.md", + "Time mininimisation" => "tutorial-double-integrator-time.md", ], "Manual" => [ "Abstract syntax" => "tutorial-abstract.md", diff --git a/docs/src/api-ctbase.md b/docs/src/api-ctbase.md index 9fce077d..713b8cf3 100644 --- a/docs/src/api-ctbase.md +++ b/docs/src/api-ctbase.md @@ -18,15 +18,16 @@ style B fill:#FBF275 You may find in this package: -- [Types](@ref api-ctbase-types): the common types and associated methods if any. - [Description](@ref api-ctbase-description): tools to manipulate tuples. -- [Differential geometry](@ref api-ctbase-diffgeometry): tools to compute [Lie brackets](https://en.wikipedia.org/w/index.php?title=Lie_bracket_of_vector_fields&oldid=1163591634), [Poisson brackets](https://en.wikipedia.org/w/index.php?title=Poisson_manifold&oldid=1163991099#Formal_definition)... +- [Differential geometry](@ref api-ctbase-differential-geometry): tools to compute [Lie brackets](https://en.wikipedia.org/w/index.php?title=Lie_bracket_of_vector_fields&oldid=1163591634), [Poisson brackets](https://en.wikipedia.org/w/index.php?title=Poisson_manifold&oldid=1163991099#Formal_definition)... - [Exceptions](@ref api-ctbase-exceptions). +- [Initial guess](@ref api-ctbase-init): tools to define an initial guess. - [Model](@ref api-ctbase-model): tools to modelise an optimal control problem in a functional manner. - [Parser](@ref api-ctbase-parser): tools to modelise an optimal control problem in an abstract manner. -- [Plot](@ref api-ctbase-plot): the `plot` function extended from Plots.jl and utils. - [Print](@ref api-ctbase-print): check how an optimal control problem is displayed. - [Repl](@ref api-ctbase-repl): control-toolbox repl. +- [Solution](@ref api-ctbase-solution): optimal control solution. +- [Types](@ref api-ctbase-types): the common types and associated methods if any. - [Utils](@ref api-ctbase-utils): auxiliary methods. Here is the list of imported packages and exported functions. diff --git a/docs/src/api-ctbase/description.md b/docs/src/api-ctbase/description.md index 1415b744..bed5ffd4 100644 --- a/docs/src/api-ctbase/description.md +++ b/docs/src/api-ctbase/description.md @@ -9,14 +9,14 @@ CollapsedDocStrings = true ```@index Pages = ["description.md"] Modules = [CTBase] -Order = [:module, :constant, :function, :macro] +Order = [:type, :module, :constant, :function, :macro] ``` ## Documentation ```@autodocs Modules = [CTBase] -Order = [:module, :constant, :function, :macro] +Order = [:type, :module, :constant, :function, :macro] Pages = ["description.jl"] Private = false ``` diff --git a/docs/src/api-ctbase/diffgeometry.md b/docs/src/api-ctbase/diffgeometry.md index 466855d3..d03b0ad1 100644 --- a/docs/src/api-ctbase/diffgeometry.md +++ b/docs/src/api-ctbase/diffgeometry.md @@ -1,4 +1,4 @@ -# [Differential geometry](@id api-ctbase-diffegeometry) +# [Differential geometry](@id api-ctbase-differential-geometry) ```@meta CollapsedDocStrings = true @@ -9,14 +9,14 @@ CollapsedDocStrings = true ```@index Pages = ["diffgeometry.md"] Modules = [CTBase] -Order = [:module, :constant, :function, :macro] +Order = [:type, :module, :constant, :function, :macro] ``` ## Documentation ```@autodocs Modules = [CTBase] -Order = [:module, :constant, :function, :macro] +Order = [:type, :module, :constant, :function, :macro] Pages = ["differential_geometry.jl"] Private = false ``` diff --git a/docs/src/api-ctbase/exceptions.md b/docs/src/api-ctbase/exceptions.md index d7cfacac..19d3f464 100644 --- a/docs/src/api-ctbase/exceptions.md +++ b/docs/src/api-ctbase/exceptions.md @@ -9,14 +9,14 @@ CollapsedDocStrings = true ```@index Pages = ["exceptions.md"] Modules = [CTBase] -Order = [:module, :constant, :function, :macro] +Order = [:type, :module, :constant, :function, :macro] ``` ## Documentation ```@autodocs Modules = [CTBase] -Order = [:module, :constant, :function, :macro] +Order = [:type, :module, :constant, :function, :macro] Pages = ["exception.jl"] Private = false ``` diff --git a/docs/src/api-ctbase/init.md b/docs/src/api-ctbase/init.md new file mode 100644 index 00000000..19d6c056 --- /dev/null +++ b/docs/src/api-ctbase/init.md @@ -0,0 +1,22 @@ +# [Initial guess](@id api-ctbase-init) + +```@meta +CollapsedDocStrings = true +``` + +## Index + +```@index +Pages = ["init.md"] +Modules = [CTBase] +Order = [:type, :module, :constant, :function, :macro] +``` + +## Documentation + +```@autodocs +Modules = [CTBase] +Order = [:type, :module, :constant, :function, :macro] +Pages = ["init.jl"] +Private = false +``` diff --git a/docs/src/api-ctbase/model.md b/docs/src/api-ctbase/model.md index ccc662a7..a0c05df0 100644 --- a/docs/src/api-ctbase/model.md +++ b/docs/src/api-ctbase/model.md @@ -4,19 +4,33 @@ CollapsedDocStrings = true ``` -## Index - -```@index +```@contents Pages = ["model.md"] +``` + +## Optimal control model type + +```@autodocs Modules = [CTBase] -Order = [:module, :constant, :function, :macro] +Order = [:type, :module, :constant, :function, :macro] +Pages = ["optimal_control_model-type.jl"] +Private = false ``` -## Documentation +## Getters ```@autodocs Modules = [CTBase] -Order = [:module, :constant, :function, :macro] -Pages = ["model.jl"] +Order = [:type, :module, :constant, :function, :macro] +Pages = ["optimal_control_model-getters.jl"] Private = false ``` + +## Constructors and setters + +```@autodocs +Modules = [CTBase] +Order = [:type, :module, :constant, :function, :macro] +Pages = ["optimal_control_model-setters.jl"] +Private = false +``` \ No newline at end of file diff --git a/docs/src/api-ctbase/plot.md b/docs/src/api-ctbase/plot.md index 7a0f43f6..589b50db 100644 --- a/docs/src/api-ctbase/plot.md +++ b/docs/src/api-ctbase/plot.md @@ -6,7 +6,7 @@ CollapsedDocStrings = true ```@autodocs Modules = [CTBase] -Order = [:module, :constant, :function, :macro] +Order = [:type, :module, :constant, :function, :macro] Pages = ["plot.jl"] Private = false ``` \ No newline at end of file diff --git a/docs/src/api-ctbase/print.md b/docs/src/api-ctbase/print.md index f2467b81..95529997 100644 --- a/docs/src/api-ctbase/print.md +++ b/docs/src/api-ctbase/print.md @@ -6,7 +6,7 @@ CollapsedDocStrings = true ```@autodocs Modules = [CTBase] -Order = [:module, :constant, :function, :macro] +Order = [:type, :module, :constant, :function, :macro] Pages = ["print.jl"] Private = false ``` @@ -70,7 +70,7 @@ You can also define the optimal control problem in an abstract form: ```@example main2 using OptimalControl -@def ocp begin +ocp = @def begin t ∈ [ 0, 1 ], time x ∈ R^2, state u ∈ R, control diff --git a/docs/src/api-ctbase/repl.md b/docs/src/api-ctbase/repl.md index 2185e0e1..1b7ea343 100644 --- a/docs/src/api-ctbase/repl.md +++ b/docs/src/api-ctbase/repl.md @@ -9,14 +9,14 @@ CollapsedDocStrings = true ```@index Pages = ["repl.md"] Modules = [CTBase] -Order = [:module, :constant, :function, :macro] +Order = [:type, :module, :constant, :function, :macro] ``` ## Documentation ```@autodocs Modules = [CTBase] -Order = [:module, :constant, :function, :macro] +Order = [:type, :module, :constant, :function, :macro] Pages = ["repl.jl"] Private = false ``` diff --git a/docs/src/api-ctbase/solution.md b/docs/src/api-ctbase/solution.md new file mode 100644 index 00000000..4fc3ecd9 --- /dev/null +++ b/docs/src/api-ctbase/solution.md @@ -0,0 +1,36 @@ +# [Solution](@id api-ctbase-solution) + +```@meta +CollapsedDocStrings = true +``` + +```@contents +Pages = ["solution.md"] +``` + +## Optimal control solution type + +```@autodocs +Modules = [CTBase] +Order = [:type, :module, :constant, :function, :macro] +Pages = ["optimal_control_solution-type.jl"] +Private = false +``` + +## Getters + +```@autodocs +Modules = [CTBase] +Order = [:type, :module, :constant, :function, :macro] +Pages = ["optimal_control_solution-getters.jl"] +Private = false +``` + +## Constructors and setters + +```@autodocs +Modules = [CTBase] +Order = [:type, :module, :constant, :function, :macro] +Pages = ["optimal_control_solution-setters.jl"] +Private = false +``` diff --git a/docs/src/api-ctbase/types.md b/docs/src/api-ctbase/types.md index 27339282..b77ed44b 100644 --- a/docs/src/api-ctbase/types.md +++ b/docs/src/api-ctbase/types.md @@ -9,13 +9,14 @@ CollapsedDocStrings = true ```@index Pages = ["types.md"] Modules = [CTBase] -Order = [:type] +Order = [:type, :module, :constant, :function, :macro] ``` ## Documentation ```@autodocs Modules = [CTBase] -Order = [:type] +Order = [:type, :module, :constant, :function, :macro] +Pages = ["types.jl", "functions.jl"] Private = false ``` diff --git a/docs/src/api-ctbase/utils.md b/docs/src/api-ctbase/utils.md index 3fea439f..2e9da888 100644 --- a/docs/src/api-ctbase/utils.md +++ b/docs/src/api-ctbase/utils.md @@ -9,14 +9,14 @@ CollapsedDocStrings = true ```@index Pages = ["utils.md"] Modules = [CTBase] -Order = [:module, :constant, :function, :macro] +Order = [:type, :module, :constant, :function, :macro] ``` ## Documentation ```@autodocs Modules = [CTBase] -Order = [:module, :constant, :function, :macro] +Order = [:type, :module, :constant, :function, :macro] Pages = ["utils.jl"] Private = false ``` diff --git a/docs/src/dev-ctbase.md b/docs/src/dev-ctbase.md index b8046c0d..070ad96b 100644 --- a/docs/src/dev-ctbase.md +++ b/docs/src/dev-ctbase.md @@ -9,13 +9,13 @@ CollapsedDocStrings = true ```@index Pages = ["dev-ctbase.md"] Modules = [CTBase] -Order = [:module, :constant, :type, :function, :macro] +Order = [:type, :module, :constant, :type, :function, :macro] ``` ## Documentation ```@autodocs Modules = [CTBase] -Order = [:module, :constant, :type, :function, :macro] +Order = [:type, :module, :constant, :type, :function, :macro] Public = false ``` diff --git a/docs/src/dev-ctdirect.md b/docs/src/dev-ctdirect.md index aebd5bc2..0f51a357 100644 --- a/docs/src/dev-ctdirect.md +++ b/docs/src/dev-ctdirect.md @@ -9,13 +9,13 @@ CollapsedDocStrings = true ```@index Pages = ["dev-ctdirect.md"] Modules = [CTDirect] -Order = [:module, :constant, :type, :function, :macro] +Order = [:type, :module, :constant, :type, :function, :macro] ``` ## Documentation ```@autodocs Modules = [CTDirect] -Order = [:module, :constant, :type, :function, :macro] +Order = [:type, :module, :constant, :type, :function, :macro] Public = false ``` diff --git a/docs/src/dev-ctflows.md b/docs/src/dev-ctflows.md index 04853acc..10281efd 100644 --- a/docs/src/dev-ctflows.md +++ b/docs/src/dev-ctflows.md @@ -9,13 +9,13 @@ CollapsedDocStrings = true ```@index Pages = ["dev-ctflows.md"] Modules = [CTFlows] -Order = [:module, :constant, :type, :function, :macro] +Order = [:type, :module, :constant, :type, :function, :macro] ``` ## Documentation ```@autodocs Modules = [CTFlows] -Order = [:module, :constant, :type, :function, :macro] +Order = [:type, :module, :constant, :type, :function, :macro] Public = false ``` diff --git a/docs/src/dev-optimalcontrol.md b/docs/src/dev-optimalcontrol.md index 8f28e89b..df4e875c 100644 --- a/docs/src/dev-optimalcontrol.md +++ b/docs/src/dev-optimalcontrol.md @@ -9,13 +9,13 @@ CollapsedDocStrings = true ```@index Pages = ["dev-optimalcontrol.md"] Modules = [OptimalControl] -Order = [:module, :constant, :type, :function, :macro] +Order = [:type, :module, :constant, :type, :function, :macro] ``` ## Documentation ```@autodocs Modules = [OptimalControl] -Order = [:module, :constant, :type, :function, :macro] +Order = [:type, :module, :constant, :type, :function, :macro] Public = false ``` diff --git a/docs/src/tutorial-basic-example.md b/docs/src/tutorial-double-integrator-energy.md similarity index 90% rename from docs/src/tutorial-basic-example.md rename to docs/src/tutorial-double-integrator-energy.md index 20655e76..34d2be61 100644 --- a/docs/src/tutorial-basic-example.md +++ b/docs/src/tutorial-double-integrator-energy.md @@ -51,7 +51,7 @@ nothing # hide !!! note "Nota bene" - For a comprehensive introduction to the syntax used above to describe the optimal control problem, check [this tutorial](@ref abstract). In particular, there are non-unicode alternatives for derivatives, integrals, *etc.* There is also a non-standard but more classical functional syntax, check [this tutorial](@ref functional). + For a comprehensive introduction to the syntax used above to describe the optimal control problem, check [this abstract syntax tutorial](@ref abstract). In particular, there are non-unicode alternatives for derivatives, integrals, *etc.* There is also a non-standard but more classical functional syntax, check [this functional syntax tutorial](@ref functional). ## [Solve and plot](@id basic-solve-plot) diff --git a/docs/src/tutorial-double-integrator.md b/docs/src/tutorial-double-integrator-time.md similarity index 86% rename from docs/src/tutorial-double-integrator.md rename to docs/src/tutorial-double-integrator-time.md index 184bc680..fb179ab2 100644 --- a/docs/src/tutorial-double-integrator.md +++ b/docs/src/tutorial-double-integrator-time.md @@ -70,7 +70,7 @@ nothing # hide !!! note "Nota bene" - For a comprehensive introduction to the syntax used above to describe the optimal control problem, check [this tutorial](@ref abstract). In particular, there are non-unicode alternatives for derivatives, integrals, *etc.* There is also a non-standard but more classical functional syntax, check [this tutorial](@ref functional). + For a comprehensive introduction to the syntax used above to describe the optimal control problem, check [this abstract syntax tutorial](@ref abstract). In particular, there are non-unicode alternatives for derivatives, integrals, *etc.* There is also a non-standard but more classical functional syntax, check [this functional syntax tutorial](@ref functional). ## Solve and plot diff --git a/docs/src/tutorial-flow.md b/docs/src/tutorial-flow.md index 71f1f6d0..235b4c3c 100644 --- a/docs/src/tutorial-flow.md +++ b/docs/src/tutorial-flow.md @@ -142,6 +142,10 @@ You can notice from the graph of `v` that the integrator has made very few steps time_grid(sol) ``` +!!! Note "Time grid" + + The function [`time_grid`](@ref) returns the discretized time grid returned by the solver. In this case, the solution has been computed by numerical integration with an adaptive step-length Runge-Kutta scheme. + To have a better visualisation (the accuracy won't change), you can provide a fine grid. ```@example main diff --git a/docs/src/tutorial-goddard.md b/docs/src/tutorial-goddard.md index 8445a407..fbb7a113 100644 --- a/docs/src/tutorial-goddard.md +++ b/docs/src/tutorial-goddard.md @@ -123,6 +123,10 @@ bang arc with maximal control, followed by a singular arc, then by a boundary ar arc is with zero control. Note that the switching function vanishes along the singular and boundary arcs. +!!! tip "Interactions with an optimal control solution" + + Please check [`state`](@ref), [`costate`](@ref), [`control`](@ref) and [`variable`](@ref) to get data from the solution. The functions `state`, `costate` and `control` return functions of time and `variable` returns a vector. The function [`time_grid`](@ref) returns the discretized time grid returned by the solver. + ```@example main t = time_grid(direct_sol) x = state(direct_sol) @@ -371,7 +375,7 @@ Let us define the problem to solve. # auxiliary function with aggregated inputs nle! = ( s, ξ) -> shoot!(s, ξ[1:3], ξ[4], ξ[5], ξ[6], ξ[7]) - # Jacobian of the (auxiliary) shooting function +# Jacobian of the (auxiliary) shooting function jnle! = (js, ξ) -> jacobian!(nle!, similar(ξ), js, backend, ξ) nothing # hide ``` diff --git a/docs/src/tutorial-initial-guess.md b/docs/src/tutorial-initial-guess.md index 7370c17b..bc6b93e3 100644 --- a/docs/src/tutorial-initial-guess.md +++ b/docs/src/tutorial-initial-guess.md @@ -36,7 +36,9 @@ ocp = @def begin end nothing # hide ``` + ## Default initial guess + We first solve the problem without giving an initial guess. This will default to initialize all variables to 0.1. @@ -68,7 +70,12 @@ To reduce the number of iterations and improve the convergence, we can give an i This initial guess can be built from constant values, interpolated vectors, functions, or existing solutions. Except when initializing from a solution, the arguments are to be passed as a named tuple ```init=(state=..., control=..., variable=...)``` whose fields are optional. Missing fields will revert to default initialization (ie constant 0.1). +!!! tip "Interactions with an optimal control solution" + + To get the number of iterations of the solver, check the [`iterations`](@ref) function. + ## Constant initial guess + We first illustrate the constant initial guess, using vectors or scalars according to the dimension. ```@example main @@ -174,6 +181,10 @@ println("Number of iterations: ", iterations(sol)) nothing # hide ``` +!!! tip "Interactions with an optimal control solution" + + Please check [`state`](@ref), [`costate`](@ref), [`control`](@ref) and [`variable`](@ref) to get data from the solution. The functions `state`, `costate` and `control` return functions of time and `variable` returns a vector. + ## Costate / multipliers For the moment we can not provide an initial guess for the costate / multipliers. diff --git a/docs/src/tutorial-plot.md b/docs/src/tutorial-plot.md index 3dac0acc..05bca27a 100644 --- a/docs/src/tutorial-plot.md +++ b/docs/src/tutorial-plot.md @@ -75,6 +75,10 @@ reconstruct the solution. See the [Indirect Simple Shooting](@ref iss) tutorial In our example, you must provide the maximising control $(x, p) \mapsto p_2$ together with the optimal control problem. +!!! tip "Interactions with an optimal control solution" + + Please check [`state`](@ref), [`costate`](@ref), [`control`](@ref) and [`variable`](@ref) to get data from the solution. The functions `state`, `costate` and `control` return functions of time and `variable` returns a vector. + ```@example main t0 = 0 tf = 1 @@ -150,6 +154,10 @@ plot(sol; control=:norm, size=(800, 300), layout=:group) You can of course create your own plots by getting the `state`, `costate` and `control` from the optimal control solution. For instance, let us plot the norm of the control for the orbital transfer problem. +!!! tip "Interactions with an optimal control solution" + + Additionally to [`state`](@ref), [`costate`](@ref), [`control`](@ref) and [`variable`](@ref), the function [`time_grid`](@ref) returns the discretized time grid returned by the solver. + ```@example main using LinearAlgebra t = time_grid(sol) @@ -163,8 +171,6 @@ plot(t, norm∘u; label="‖u‖") - The `norm` function is from `LinearAlgebra.jl`. - The `∘` operator is the composition operator. Hence, `norm∘u` is the function `t -> norm(u(t))`. - - The `state(sol)`, `costate(sol)` and `control(sol)` are functions that return the state, costate and control trajectories at a given time. - ## Normalized time diff --git a/docs/src/tutorial-repl.md b/docs/src/tutorial-repl.md index bb2b0d46..2bbaf5d1 100644 --- a/docs/src/tutorial-repl.md +++ b/docs/src/tutorial-repl.md @@ -15,6 +15,10 @@ To enter into the control-toolbox, press `>` key. and plot the solution in the Julia REPL. Use the command `NAME` to rename the optimal control problem: `ct> NAME=ocp`. +!!! note "Nota bene" + + In the following gif, the plot is not displayed since only the terminal is recorded. + ```@raw html