Merge pull request #255 from control-toolbox/222-manipulation-of-the-nlp

Add Percival

Author: PierreMartinon

docs/Project.toml

@@ -14,6 +14,7 @@ MINPACK = "4854310b-de5a-5eb6-a2a5-c1dee2bd17f9"
 NLPModelsIpopt = "f4238b75-b362-5c4c-b852-0801c9a21d71"
 NonlinearSolve = "8913a72c-1f9b-4ce2-8d82-65094dcecaec"
 OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
+Percival = "01435c0c-c90d-11e9-3788-63660f8fbccc"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 Roots = "f2b01f46-fcfa-551c-844a-d8ac1e96c665"
 Suppressor = "fd094767-a336-5f1f-9728-57cf17d0bbfb"

docs/src/tutorial-nlp.md

@@ -11,30 +11,41 @@ When calling `solve(ocp)` three steps are performed internally:
 - then, this DOCP is solved (with the internal function `solve_docp`),
 - finally, a functional solution of the OCP is rebuilt from the solution of the discretized problem, with [`build_solution`](@ref).
 
-These steps can also be done separately, for instance if you want to use your own NLP solver. Let us load the modules
+These steps can also be done separately, for instance if you want to use your own NLP solver. 
+
+Let us load the packages.
 
 ```@example main
 using OptimalControl
 using NLPModelsIpopt
 using Plots
 ```
 
-and define a test problem
+## Definition of the optimal control problem
+
+We define a test problem
 
 ```@example main
 @def ocp begin
+
     t ∈ [ 0, 1 ], time
     x ∈ R², state
     u ∈ R, control
+
     x(0) == [ -1, 0 ]
     x(1) == [ 0, 0 ]
+
     ẋ(t) == [ x₂(t), u(t) ]
+
     ∫( 0.5u(t)^2 ) → min
+
 end
 nothing # hide
 ```
 
-First let us discretize the problem.
+## Discretization and NLP problem
+
+We discretize the problem.
 
 ```@example main
 docp, nlp = direct_transcription(ocp)
@@ -43,22 +54,27 @@ nothing # hide
 
 The DOCP contains information related to the transcription, including a copy of the original OCP, and the NLP is the resulting discretized problem, in our case an `ADNLPModel`.
 
-You could then use the solver of your choice to solve it.
-For an example we use the `ipopt` solver from [`NLPModelsIpopt.jl`](https://github.com/JuliaSmoothOptimizers/NLPModelsIpopt.jl) package to solve the NLP problem.
+We can now use the solver of our choice to solve it.
+
+## Resolution of the NLP problem
+
+For a first example we use the `ipopt` solver from [`NLPModelsIpopt.jl`](https://github.com/JuliaSmoothOptimizers/NLPModelsIpopt.jl) package to solve the NLP problem.
 
 ```@example main
 using NLPModelsIpopt
 nlp_sol = ipopt(nlp; print_level=4, mu_strategy="adaptive", tol=1e-8, sb="yes")
 nothing # hide
 ```
 
-Then we can rebuild and plot an OCP solution (note that the multipliers are optional, but the OCP costate will not be retrieved if the multipliers are not provided).
+Then we can rebuild and plot an optimal control problem solution (note that the multipliers are optional, but the OCP costate will not be retrieved if the multipliers are not provided).
 
 ```@example main
 sol = build_solution(docp, primal=nlp_sol.solution, dual=nlp_sol.multipliers)
 plot(sol)
 ```
 
+## Initial guess
+
 An initial guess, including warm start, can be passed to [`direct_transcription`](@ref) the same way as for `solve`.
 
 ```@example main
@@ -71,4 +87,14 @@ It can also be changed after the transcription is done, with  [`set_initial_gues
 ```@example main
 set_initial_guess(docp, nlp, sol)
 nothing # hide
+```
+
+For a second example, we use the [`Percival.jl`](https://jso.dev/Percival.jl) to solve the NLP problem
+with as initial guess the solution from the first resolution.
+
+```@example main
+using Percival
+
+output = percival(nlp)
+print(output)
 ```