Merge pull request #154 from control-toolbox/doc

Doc

Author: ocots

.gitignore

@@ -25,3 +25,6 @@ Manifest.toml
 
 # Notebooks checkpoints
 */.ipynb_checkpoints
+
+#
+docs/src/tmp/

docs/make.jl

@@ -20,16 +20,15 @@ makedocs(
         "Tutorials"     => ["tutorial-basic-example.md", 
                             "tutorial-basic-example-f.md", 
                             "tutorial-double-integrator.md",
-                            "tutorial-energy-and-distance-minimization.md",
+                            "tutorial-lqr-basic.md",
                             "tutorial-goddard.md",
                             #"tutorial-model.md",
                             #"tutorial-solvers.md",
-                            #"tutorial-init.md",
-                            #"tutorial-plot.md",
+                            "tutorial-init.md",
+                            "tutorial-plot.md",
                             #"tutorial-iss.md",
                             #"tutorial-flows.md",
                             #"tutorial-ct_repl.md",
-                            #"tutorial-problems.md"
                             ],
         "API"           => "api.md", 
         "JuliaCon2023"  => "juliacon2023.md", 

docs/src/tutorial-energy-and-distance-minimization.md

@@ -1,7 +1,75 @@
-# Initialisation
+# Initial guess
 
-```@meta
-CurrentModule =  OptimalControl
+We define the following optimal control problem.
+
+```@example main
+using OptimalControl
+
+t0 = 0
+tf = 10
+α  = 5
+
+@def ocp begin
+    t ∈ [ t0, tf ], time
+    v ∈ R, variable
+    x ∈ R², state
+    u ∈ R, control
+    x(t0) == [ -1, 0 ]
+    x(tf) - [ 0, v ] == [0, 0]
+    ẋ(t) == [ x₂(t), x₁(t) + α*x₁(t)^2 + u(t) ]
+    v^2 + ∫( 0.5u(t)^2 ) → min
+end
+nothing # hide
 ```
 
-See [`solve`](@ref) method.
+We first solve the problem without giving an initial guess.
+
+```@example main
+# solve the optimal control problem without initial guess
+sol = solve(ocp, display=false)
+
+# print the number of iterations 
+println("Number of iterations: ", sol.iterations)
+nothing # hide
+```
+
+Let us plot the solution of the optimal control problem.
+
+```@example main
+plot(sol, size=(600, 450))
+```
+
+To reduce the number of iterations and improve the convergence, we can give an initial guess to the solver. We define the following initial guess.
+
+```@example main
+# constant initial guess
+initial_guess = (state=[-0.2, 0.1], control=-0.2, variable=0.05)
+
+# solve the optimal control problem with initial guess
+sol = solve(ocp, display=false, init=initial_guess)
+
+# print the number of iterations
+println("Number of iterations: ", sol.iterations)
+nothing # hide
+```
+
+We can also provide functions of time as initial guess for the state and the control.
+
+```@example main
+# initial guess as functions of time
+x(t) = [ -0.2 * t, 0.1 * t ]
+u(t) = -0.2 * t
+initial_guess = (state=x, control=u, variable=0.05)
+
+# solve the optimal control problem with initial guess
+sol = solve(ocp, display=false, init=initial_guess)
+
+# print the number of iterations
+println("Number of iterations: ", sol.iterations)
+nothing # hide
+```
+
+!!! warning
+
+    For the moment we can not provide an initial guess for the costate.
+    Besides, there is neither cold nor warm start implemented yet. That is, we can not use the solution of a previous optimal control problem as initial guess.

docs/src/tutorial-init.md

@@ -0,0 +1,145 @@
+# LQR example
+
+The energy and distance minimisation Linear Quadratic Problem (LQR) problem consists in minimising
+
+```math
+    \frac{1}{2} \int_{0}^{t_f} \left( x_1^2(t) + x_2^2(t) + u^2(t) \right) \, \mathrm{d}t 
+```
+
+subject to the constraints
+
+```math
+    \dot x_1(t) = x_2(t), \quad \dot x_2(t) = -x_1(t) + u(t), \quad u(t) \in \R
+```
+
+and the initial condition
+
+```math
+    x(0) = (0,1).
+```
+
+We define $A$ and $B$ as
+
+```math
+    A = \begin{pmatrix} 0 & 1 \\ -1 & 0 \\ \end{pmatrix}, \quad
+    B = \begin{pmatrix} 0 \\ 1 \\ \end{pmatrix}
+```
+
+and we aim to solve this optimal control problem for different values of $t_f$.
+First, we need to import the `OptimalControl.jl` package.
+
+```@example main
+using OptimalControl
+```
+
+Then, we can define the problem parameterized by the final time `tf`.
+
+```@example main
+x0 = [ 0
+       1 ]
+A  = [ 0 1
+      -1 0 ]
+B  = [ 0
+       1 ]
+
+function LQRProblem(tf)
+
+    @def ocp begin
+        t ∈ [ 0, tf ], time
+        x ∈ R², state
+        u ∈ R, control
+        x(0) == x0, initial_con
+        ẋ(t) == A * x(t) + B * u(t)
+        ∫( 0.5(x₁(t)^2 + x₂(t)^2 + u(t)^2) ) → min
+    end
+
+    return ocp
+end;
+nothing # hide
+```
+
+We solve the problem for $t_f \in \{3, 5, 30\}$.
+
+```@example main
+solutions = []
+tfspan    = [3, 5, 30]
+
+for tf ∈ tfspan
+    sol = solve(LQRProblem(tf), display=false)
+    push!(solutions, sol)
+end
+nothing # hide
+```
+
+We choose to plot the solutions considering a normalized time $s=(t-t_0)/(t_f-t_0)$.
+We thus introduce the function `rescale` that rescales the time and redefine the state, costate and control variables.
+
+!!! tip
+
+    Instead of defining the function `rescale`, you can consider $t_f$ as a parameter and define the following
+    optimal control problem:
+    
+    ```julia
+    @def ocp begin
+        s ∈ [ 0, 1 ], time
+        x ∈ R², state
+        u ∈ R, control
+        x(0) == x0, initial_con
+        ẋ(s) == tf * ( A * x(s) + B * u(s) )
+        ∫( 0.5(x₁(s)^2 + x₂(s)^2 + u(s)^2) ) → min
+    end
+    ```
+
+```@example main
+function rescale(sol)
+
+    # integration times
+    times = sol.times
+
+    # s is the rescaled time between 0 and 1
+    t(s)  = times[1] + s * (times[end] - times[1])
+
+    # rescaled times
+    sol.times = (times .- times[1]) ./ (times[end] .- times[1])
+
+    # redefinition of the state, control and costate
+    x = sol.state
+    u = sol.control
+    p = sol.costate
+
+    sol.state   = x∘t   # s → x(t(s))
+    sol.control = u∘t   # s → u(t(s))
+    sol.costate = p∘t   # s → p(t(s))
+
+    return sol
+end
+nothing # hide
+```
+
+!!! note
+
+    The `∘` operator is the composition operator. Hence, `x∘t` is the function `s -> x(t(s))`.
+
+
+Finally we choose to plot only the state and control variables.
+
+```@example main
+using Plots.PlotMeasures # for leftmargin, bottommargin
+
+# we construct the plots from the solutions with default options
+plt = plot(rescale(solutions[1]))
+for sol in solutions[2:end]
+    plot!(plt, rescale(sol))
+end
+
+# we plot only the state and control variables and we add the legend
+px1 = plot(plt[1], legend=false, xlabel="s", ylabel="x₁")
+px2 = plot(plt[2], label=reshape(["tf = $tf" for tf ∈ tfspan], 
+    (1, length(tfspan))), xlabel="s", ylabel="x₂")
+pu  = plot(plt[5], legend=false, xlabel="s", ylabel="u")
+plot(px1, px2, pu, layout=(1, 3), size=(800, 300), leftmargin=5mm, bottommargin=5mm)
+```
+
+!!! note
+
+    We can observe that $x(t_f)$ converges to the origin as $t_f$ increases.