From 3bfcf77c7bd5eb8c5c4215a716d07579d7b5d8c0 Mon Sep 17 00:00:00 2001 From: Olivier Cots Date: Wed, 18 Sep 2024 22:51:14 +0200 Subject: [PATCH] up doc --- .JuliaFormatter.toml | 7 ---- .github/workflows/Formatter.yml | 2 +- docs/Project.toml | 1 + docs/src/api-ctbase.md | 2 +- docs/src/api-ctdirect.md | 2 +- docs/src/api-ctflows.md | 2 +- docs/src/api-optimalcontrol.md | 2 +- src/solve.jl | 73 ++++++++++++++++++++++++--------- 8 files changed, 60 insertions(+), 31 deletions(-) delete mode 100644 .JuliaFormatter.toml diff --git a/.JuliaFormatter.toml b/.JuliaFormatter.toml deleted file mode 100644 index 8bb13b8e..00000000 --- a/.JuliaFormatter.toml +++ /dev/null @@ -1,7 +0,0 @@ -margin = 100 -indent = 4 -whitespace_typedefs = true -whitespace_ops_in_indices = true -remove_extra_newlines = true -annotate_untyped_fields_with_any = false -normalize_line_endings = "unix" diff --git a/.github/workflows/Formatter.yml b/.github/workflows/Formatter.yml index a9b2a7a7..7b2299eb 100644 --- a/.github/workflows/Formatter.yml +++ b/.github/workflows/Formatter.yml @@ -17,7 +17,7 @@ jobs: - name: Install JuliaFormatter and format run: | julia -e 'import Pkg; Pkg.add("JuliaFormatter")' - julia -e 'using JuliaFormatter; format(".")' + julia -e 'using JuliaFormatter; format(".", BlueStyle())' # https://github.com/marketplace/actions/create-pull-request # https://github.com/peter-evans/create-pull-request#reference-example - name: Create Pull Request diff --git a/docs/Project.toml b/docs/Project.toml index f6fc7673..774632f6 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -16,6 +16,7 @@ MINPACK = "4854310b-de5a-5eb6-a2a5-c1dee2bd17f9" MadNLP = "2621e9c9-9eb4-46b1-8089-e8c72242dfb6" NLPModelsIpopt = "f4238b75-b362-5c4c-b852-0801c9a21d71" NonlinearSolve = "8913a72c-1f9b-4ce2-8d82-65094dcecaec" +OptimalControl = "5f98b655-cc9a-415a-b60e-744165666948" OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed" Percival = "01435c0c-c90d-11e9-3788-63660f8fbccc" Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80" diff --git a/docs/src/api-ctbase.md b/docs/src/api-ctbase.md index 692c2c45..8374346f 100644 --- a/docs/src/api-ctbase.md +++ b/docs/src/api-ctbase.md @@ -8,7 +8,7 @@ The [CTBase.jl](control-toolbox.org/CTBase.jl/) package is part of the [control- ```mermaid flowchart TD -O(OptimalControl) --> B(CTBase) +O(OptimalControl) --> B(CTBase) O --> D(CTDirect) O --> F(CTFlows) F --> B diff --git a/docs/src/api-ctdirect.md b/docs/src/api-ctdirect.md index 23a498bd..72f0b98d 100644 --- a/docs/src/api-ctdirect.md +++ b/docs/src/api-ctdirect.md @@ -8,7 +8,7 @@ The [CTDirect.jl](control-toolbox.org/CTDirect.jl) package is part of the [contr ```mermaid flowchart TD -O(OptimalControl) --> B(CTBase) +O(OptimalControl) --> B(CTBase) O --> D(CTDirect) O --> F(CTFlows) F --> B diff --git a/docs/src/api-ctflows.md b/docs/src/api-ctflows.md index 41e7b3e8..e594f47e 100644 --- a/docs/src/api-ctflows.md +++ b/docs/src/api-ctflows.md @@ -8,7 +8,7 @@ The [CTFlows.jl](control-toolbox.org/CTFlows.jl) package is part of the [control ```mermaid flowchart TD -O(OptimalControl) --> B(CTBase) +O(OptimalControl) --> B(CTBase) O --> D(CTDirect) O --> F(CTFlows) F --> B diff --git a/docs/src/api-optimalcontrol.md b/docs/src/api-optimalcontrol.md index 3b1bfdff..a239c2be 100644 --- a/docs/src/api-optimalcontrol.md +++ b/docs/src/api-optimalcontrol.md @@ -8,7 +8,7 @@ The [OptimalControl.jl](https://control-toolbox.org/OptimalControl.jl) package i ```mermaid flowchart TD -O(OptimalControl) --> B(CTBase) +O(OptimalControl) --> B(CTBase) O --> D(CTDirect) O --> F(CTFlows) F --> B diff --git a/src/solve.jl b/src/solve.jl index c3ff0eb9..4edfb471 100644 --- a/src/solve.jl +++ b/src/solve.jl @@ -1,7 +1,7 @@ """ $(TYPEDSIGNATURES) -Return the list of available methods to solve the optimal control problem. +Return the list of available methods that can be used to solve the optimal control problem. """ function available_methods() # by order of preference: from top to bottom @@ -15,8 +15,13 @@ end """ $(TYPEDSIGNATURES) -Remove from the description, the Symbol that are specific to [OptimalControl.jl](https://control-toolbox.org/OptimalControl.jl) and so must not -be passed. +When calling the function `solve`, the user can provide a description of the method to use to solve the optimal control problem. +The description can be a partial description or a full description. +The function `solve` will find the best match from the available methods, thanks to the function `getFullDescription`. +Then, the description is cleaned by the function `clean` to remove the Symbols that are specific to +[OptimalControl.jl](https://control-toolbox.org/OptimalControl.jl) and so must not be passed to the solver. +For instance, the Symbol `:direct` is specific to [OptimalControl.jl](https://control-toolbox.org/OptimalControl.jl) and must be removed. +It must not be passed to the CTDirect.jl solver. """ function clean(d::Description) return remove(d, (:direct,)) @@ -26,37 +31,67 @@ end $(TYPEDSIGNATURES) Solve the the optimal control problem `ocp` by the method given by the (optional) description. +The available methods are given by `available_methods()`. +The higher in the list, the higher is the priority. +The keyword arguments are specific to the chosen method and represent the options of the solver. -# The (optional) description +!!! note + See the [tutorial on solving optimal control problems](@ref tutorial-solve) for more information. -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, -the higher is the priority. To get the list of available methods, call `available_methods()`. +# Arguments -Keyword arguments: you can pass any other option by a pair `keyword=value` according to the chosen method. +- `ocp::OptimalControlModel`: the optimal control problem to solve. +- `description::Symbol...`: the description of the method to use to solve the problem. +- `kwargs...`: the options of the solver. # Examples -```julia-repl +The simplest way to solve the optimal control problem is to call the function without any argument. + +```julia-rep julia> sol = solve(ocp) +``` + +The method can be specified by passing the description as a Symbol. You can provide a partial description, the function will +find the best match. + +```julia-rep julia> sol = solve(ocp, :direct) -julia> sol = solve(ocp, :direct, :ipopt) +``` + +The method can be specified by passing the full description as a list of Symbols. + +```julia-repl +julia> sol = solve(ocp, :direct, :adnlp, :ipopt) +``` + +The keyword arguments are specific to the chosen method and represent the options of the solver. +For example, the keyword `display` is used to display the information of the solver. +The default value is `true`. + +```julia-rep 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],)) +``` + +The initial guess can be provided by the keyword `init`. +You can provide the initial guess for the state, control, and variable. + +```julia-rep 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)) ``` + +!!! tip + For more information on how to provide the initial guess, see the [tutorial on the initial guess](@ref tutorial-init). + """ -function CommonSolve.solve(ocp::OptimalControlModel, description::Symbol...; kwargs...) +function CommonSolve.solve(ocp::OptimalControlModel, description::Symbol...; kwargs...)::OptimalControlSolution # get the full description method = getFullDescription(description, available_methods()) # solve the problem - :direct ∈ method && return CTDirect.direct_solve(ocp, clean(description)...; kwargs...) + if :direct ∈ method + return CTDirect.direct_solve(ocp, clean(description)...; kwargs...) + end + end