Skip to content

Commit 8658899

Browse files
ocotsocots
authored
Merge pull request #465 from control-toolbox/462-bug-link-broken-in-doc
up doc
2 parents 951ea74 + 13547ce commit 8658899

17 files changed

+109
-128
lines changed

‎docs/make.jl

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -31,24 +31,24 @@ makedocs(;
3131
],
3232
),
3333
pages=[
34-
"Introduction" => "index.md",
35-
"Basic examples" => [
34+
"Getting Started" => "index.md",
35+
"Basic Examples" => [
3636
"Energy minimisation" => "tutorial-double-integrator-energy.md",
3737
"Time mininimisation" => "tutorial-double-integrator-time.md",
3838
],
3939
"Manual" => [
40-
"Abstract syntax" => "tutorial-abstract.md",
41-
"Initial guess" => "tutorial-initial-guess.md",
42-
"Solve" => "tutorial-solve.md",
40+
"Define a problem" => "tutorial-abstract.md",
41+
"Set an initial guess" => "tutorial-initial-guess.md",
42+
"Solve a problem" => "tutorial-solve.md",
4343
"Plot a solution" => "tutorial-plot.md",
44-
"Flow" => "tutorial-flow.md",
44+
"Compute flows" => "tutorial-flow.md",
4545
],
46-
"Tutorials" => [
47-
"Discretisation options" => "tutorial-discretisation.md",
46+
"Tutorials and Advanced Features" => [
4847
"Discrete continuation" => "tutorial-continuation.md",
49-
"NLP options" => "tutorial-nlp.md",
50-
"Goddard: direct, indirect" => "tutorial-goddard.md",
48+
"Discretisation options" => "tutorial-discretisation.md",
49+
"NLP manipulations" => "tutorial-nlp.md",
5150
"Indirect simple shooting" => "tutorial-iss.md",
51+
"Goddard: direct, indirect" => "tutorial-goddard.md",
5252
"Linear–quadratic regulator" => "tutorial-lqr-basic.md",
5353
"Minimal action" => "tutorial-mam.md",
5454
],

‎docs/src/dev-ctbase.md

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,19 @@
11
# CTBase.jl
22

33
```@meta
4-
CollapsedDocStrings = true
4+
CollapsedDocStrings = false
55
```
66

77
The [CTBase.jl](control-toolbox.org/CTBase.jl/) package is part of the [control-toolbox ecosystem](https://github.com/control-toolbox).
88

99
```mermaid
1010
flowchart TD
11-
B(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctbase.html'>CTBase</a>)
12-
M(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctmodels.html'>CTModels</a>)
13-
P(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctparser.html'>CTParser</a>)
14-
O(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-optimalcontrol.html'>OptimalControl</a>)
15-
D(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctdirect.html'>CTDirect</a>)
16-
F(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctflows.html'>CTFlows</a>)
11+
B(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctbase.html'>CTBase</a>)
12+
M(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctmodels.html'>CTModels</a>)
13+
P(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctparser.html'>CTParser</a>)
14+
O(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-optimalcontrol.html'>OptimalControl</a>)
15+
D(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctdirect.html'>CTDirect</a>)
16+
F(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctflows.html'>CTFlows</a>)
1717
O --> D
1818
O --> M
1919
O --> F

‎docs/src/dev-ctdirect.md

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,19 @@
11
# CTDirect.jl
22

33
```@meta
4-
CollapsedDocStrings = true
4+
CollapsedDocStrings = false
55
```
66

77
The [CTDirect.jl](control-toolbox.org/CTDirect.jl) package is part of the [control-toolbox ecosystem](https://github.com/control-toolbox).
88

99
```mermaid
1010
flowchart TD
11-
B(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctbase.html'>CTBase</a>)
12-
M(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctmodels.html'>CTModels</a>)
13-
P(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctparser.html'>CTParser</a>)
14-
O(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-optimalcontrol.html'>OptimalControl</a>)
15-
D(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctdirect.html'>CTDirect</a>)
16-
F(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctflows.html'>CTFlows</a>)
11+
B(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctbase.html'>CTBase</a>)
12+
M(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctmodels.html'>CTModels</a>)
13+
P(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctparser.html'>CTParser</a>)
14+
O(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-optimalcontrol.html'>OptimalControl</a>)
15+
D(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctdirect.html'>CTDirect</a>)
16+
F(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctflows.html'>CTFlows</a>)
1717
O --> D
1818
O --> M
1919
O --> F

‎docs/src/dev-ctflows.md

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,19 @@
11
# CTFlows.jl
22

33
```@meta
4-
CollapsedDocStrings = true
4+
CollapsedDocStrings = false
55
```
66

77
The [CTFlows.jl](control-toolbox.org/CTFlows.jl) package is part of the [control-toolbox ecosystem](https://github.com/control-toolbox).
88

99
```mermaid
1010
flowchart TD
11-
B(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctbase.html'>CTBase</a>)
12-
M(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctmodels.html'>CTModels</a>)
13-
P(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctparser.html'>CTParser</a>)
14-
O(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-optimalcontrol.html'>OptimalControl</a>)
15-
D(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctdirect.html'>CTDirect</a>)
16-
F(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctflows.html'>CTFlows</a>)
11+
B(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctbase.html'>CTBase</a>)
12+
M(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctmodels.html'>CTModels</a>)
13+
P(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctparser.html'>CTParser</a>)
14+
O(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-optimalcontrol.html'>OptimalControl</a>)
15+
D(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctdirect.html'>CTDirect</a>)
16+
F(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctflows.html'>CTFlows</a>)
1717
O --> D
1818
O --> M
1919
O --> F

‎docs/src/dev-ctmodels.md

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,19 @@
11
# CTModels.jl
22

33
```@meta
4-
CollapsedDocStrings = true
4+
CollapsedDocStrings = false
55
```
66

77
The [CTModels.jl](control-toolbox.org/CTModels.jl) package is part of the [control-toolbox ecosystem](https://github.com/control-toolbox).
88

99
```mermaid
1010
flowchart TD
11-
B(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctbase.html'>CTBase</a>)
12-
M(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctmodels.html'>CTModels</a>)
13-
P(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctparser.html'>CTParser</a>)
14-
O(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-optimalcontrol.html'>OptimalControl</a>)
15-
D(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctdirect.html'>CTDirect</a>)
16-
F(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctflows.html'>CTFlows</a>)
11+
B(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctbase.html'>CTBase</a>)
12+
M(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctmodels.html'>CTModels</a>)
13+
P(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctparser.html'>CTParser</a>)
14+
O(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-optimalcontrol.html'>OptimalControl</a>)
15+
D(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctdirect.html'>CTDirect</a>)
16+
F(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctflows.html'>CTFlows</a>)
1717
O --> D
1818
O --> M
1919
O --> F

‎docs/src/dev-ctparser.md

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,19 @@
11
# CTParser.jl
22

33
```@meta
4-
CollapsedDocStrings = true
4+
CollapsedDocStrings = false
55
```
66

77
The [CTParser.jl](control-toolbox.org/CTParser.jl) package is part of the [control-toolbox ecosystem](https://github.com/control-toolbox).
88

99
```mermaid
1010
flowchart TD
11-
B(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctbase.html'>CTBase</a>)
12-
M(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctmodels.html'>CTModels</a>)
13-
P(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctparser.html'>CTParser</a>)
14-
O(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-optimalcontrol.html'>OptimalControl</a>)
15-
D(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctdirect.html'>CTDirect</a>)
16-
F(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctflows.html'>CTFlows</a>)
11+
B(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctbase.html'>CTBase</a>)
12+
M(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctmodels.html'>CTModels</a>)
13+
P(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctparser.html'>CTParser</a>)
14+
O(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-optimalcontrol.html'>OptimalControl</a>)
15+
D(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctdirect.html'>CTDirect</a>)
16+
F(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctflows.html'>CTFlows</a>)
1717
O --> D
1818
O --> M
1919
O --> F

‎docs/src/dev-optimalcontrol.md

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,19 @@
11
# OptimalControl.jl
22

33
```@meta
4-
CollapsedDocStrings = true
4+
CollapsedDocStrings = false
55
```
66

77
The [OptimalControl.jl](https://control-toolbox.org/OptimalControl.jl) package is part of the [control-toolbox ecosystem](https://github.com/control-toolbox).
88

99
```mermaid
1010
flowchart TD
11-
B(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctbase.html'>CTBase</a>)
12-
M(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctmodels.html'>CTModels</a>)
13-
P(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctparser.html'>CTParser</a>)
14-
O(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-optimalcontrol.html'>OptimalControl</a>)
15-
D(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctdirect.html'>CTDirect</a>)
16-
F(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctflows.html'>CTFlows</a>)
11+
B(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctbase.html'>CTBase</a>)
12+
M(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctmodels.html'>CTModels</a>)
13+
P(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctparser.html'>CTParser</a>)
14+
O(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-optimalcontrol.html'>OptimalControl</a>)
15+
D(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctdirect.html'>CTDirect</a>)
16+
F(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctflows.html'>CTFlows</a>)
1717
O --> D
1818
O --> M
1919
O --> F

‎docs/src/index.md

Lines changed: 10 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -4,44 +4,15 @@
44
CurrentModule = OptimalControl
55
```
66

7-
The OptimalControl.jl package is the root package of the [control-toolbox ecosystem](https://github.com/control-toolbox).
8-
The control-toolbox ecosystem gathers Julia packages for mathematical control and applications. It aims to provide tools to model and solve optimal control problems with ordinary differential equations by direct and indirect methods.
7+
The OptimalControl.jl package is the root package of the [control-toolbox ecosystem](https://github.com/control-toolbox). The control-toolbox ecosystem gathers Julia packages for mathematical control and applications. It aims to provide tools to model and solve optimal control problems with ordinary differential equations by direct and indirect methods.
98

109
## Installation
1110

12-
To install OptimalControl.jl please
13-
[open Julia's interactive session (known as REPL)](https://docs.julialang.org/en/v1/manual/getting-started)
14-
and press `]` key in the REPL to use the package mode, then add the package:
11+
To install OptimalControl.jl, please [open Julia's interactive session (known as REPL)](https://docs.julialang.org/en/v1/manual/getting-started) and use the Julia package manager:
1512

1613
```julia
17-
julia> ]
18-
pkg> add OptimalControl
19-
```
20-
21-
## Mathematical problem
22-
23-
A (nonautonomous) optimal control problem with possibly free initial and final times can be described as minimising the cost functional
24-
25-
```math
26-
g(t_0, x(t_0), t_f, x(t_f)) + \int_{t_0}^{t_f} f^{0}(t, x(t), u(t))~\mathrm{d}t
27-
```
28-
29-
where the state $x$ and the control $u$ are functions subject, for $t \in [t_0, t_f]$,
30-
to the differential constraint
31-
32-
```math
33-
\dot{x}(t) = f(t, x(t), u(t))
34-
```
35-
36-
and other constraints such as
37-
38-
```math
39-
\begin{array}{llcll}
40-
~\xi_l &\le& \xi(t, u(t)) &\le& \xi_u, \\
41-
\eta_l &\le& \eta(t, x(t)) &\le& \eta_u, \\
42-
\psi_l &\le& \psi(t, x(t), u(t)) &\le& \psi_u, \\
43-
\phi_l &\le& \phi(t_0, x(t_0), t_f, x(t_f)) &\le& \phi_u.
44-
\end{array}
14+
using Pkg
15+
Pkg.add("OptimalControl")
4516
```
4617

4718
## Basic usage
@@ -68,9 +39,10 @@ sol = solve(ocp)
6839
plot(sol)
6940
```
7041

71-
For more details about this problem, please check the [basic example tutorial](@ref tutorial-double-integrator-energy).
72-
For a comprehensive introduction to the syntax used above to describe the optimal control problem, check the [abstract syntax tutorial](@ref tutorial-abstract).
73-
The solve options are described in the [solve tutorial](@ref tutorial-solve).
42+
- For more details about this problem, please check the [basic example tutorial](@ref tutorial-double-integrator-energy).
43+
- For a comprehensive introduction to the syntax used above to describe the optimal control problem, check the [abstract syntax tutorial](@ref tutorial-abstract-syntax).
44+
- The `solve` function has options, see the [solve tutorial](@ref tutorial-solve).
45+
- You can customise the plot with the `plot` function, see the [plot tutorial](@ref tutorial-plot).
7446

7547
## Citing us
7648

@@ -92,13 +64,9 @@ url = {https://control-toolbox.org/OptimalControl.jl}
9264

9365
## Contributing
9466

95-
If you think you found a bug or if you have a feature request / suggestion, feel free to open an
96-
[issue](https://github.com/control-toolbox/OptimalControl.jl/issues).
97-
Before opening a pull request, please start an issue or a discussion on the topic.
67+
If you think you found a bug or if you have a feature request / suggestion, feel free to open an [issue](https://github.com/control-toolbox/OptimalControl.jl/issues). Before opening a pull request, please start an issue or a discussion on the topic.
9868

99-
Contributions are welcomed, check out [how to contribute to a Github project](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project).
100-
If it is your first contribution, you can also check [this first contribution tutorial](https://github.com/firstcontributions/first-contributions).
101-
You can find first good issues (if any 🙂) [here](https://github.com/control-toolbox/OptimalControl.jl/contribute). You may find other packages to contribute to at the [control-toolbox organization](https://github.com/control-toolbox).
69+
Contributions are welcomed, check out [how to contribute to a Github project](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project). If it is your first contribution, you can also check [this first contribution tutorial](https://github.com/firstcontributions/first-contributions). You can find first good issues (if any 🙂) [here](https://github.com/control-toolbox/OptimalControl.jl/contribute). You may find other packages to contribute to at the [control-toolbox organization](https://github.com/control-toolbox).
10270

10371
If you want to ask a question, feel free to start a discussion [here](https://github.com/orgs/control-toolbox/discussions). This forum is for general discussion about this repository and the [control-toolbox organization](https://github.com/control-toolbox).
10472

‎docs/src/tutorial-abstract.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# [The abstract syntax to define an optimal control problem](@id tutorial-abstract)
1+
# [The syntax to define an optimal control problem](@id tutorial-abstract-syntax)
22

33
The full grammar of [OptimalControl.jl](https://control-toolbox.org/OptimalControl.jl) small *Domain Specific Language* is given below. The idea is to use a syntax that is
44
- pure Julia (and, as such, effortlessly analysed by the standard Julia parser),

‎docs/src/tutorial-double-integrator-energy.md

Lines changed: 30 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# [Double integrator: energy min (abstract syntax)](@id tutorial-double-integrator-energy)
1+
# [Double integrator: energy min](@id tutorial-double-integrator-energy)
22

33
Let us consider a wagon moving along a rail, whom acceleration can be controlled by a force $u$.
44
We denote by $x = (x_1, x_2)$ the state of the wagon, that is its position $x_1$ and its velocity $x_2$.
@@ -51,7 +51,7 @@ nothing # hide
5151

5252
!!! note "Nota bene"
5353

54-
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.*
54+
For a comprehensive introduction to the syntax used above to define the optimal control problem, check [this abstract syntax tutorial](@ref tutorial-abstract-syntax). In particular, there are non-unicode alternatives for derivatives, integrals, *etc.*
5555

5656
## [Solve and plot](@id basic-solve-plot)
5757

@@ -68,6 +68,10 @@ And plot the solution with:
6868
plot(sol)
6969
```
7070

71+
!!! note "Nota bene"
72+
73+
The `solve` function has options, see the [solve tutorial](@ref tutorial-solve). You can customise the plot with the `plot` function, see the [plot tutorial](@ref tutorial-plot).
74+
7175
## State constraint
7276

7377
We add the path constraint
@@ -76,6 +80,8 @@ We add the path constraint
7680
x_2(t) \le 1.2.
7781
```
7882

83+
Let us model, solve and plot the optimal control problem with this constraint.
84+
7985
```@example main
8086
ocp = @def begin
8187
@@ -95,28 +101,40 @@ ocp = @def begin
95101
end
96102
97103
sol = solve(ocp)
104+
98105
plot(sol)
99106
```
100107

101-
## Save and load
108+
## Exporting and importing the solution
109+
110+
We can export (or save) the solution in a Julia `.jld2` data file and reload it later, and also export a discretised version of the solution in a more portable [JSON](https://en.wikipedia.org/wiki/JSON) format. Note that the optimal control problem is needed when loading a solution.
102111

103-
We can save the solution in a Julia `.jld2` data file and reload it later, and also export a discretised version of the solution in a more portable [JSON](https://en.wikipedia.org/wiki/JSON) format. Note that the OCP is needed when loading a solution.
112+
### JLD2
104113

105114
```@example main
106-
# load additional modules
107-
using JLD2, JSON3
115+
using JLD2
108116
109-
# JLD save / load
110117
using Suppressor # hide
111118
@suppress_err begin # hide
112119
export_ocp_solution(sol; filename_prefix="my_solution")
113120
end # hide
114-
sol_reloaded = import_ocp_solution(ocp; filename_prefix="my_solution")
115-
println("Objective from loaded solution: ", sol_reloaded.objective)
116121
117-
# JSON export / read
122+
sol_jld = import_ocp_solution(ocp; filename_prefix="my_solution")
123+
124+
println("Objective from computed solution: ", objective(sol))
125+
println("Objective from imported solution: ", objective(sol_jld))
126+
```
127+
128+
### JSON
129+
130+
```@example main
131+
# load additional modules
132+
using JSON3
133+
118134
export_ocp_solution(sol; filename_prefix="my_solution", format=:JSON)
135+
119136
sol_json = import_ocp_solution(ocp; filename_prefix="my_solution", format=:JSON)
120-
println("Objective from JSON discrete solution: ", sol_json.objective)
121-
```
122137
138+
println("Objective from computed solution: ", objective(sol))
139+
println("Objective from imported solution: ", objective(sol_json))
140+
```

0 commit comments

Comments
 (0)