foo

ocots · ocots · commit 6e2d6fdc4cc8 · 2023-07-25T01:57:37.000+02:00
diff --git a/docs/make.jl b/docs/make.jl
@@ -15,8 +15,18 @@ makedocs(
     format = Documenter.HTML(prettyurls = false),
     pages = [
         "Introduction"  => "index.md",
-        "Tutorials"     => ["basic-example.md", "goddard.md"],
-        "API"           => ["api.md", "api-ctbase.md", "api-ctflows.md", "api-ctdirect.md"], 
+        "Tutorials"     => ["tutorial-basic-example.md", 
+                            "tutorial-goddard.md",
+                            "tutorial-model.md",
+                            "tutorial-solvers.md",
+                            "tutorial-init.md",
+                            "tutorial-plot.md",
+                            "tutorial-iss.md",
+                            "tutorial-ctrepl.md"],
+        "API"           => ["api.md", 
+                            "api-ctbase.md", 
+                            "api-ctflows.md", 
+                            "api-ctdirect.md"], 
     ]
 )
 
diff --git a/docs/src/api.md b/docs/src/api.md
@@ -9,6 +9,13 @@ Order = [:module, :constant, :type, :function, :macro]
 Private = false
 ```
 
+## Available methods
+
+```@example
+using OptimalControl
+Methods()
+```
+
 ## Documentation
 
 ```@autodocs
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -8,7 +8,7 @@ The `OptimalControl.jl` package aims to provide tools to solve optimal control p
 It is part of the [control-toolbox ecosystem](https://github.com/control-toolbox):
 
 ```@raw html
-<img src="./assets/diagram.png" style="display: block; margin: 0 auto 20px auto;" width="400px">
+<img src="./assets/diagram.png" style="display: block; margin: 0 auto 20px auto;" width="320px">
 ```
 
 !!! note "Install and documentation"
diff --git a/docs/src/tutorial-basic-example.md b/docs/src/tutorial-basic-example.md
diff --git a/docs/src/tutorial-ctrepl.md b/docs/src/tutorial-ctrepl.md
@@ -0,0 +1,3 @@
+# ct repl
+
+See [`ctrepl`](@ref) method.
diff --git a/docs/src/tutorial-goddard.md b/docs/src/tutorial-goddard.md
diff --git a/docs/src/tutorial-init.md b/docs/src/tutorial-init.md
@@ -0,0 +1,7 @@
+# Initialisation
+
+```@meta
+CurrentModule =  OptimalControl
+```
+
+See [`solve`](@ref) method.
diff --git a/docs/src/tutorial-iss.md b/docs/src/tutorial-iss.md
@@ -0,0 +1,3 @@
+# Indirect simple shooting
+
+In construction.
diff --git a/docs/src/tutorial-model.md b/docs/src/tutorial-model.md
@@ -0,0 +1,3 @@
+# Modelisation
+
+See [`OptimalControlModel`](@ref) type.
diff --git a/docs/src/tutorial-plot.md b/docs/src/tutorial-plot.md
@@ -0,0 +1,3 @@
+# Plot solution
+
+See [`plot`](@ref) method.
diff --git a/docs/src/tutorial-solvers.md b/docs/src/tutorial-solvers.md
@@ -0,0 +1,7 @@
+# Solvers and options
+
+```@meta
+CurrentModule =  OptimalControl
+```
+
+See [`solve`](@ref) method.
diff --git a/src/OptimalControl.jl b/src/OptimalControl.jl
@@ -21,13 +21,12 @@ using CTFlows
 
 # declarations
 const __display = CTBase.__display
-const ctrepl = CTBase.__init_repl
 
-# resources
 include("solve.jl")
 
 # export functions only for user
 export solve
+export Methods
 
 # export from other modules
 
diff --git a/src/solve.jl b/src/solve.jl
@@ -2,10 +2,19 @@
 # Resolution
 
 # by order of preference
-methods = ()
+algorithmes = ()
 
 # descent methods
-methods = add(methods, (:direct, :adnlp, :ipopt))
+algorithmes = add(algorithmes, (:direct, :adnlp, :ipopt))
+
+"""
+$(TYPEDSIGNATURES)
+
+Return the list of available methods to solve the optimal control problem.
+"""
+function Methods()::Tuple{Tuple{Vararg{Symbol}}}
+    return algorithmes
+end
 
 """
 $(TYPEDSIGNATURES)
@@ -16,7 +25,7 @@ Solve the the optimal control problem `ocp` by the method given by the (optional
 
 You can pass a partial description.
 If you give a partial description, then, if several complete descriptions contains the partial one, 
-then, the method with the highest priority is chosen. The higher in the list `OptimalControl.methods`, 
+then, the method with the highest priority is chosen. The higher in the list, 
 the higher is the priority.
 
 Keyword arguments:
@@ -28,12 +37,14 @@ Keyword arguments:
 
     There is only one available method for the moment: a direct method which transforms
     the optimal control problem into a nonlinear programming problem (NLP) solved
-    by `IPOPT`, thanks to the package `ADNLProblems`. The direct method comes from
-    the `CTDirect` package.
+    by [`Ipopt`](https://coin-or.github.io/Ipopt/), thanks to the package 
+    [`ADNLPModels`](https://github.com/JuliaSmoothOptimizers/ADNLPModels.jl).
+    The direct method comes from the 
+    [`CTDirect`](https://github.com/control-toolbox/CTDirect.jl) package.
 
 !!! tip
 
-    - To see the list of available methods, simply print `OptimalControl.methods`.
+    - To see the list of available methods, simply call `Methods()`.
     - You can pass any other option by a pair `keyword=value` according to the chosen method.
 
 # Examples
@@ -42,6 +53,14 @@ Keyword arguments:
 julia> sol = solve(ocp)
 julia> sol = solve(ocp, :direct)
 julia> sol = solve(ocp, :direct, :ipopt)
+julia> sol = solve(ocp, :direct, :ipopt, display=false)
+julia> sol = solve(ocp, :direct, :ipopt, display=false, init=sol)
+julia> sol = solve(ocp, init=(state=[-0.5, 0.2],))
+julia> sol = solve(ocp, init=(state=[-0.5, 0.2], control=0.5))
+julia> sol = solve(ocp, init=(state=[-0.5, 0.2], control=0.5, variable=[1, 2]))
+julia> sol = solve(ocp, init=(state=[-0.5, 0.2], control=t->6-12*t))
+julia> sol = solve(ocp, init=(state=t->[-1+t, t*(t-1)], control=0.5))
+julia> sol = solve(ocp, init=(state=t->[-1+t, t*(t-1)], control=t->6-12*t))
 ```
 
 """
@@ -51,7 +70,7 @@ function solve(ocp::OptimalControlModel, description::Symbol...;
     kwargs...)
 
     #
-    method = getFullDescription(description, methods)
+    method = getFullDescription(description, Methods())
 
     # todo: OptimalControlInit must be in CTBase, it is for the moment in CTDirect
     
@@ -60,11 +79,11 @@ function solve(ocp::OptimalControlModel, description::Symbol...;
     elseif init isa CTBase.OptimalControlSolution
         init = OptimalControlInit(init)
     else
-        init = OptimalControlInit(x_init=init[rg(1, ocp.state_dimension)], 
-                            u_init=init[rg(ocp.state_dimension+1, ocp.state_dimension+ocp.control_dimension)],
-                            v_init=init[rg(ocp.state_dimension+ocp.control_dimension+1, lastindex(init))])
+        x_init = :state    ∈ keys(init) ? init[:state]    : nothing
+        u_init = :control  ∈ keys(init) ? init[:control]  : nothing
+        v_init = :variable ∈ keys(init) ? init[:variable] : nothing
+        init = OptimalControlInit(x_init=x_init, u_init=u_init, v_init=v_init)
     end
-    
 
     # print chosen method
     display ? println("Method = ", method) : nothing
diff --git a/test/runtests.jl b/test/runtests.jl
@@ -6,12 +6,15 @@ using CTProblems
 
 #
 @testset verbose = true showtiming = true "Optimal control tests" begin
-    for name in (
-        "goddard_direct",
-        "goddard_indirect",
+    for name ∈ (
+        :goddard_direct,
+        :goddard_indirect,
+        :init,
         )
-        @testset "$name" begin
-            include("test_$name.jl")
+        @testset "$(name)" begin
+            test_name = Symbol(:test_, name)
+            include("$(test_name).jl")
+            @eval $test_name()
         end
     end
 end
diff --git a/test/test_goddard_direct.jl b/test/test_goddard_direct.jl
@@ -1,13 +1,16 @@
+function test_goddard_direct()
+
 # goddard with state constraint - maximize altitude
 prob = Problem(:goddard, :classical, :altitude, :x_dim_3, :u_dim_1, :mayer, :x_cons, :u_cons, :singular_arc)
 ocp = prob.model
 
 # initial guess (constant state and control functions)
-#init = ([1.01, 0.05, 0.8], 0.1, 0.2)
-init = [1.01, 0.05, 0.8, 0.1, 0.2]
+init = (state=[1.01, 0.05, 0.8], control=0.1, variable=0.2)
 
 # solve
 sol = solve(ocp, grid_size=10, print_level=5, init=init)
 
 # test
 @test sol.objective ≈ prob.solution.objective atol=5e-3
+
+end
diff --git a/test/test_goddard_indirect.jl b/test/test_goddard_indirect.jl
@@ -1,3 +1,5 @@
+function test_goddard_indirect()
+
 prob = Problem(:goddard, :classical, :altitude, :x_dim_3, :u_dim_1, :mayer, :x_cons, :u_cons, :singular_arc)
 ocp = prob.model
 sol = prob.solution
@@ -106,3 +108,5 @@ shoot!(s, p0, t1, t2, t3, tf)
 
 @test sol.converged
 @test norm(s) < 1e-6
+
+end
diff --git a/test/test_init.jl b/test/test_init.jl
@@ -0,0 +1,31 @@
+function test_init()
+
+    # get double integrator enregy min problem
+    prob = Problem(:integrator, :energy, :x_dim_2, :u_dim_1, :lagrange, :noconstraints)
+    ocp = prob.model
+
+    #
+    N = 50
+    tol = 1e-2
+   
+    # initial guess (constant state and control)
+    init = (state=[-0.5, 0.2], control=0.5)
+    sol = solve(ocp, grid_size=N, init=init)
+    @test sol.objective ≈ prob.solution.objective atol=tol
+
+    # initial guess (constant state and functional control)
+    init = (state=[-0.5, 0.2], control=t->6-12*t)
+    sol = solve(ocp, grid_size=N, init=init)
+    @test sol.objective ≈ prob.solution.objective atol=tol
+
+    # initial guess (functional state and constant control)
+    init = (state=t->[-1+t, t*(t-1)], control=0.5)
+    sol = solve(ocp, grid_size=N, init=init)
+    @test sol.objective ≈ prob.solution.objective atol=tol
+
+    # initial guess (functional state and functional control)
+    init = (state=t->[-1+t, t*(t-1)], control=t->6-12*t)
+    sol = solve(ocp, grid_size=N, init=init)
+    @test sol.objective ≈ prob.solution.objective atol=tol
+
+end

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# ct repl`
	`2`	`+`
	`3`	+See [`ctrepl`](@ref) method.
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Indirect simple shooting`
	`2`	`+`
	`3`	`+In construction.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Modelisation`
	`2`	`+`
	`3`	+See [`OptimalControlModel`](@ref) type.
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Plot solution`
	`2`	`+`
	`3`	+See [`plot`](@ref) method.