Skip to content

Commit a0c3111

Browse files
committed
Updated DOP docs, updated phases.
1 parent ddd4b31 commit a0c3111

12 files changed

Lines changed: 161 additions & 159 deletions

File tree

docs/make.jl

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,12 @@ DocMeta.setdocmeta!(DynOptInterface, :DocTestSetup, :(import DynOptInterface as
88
const _PAGES = [
99
"Home" => "index.md",
1010
"Dynamic Optimization" => "dynamic_optimization.md",
11+
"Tutorials" => [
12+
"Solving a DOP" => "tutorials/solving_dop.md",
13+
"Interfacing with a solver" => "tutorials/interfacing_solver.md",
14+
],
1115
"API Reference" => [
1216
"Dynamic Functions" => [
13-
"reference/dynamic_functions/abstraction.md",
1417
"reference/dynamic_functions/phases.md",
1518
"reference/dynamic_functions/dynamic_variables.md",
1619
"reference/dynamic_functions/expressions.md",

docs/src/dynamic_optimization.md

Lines changed: 71 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -4,60 +4,90 @@ CurrentModule = DynOptInterface
44

55
# Dynamic Optimization
66

7-
## Phases and Dynamic Variables
7+
This section describes the formulation of a generic multi-phase dynamic optimization problem (DOP).
8+
This formulation extends MathOptInterface's [Function-in-Set formulation](@extref Standard-form-problem) for *finite-dimensional* optimization problems.
89

9-
Phases represent intervals $t \in [t_0, t_f]$ on which dynamic variables $t \mapsto \boldsymbol y(t)$ are defined.
10+
## Finite-Dimensional Optimization
1011

11-
![dynamic variable](assets/dynamic_variable.png)
12+
A finite-dimensional optimization problem is defined as finding the variables ``x`` that
13+
```math
14+
\begin{equation*}
15+
\begin{aligned}
16+
\text{minimize} \quad &f_o(x),\\
17+
\text{subject to} \quad &f_c(x) \in \mathcal{S},
18+
\end{aligned}
19+
\end{equation*}
20+
```
21+
where ``f_o`` is the objective function, ``f_c`` is the constraints function, and ``\mathcal{S}`` is the constraints set.
22+
23+
## Phases
24+
25+
A *phase* is an interval (e.g., a time segment) whose boundaries can be optimization variables.
26+
The ``i``-th phase of a DOP is the interval between ``t_0^{(i)}`` and ``t_f^{(i)}``.
27+
Moreover, ``t^{(i)}`` is a parameter that takes values in the ``i``-th phase.
28+
29+
| Symbol | Description | Element Type |
30+
|:-:|:--|:--|
31+
| ``t_0`` | Vector of initial boundaries of phases | [`Initial`](@ref)`{`[`PhaseIndex`](@ref)`}` |
32+
| ``t_f`` | Vector of final boundaries of phases | [`Final`](@ref)`{`[`PhaseIndex`](@ref)`}` |
33+
34+
## Dynamic Variables
35+
36+
A *dynamic variable* is an optimizable function defined on a phase.
37+
The ``j``-th dynamic variable of a DOP, defined on the ``i``-th phase, is denoted as
38+
```math
39+
\begin{equation*}
40+
t^{(i)} \mapsto \boldsymbol y_j(t^{(i)}).
41+
\end{equation*}
42+
```
43+
The first derivative of ``\boldsymbol y_j`` is denoted as ``\dot{\boldsymbol y}_j``.
44+
45+
| Symbol | Description | Element Type |
46+
|:-:|:--|:--|
47+
| ``\boldsymbol y`` | Vector of dynamic variables | [`DynamicVariableIndex`](@ref) |
48+
| ``\dot{\boldsymbol y}`` | Vector of derivatives of dynamic variables | [`Derivative`](@ref)`{`[`DynamicVariableIndex`](@ref)`}` |
49+
50+
## Objective
1251

13-
## Problem Formulation
52+
The objective function is augmented to include a boundary term and an integrated dynamic term.
1453

15-
MOI's [Function-in-Set form problem](@extref Standard-form-problem) is extended as follows.
16-
Dynamic Optimization Problems deal with finding variables $x \in \mathbb R^{n_x}$, phase boundaries $t_0^{(i)} \in \mathbb R$, $t_f^{(i)} \in \mathbb R$, and dynamic variables $\boldsymbol y^{(i)} : [t_0^{(i)}, t_f^{(i)}] \rightarrow \mathbb R^{n_y^{(i)}}$ that
54+
| Symbol | Description | Type |
55+
|:-:|:--|:--|
56+
| ``f_o`` | Finite-dimensional objective function | `<:`[`MOI.AbstractScalarFunction`](@extref MathOptInterface.AbstractScalarFunction) |
57+
| ``b_o`` | Boundary objective function | `<:`[`AbstractBoundaryFunction`](@ref) |
58+
| ``d_o^{(i)}`` | The ``i``-th phase dynamic objective function | `<:`[`AbstractDynamicFunction`](@ref) |
1759

60+
## Constraints
61+
62+
The constraints are extended to include *boundary constraints* and *dynamic constraints*.
63+
64+
| Symbol | Description | Element Type |
65+
|:-:|:--|:--|
66+
| ``f_c`` | Finite-dimensional constraint functiosn | `<:`[`MOI.AbstractScalarFunction`](@extref MathOptInterface.AbstractScalarFunction) |
67+
| ``\mathcal{S}`` | Finite-dimensional constraint sets | `<`[`MOI.AbstractScalarSet`](@extref MathOptInterface.AbstractScalarSet) |
68+
| ``b_c`` | Boundary constraint functions | `<:`[`AbstractBoundaryFunction`](@ref) |
69+
| ``\mathcal{B}`` | Boundary constraint sets| `<`[`MOI.AbstractScalarSet`](@extref MathOptInterface.AbstractScalarSet) |
70+
| ``d_c^{(i)}`` | The ``i``-th phase dynamic constraint functions | `<:`[`AbstractDynamicFunction`](@ref) |
71+
| ``\mathcal{D}^{(i)}`` | The ``i``-th phase dynamic constraint sets | `<`[`MOI.AbstractScalarSet`](@extref MathOptInterface.AbstractScalarSet) |
72+
73+
## DOP Formulation
74+
75+
The dynamic optimization problem is defined as finding the variables ``x``, the phase boundaries ``t_0``, ``t_f``, and the dynamic variables ``\boldsymbol y`` that
1876
```math
1977
\begin{align*}
2078
\begin{array}{rl}
2179
\text{minimize} \quad &
22-
m \big( \boldsymbol y(t_0), \boldsymbol y(t_f), t_0, t_f, x \big) +
80+
f_o(x) + b_o \big( \boldsymbol y(t_0), \boldsymbol y(t_f), t_0, t_f, x \big) +
2381
\displaystyle{\sum_{i=1}^{n_p} \bigg[
24-
\int_{t_0^{(i)}}^{t_f^{(i)}} \ell^{(i)} \big( \boldsymbol y^{(i)}(t), t, x \big) \textrm{d}t \bigg],}\\
82+
\int_{t_0^{(i)}}^{t_f^{(i)}} d_o^{(i)} \big( \boldsymbol y^{(i)}(t), t, x \big) \textrm{d}t \bigg],}\\
2583
%
2684
\text{subject to} \quad &
2785
\begin{aligned}
28-
f(x) & \in \mathcal S,\\
29-
%
30-
d^{(i)}\big(\dot{\boldsymbol y}^{(i)}(t), \boldsymbol y^{(i)}(t), t, x) & \in \mathcal D^{(i)},
31-
\quad \forall t \in [t_0^{(i)}, t_f^{(i)}],
32-
\quad \forall i \in \{1, 2, ..., n_p\},\\
33-
b(\boldsymbol y(t_0), \boldsymbol y(t_f), t_0, t_f, x) &\in \mathcal B,
86+
f_c(x) & \in \mathcal S,\\
87+
b_c(\boldsymbol y(t_0), \boldsymbol y(t_f), t_0, t_f, x) &\in \mathcal B,\\
88+
d^{(i)}\big(\dot{\boldsymbol y}^{(i)}(t^{(i)}), \boldsymbol y^{(i)}(t^{(i)}), t^{(i)}, x) & \in \mathcal D^{(i)},
89+
\quad \forall t^{(i)} \in [t_0^{(i)}, t_f^{(i)}], \quad \forall i \in \{1, 2, ..., n_p\}.
3490
\end{aligned}
3591
\end{array}
3692
\end{align*}
37-
```
38-
39-
where:
40-
* ``f`` are [`MOI.AbstractScalarFunction`](@extref MathOptInterface.AbstractScalarFunction)s
41-
* ``\ell`` and ``d`` are [`AbstractDynamicFunction`](@ref)s
42-
* ``m`` and ``b`` are [`AbstractBoundaryFunction`](@ref)s
43-
44-
45-
## Dynamic Functions
46-
47-
* [`PhaseIndex`](@ref)
48-
* [`DynamicVariableIndex`](@ref)
49-
* [`LinearDynamicFunction`](@ref)
50-
* [`PureQuadraticDynamicFunction`](@ref)
51-
* [`NonlinearDynamicFunction`](@ref)
52-
* [`Derivative`](@ref)
53-
* [`ExplicitDifferentialFunction`](@ref)
54-
55-
## Boundary Functions
56-
57-
* [`Initial`](@ref)
58-
* [`Final`](@ref)
59-
* [`Linkage`](@ref)
60-
* [`NonlinearBoundaryFunction`](@ref)
61-
* [`Integral`](@ref)
62-
* [`MultiPhaseIntegral`](@ref)
63-
* [`Bolza`](@ref)
93+
```

docs/src/reference/dynamic_functions/abstraction.md

Lines changed: 0 additions & 11 deletions
This file was deleted.

docs/src/reference/dynamic_functions/phases.md

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,20 +5,28 @@ CurrentModule = DynOptInterface
55
# Phases
66

77
```@docs
8+
AbstractDynamicFunction
89
PhaseIndex
9-
supports_phase
10-
UnsupportedPhase
11-
AddPhaseNotAllowed
10+
phase_index
11+
NonUniquePhaseError
12+
```
13+
14+
# Phases in Models
15+
16+
```@docs
17+
supports_phases
18+
UnsupportedPhasesError
1219
add_phase
20+
AddPhaseNotAllowedError
1321
MOI.is_valid(::MOI.ModelLike, ::PhaseIndex)
14-
InvalidPhaseIndex
22+
InvalidPhaseError
1523
```
1624

1725
# Phase Attributes
1826

1927
```@docs
2028
AbstractPhaseAttribute
21-
MOI.supports(::MOI.ModelLike, ::AbstractPhaseAttribute, ::Type{PhaseIndex})
29+
MOI.supports(::MOI.ModelLike, ::AbstractPhaseAttribute)
2230
MOI.set(::MOI.ModelLike, ::AbstractPhaseAttribute, ::PhaseIndex, ::Any)
2331
MOI.get(::MOI.ModelLike, ::AbstractPhaseAttribute, ::PhaseIndex)
2432
PhaseName

docs/src/tutorials/interfacing_solver.md

Whitespace-only changes.

docs/src/tutorials/solving_dop.md

Whitespace-only changes.

src/DynOptInterface.jl

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,6 @@ module DynOptInterface
22

33
import MathOptInterface as MOI
44

5-
include("dynamic_functions/abstraction.jl")
65
include("dynamic_functions/phases.jl")
76
include("dynamic_functions/dynamic_variables.jl")
87
include("dynamic_functions/expressions.jl")

src/dynamic_functions/abstraction.jl

Lines changed: 0 additions & 32 deletions
This file was deleted.

src/dynamic_functions/derivatives.jl

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ An object representing the function ``t_i \\mapsto \\dot{y}(t_i) - f_d(y(t_i), t
3333
3434
It is a sub-type of [`AbstractDynamicFunction`](@ref). The derivative (stored in the `derivative`
3535
field) and the dynamic function (stored in the `dyn_fun` field) must be defined in the same
36-
phase, otherwise a [`MixedPhases`](@ref) error is thrown.
36+
phase, otherwise a [`NonUniquePhaseError`](@ref) error is thrown.
3737
"""
3838
struct ExplicitDifferentialFunction{D<:AbstractDynamicFunction,F<:AbstractDynamicFunction} <:
3939
AbstractDynamicFunction
@@ -45,7 +45,7 @@ struct ExplicitDifferentialFunction{D<:AbstractDynamicFunction,F<:AbstractDynami
4545
dyn_fun::F,
4646
) where {D<:AbstractDynamicFunction, F<:AbstractDynamicFunction}
4747
if phase_index(derivative) != phase_index(dyn_fun)
48-
throw(MixedPhases(""))
48+
throw(NonUniquePhaseError(""))
4949
end
5050
return new{D,F}(derivative, dyn_fun)
5151
end

src/dynamic_functions/expressions.jl

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ Represents the function ``t_i \\mapsto c^\\top y(t_i)``, which is a sum of
3939
[`LinearDynamicTerm`](@ref)s.
4040
4141
It is sub-type of [`AbstractDynamicFunction`](@ref). All dynamic variables must be defined
42-
on the same phase, otherwise a [`MixedPhases`](@ref) error is thrown. The
42+
on the same phase, otherwise a [`NonUniquePhaseError`](@ref) error is thrown. The
4343
[`LinearDynamicTerm`](@ref)s are stored in the `terms` field.
4444
"""
4545
struct LinearDynamicFunction{T} <: AbstractDynamicFunction
@@ -49,7 +49,7 @@ struct LinearDynamicFunction{T} <: AbstractDynamicFunction
4949
terms::Vector{LinearDynamicTerm{T}},
5050
) where {T}
5151
if !all(term -> phase_index(term) == phase_index(first(terms)), terms)
52-
throw(MixedPhases(""))
52+
throw(NonUniquePhaseError(""))
5353
end
5454
return new{T}(terms)
5555
end
@@ -95,7 +95,7 @@ struct PureQuadraticDynamicTerm{T}
9595
dyn_var_b::DynamicVariableIndex,
9696
) where {T}
9797
if phase_index(dyn_var_a) != phase_index(dyn_var_b)
98-
throw(MixedPhases)
98+
throw(NonUniquePhaseError)
9999
end
100100
return new{T}(coefficient, dyn_var_a, dyn_var_b)
101101
end
@@ -130,7 +130,7 @@ Represents the function ``t_i \\mapsto y(t_i)^\\top C y(t_i)``, which is a sum o
130130
[`PureQuadraticDynamicTerm`](@ref)s.
131131
132132
A sub-type of [`AbstractDynamicFunction`](@ref). All dynamic variables must be defined
133-
on the same phase, otherwise a [`MixedPhases`](@ref) error is thrown. The
133+
on the same phase, otherwise a [`NonUniquePhaseError`](@ref) error is thrown. The
134134
[`PureQuadraticDynamicTerm`](@ref)s are stored in the `terms` field.
135135
"""
136136
struct PureQuadraticDynamicFunction{T} <: AbstractDynamicFunction
@@ -140,7 +140,7 @@ struct PureQuadraticDynamicFunction{T} <: AbstractDynamicFunction
140140
terms::Vector{PureQuadraticDynamicTerm{T}},
141141
) where {T}
142142
if !all(term -> phase_index(term) == phase_index(first(terms)), terms)
143-
throw(MixedPhases(""))
143+
throw(NonUniquePhaseError(""))
144144
end
145145
return new{T}(terms)
146146
end
@@ -168,7 +168,7 @@ end
168168
Represents a general function ``t_i \\mapsto f_d(\\dot{y}(t_i), y(t_i), t_i, x)``.
169169
170170
It is a sub-type of [`AbstractDynamicFunction`](@ref). All dynamic variables must be defined
171-
on the same phase, otherwise a [`MixedPhases`](@ref) error is thrown. Similar to
171+
on the same phase, otherwise a [`NonUniquePhaseError`](@ref) error is thrown. Similar to
172172
[`MOI.ScalarNonlinearFunction`](@extref MathOptInterface.ScalarNonlinearFunction),
173173
this function is represented by an expression tree, using the following fields:
174174

0 commit comments

Comments
 (0)