added phase attributes, MultiPhaseIntegral, and changed Derivative

JuDO-dev · Aug 31, 2024 · ddd4b31 · ddd4b31 · e-duar-do · Aug 31, 2024
1 parent c790e57
commit ddd4b31
Show file tree

Hide file tree

Showing 16 changed files with 222 additions and 109 deletions.
diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "DynOptInterface"
 uuid = "6c38235a-427b-4736-80fa-cf75909744ec"
 authors = ["Eduardo M. G. Vila <[email protected]> and contributors"]
-version = "0.1.0"
+version = "0.2.0"
 
 [deps]
 MathOptInterface = "b8f27783-ece8-5eb3-8dc8-9495eed66fee"

diff --git a/README.md b/README.md
@@ -3,4 +3,4 @@
 <!-- [![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://JuDO-dev.github.io/DynOptInterface.jl/stable/) -->
 [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://JuDO-dev.github.io/DynOptInterface.jl/dev/)
 [![Build Status](https://github.com/JuDO-dev/DynOptInterface.jl/actions/workflows/CI.yml/badge.svg?branch=dev)](https://github.com/JuDO-dev/DynOptInterface.jl/actions/workflows/CI.yml?query=branch%3Adev)
-<!-- [![Coverage](https://codecov.io/gh/JuDO-dev/DynOptInterface.jl/branch/dev/graph/badge.svg)](https://codecov.io/gh/JuDO-dev/DynOptInterface.jl) -->
+[![Coverage](https://codecov.io/gh/JuDO-dev/DynOptInterface.jl/branch/dev/graph/badge.svg)](https://codecov.io/gh/JuDO-dev/DynOptInterface.jl)
diff --git a/docs/make.jl b/docs/make.jl
@@ -7,6 +7,7 @@ DocMeta.setdocmeta!(DynOptInterface, :DocTestSetup, :(import DynOptInterface as
 
 const _PAGES = [
     "Home" => "index.md",
+    "Dynamic Optimization" => "dynamic_optimization.md",
     "API Reference" => [
         "Dynamic Functions" => [
             "reference/dynamic_functions/abstraction.md",

diff --git a/docs/src/assets/dynamic_variable.png b/docs/src/assets/dynamic_variable.png
diff --git a/docs/src/changelog.md b/docs/src/changelog.md
@@ -7,6 +7,12 @@ CurrentModule = DynOptInterface
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v0.2.0 (August 31, 2024)
+
+- Added phase attributes
+- Changed `DynamicVariableDerivative` to `Derivative`, also changing `ExplicitDifferentialFunction`
+- Added `MultiPhaseIntegral`
+
 ## v0.1.0 (July 26, 2024)
 
 - Initial release
diff --git a/docs/src/dynamic_optimization.md b/docs/src/dynamic_optimization.md
@@ -0,0 +1,63 @@
+```@meta
+CurrentModule = DynOptInterface
+```
+
+# Dynamic Optimization
+
+## Phases and Dynamic Variables
+
+Phases represent intervals $t \in [t_0, t_f]$ on which dynamic variables $t \mapsto \boldsymbol y(t)$ are defined.
+
+![dynamic variable](assets/dynamic_variable.png)
+
+## Problem Formulation
+
+MOI's [Function-in-Set form problem](@extref Standard-form-problem) is extended as follows.
+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
+
+```math
+\begin{align*}
+\begin{array}{rl}
+    \text{minimize} \quad &
+    m \big( \boldsymbol y(t_0), \boldsymbol y(t_f), t_0, t_f, x \big) +
+    \displaystyle{\sum_{i=1}^{n_p} \bigg[
+    \int_{t_0^{(i)}}^{t_f^{(i)}} \ell^{(i)} \big( \boldsymbol y^{(i)}(t), t, x \big) \textrm{d}t \bigg],}\\
+    %
+    \text{subject to} \quad &
+    \begin{aligned}
+        f(x) & \in \mathcal S,\\
+        %
+        d^{(i)}\big(\dot{\boldsymbol y}^{(i)}(t), \boldsymbol y^{(i)}(t), t, x) & \in \mathcal D^{(i)},
+        \quad \forall t \in [t_0^{(i)}, t_f^{(i)}],
+        \quad \forall i \in \{1, 2, ..., n_p\},\\
+        b(\boldsymbol y(t_0), \boldsymbol y(t_f), t_0, t_f, x) &\in \mathcal B,
+    \end{aligned}
+\end{array}
+\end{align*}
+```
+
+where:
+* ``f`` are [`MOI.AbstractScalarFunction`](@extref MathOptInterface.AbstractScalarFunction)s
+* ``\ell`` and ``d`` are [`AbstractDynamicFunction`](@ref)s
+* ``m`` and ``b`` are [`AbstractBoundaryFunction`](@ref)s
+
+
+## Dynamic Functions
+
+* [`PhaseIndex`](@ref)
+* [`DynamicVariableIndex`](@ref)
+* [`LinearDynamicFunction`](@ref)
+* [`PureQuadraticDynamicFunction`](@ref)
+* [`NonlinearDynamicFunction`](@ref)
+* [`Derivative`](@ref)
+* [`ExplicitDifferentialFunction`](@ref)
+
+## Boundary Functions
+
+* [`Initial`](@ref)
+* [`Final`](@ref)
+* [`Linkage`](@ref)
+* [`NonlinearBoundaryFunction`](@ref)
+* [`Integral`](@ref)
+* [`MultiPhaseIntegral`](@ref)
+* [`Bolza`](@ref)
diff --git a/docs/src/reference/boundary_functions.md b/docs/src/reference/boundary_functions.md
@@ -32,5 +32,6 @@ NonlinearBoundaryFunction
 ## Integrals
 ```@docs
 Integral
+MultiPhaseIntegral
 Bolza
 ```
diff --git a/docs/src/reference/dynamic_functions/derivatives.md b/docs/src/reference/dynamic_functions/derivatives.md
@@ -5,6 +5,6 @@ CurrentModule = DynOptInterface
 # Derivatives
 
 ```@docs
-DynamicVariableDerivative
+Derivative
 ExplicitDifferentialFunction
 ```
diff --git a/docs/src/reference/dynamic_functions/phases.md b/docs/src/reference/dynamic_functions/phases.md
@@ -14,15 +14,12 @@ MOI.is_valid(::MOI.ModelLike, ::PhaseIndex)
 InvalidPhaseIndex
 ```
 
-# Attributes
-
-The [`PhaseIndex`](@ref) object is compatible with the following attributes:
-* [`MOI.VariableName`](@extref MathOptInterface.VariableName) with value types `String`
-* [`MOI.VariablePrimal`](@extref MathOptInterface.VariablePrimal) with value types `Tuple{<:Real,<:Real}`
-* [`MOI.VariablePrimalStart`](@extref MathOptInterface.VariablePrimalStart) with value types `Tuple{<:Real,<:Real}`
+# Phase Attributes
 
 ```@docs
-MOI.supports(::MOI.ModelLike, ::MOI.AbstractVariableAttribute, ::Type{PhaseIndex})
-MOI.set(::MOI.ModelLike, ::MOI.AbstractVariableAttribute, ::PhaseIndex, ::Any)
-MOI.get(::MOI.ModelLike, ::MOI.AbstractVariableAttribute, ::PhaseIndex)
+AbstractPhaseAttribute
+MOI.supports(::MOI.ModelLike, ::AbstractPhaseAttribute, ::Type{PhaseIndex})
+MOI.set(::MOI.ModelLike, ::AbstractPhaseAttribute, ::PhaseIndex, ::Any)
+MOI.get(::MOI.ModelLike, ::AbstractPhaseAttribute, ::PhaseIndex)
+PhaseName
 ```
diff --git a/src/boundary_functions.jl b/src/boundary_functions.jl
@@ -16,16 +16,16 @@ abstract type AbstractBoundaryFunction <: MOI.AbstractScalarFunction end
 ## Initial & Final
 
 """
-    Initial{DF}(dyn_fun::DF) where {DF<:AbstractDynamicFunction}
+    Initial{DF}(evaluand::DF) where {DF<:AbstractDynamicFunction}
 
 Represents the evaluation of an [`AbstractDynamicFunction`](@ref) at the initial 
 point of its phase.
 
 It is a sub-type of [`AbstractBoundaryFunction`](@ref). The dynamic function is stored
-in the `dyn_fun` field.
+in the `evaluand` field.
 """
 struct Initial{DF<:AbstractDynamicFunction} <: AbstractBoundaryFunction
-    dyn_fun::DF
+    evaluand::DF
 end
 
 function MOI.Utilities._to_string(
@@ -35,22 +35,22 @@ function MOI.Utilities._to_string(
 )
     return string(
         "Initial(",
-        MOI.Utilities._to_string(options, model, initial.dyn_fun),
+        MOI.Utilities._to_string(options, model, initial.evaluand),
         ")",
     )
 end
 
 """
-    Final{DF}(dyn_fun::DF) where {DF<:AbstractDynamicFunction}
+    Final{DF}(evaluand::DF) where {DF<:AbstractDynamicFunction}
 
 Represents the evaluation of an [`AbstractDynamicFunction`](@ref) at the final 
 point of its phase.
 
 It is a sub-type of [`AbstractBoundaryFunction`](@ref). The dynamic function is stored
-in the `dyn_fun` field.
+in the `evaluand` field.
 """
 struct Final{DF<:AbstractDynamicFunction} <: AbstractBoundaryFunction
-    dyn_fun::DF
+    evaluand::DF
 end
 
 function MOI.Utilities._to_string(
@@ -60,7 +60,7 @@ function MOI.Utilities._to_string(
 )
     return string(
         "Final(",
-        MOI.Utilities._to_string(options, model, final.dyn_fun),
+        MOI.Utilities._to_string(options, model, final.evaluand),
         ")",
     )
 end
@@ -69,18 +69,18 @@ end
 
 """
     Linkage{DF}(
-        final::Final{DF},
-        initial::Initial{DF},
+        final_evaluand::DF,
+        initial_evaluand::DF,
     ) where {DF<:AbstractDynamicFunction}
 
 Represents the expression ``f_f(y(t^f), t^f) - f_0(y(t^0), t^0)``.
 
 It is a sub-type of [`AbstractBoundaryFunction`](@ref). The final function is stored in the
-`final` field and the initial function is stored in the `initial` field.
+`final_evaluand` field and the initial function is stored in the `initial_evaluand` field.
 """
 struct Linkage{DF<:AbstractDynamicFunction} <: AbstractBoundaryFunction
-    final::Final{DF}
-    initial::Initial{DF}
+    final_evaluand::DF
+    initial_evaluand::DF
 end
 
 function MOI.Utilities._to_string(
@@ -89,9 +89,11 @@ function MOI.Utilities._to_string(
     linkage::Linkage,
 )
     return string(
-        MOI.Utilities._to_string(options, model, linkage.final),
-        " - ",
+        "Final(",
+        MOI.Utilities._to_string(options, model, linkage.final_evaluand),
+        ") - Initial(",
         MOI.Utilities._to_string(options, model, linkage.initial),
+        ")",
     )
 end
 
@@ -149,14 +151,14 @@ end
 ## Integrals
 
 """
-    Integral{DF}(dyn_fun::AbstractDynamicFunction) where {DF<:AbstractDynamicFunction}
+    Integral{DF}(integrand::DF) where {DF<:AbstractDynamicFunction}
 
 Represents the integral ``\\int_{t_i^o}^{t_i^f} f_d(\\dot{y}(t_i), y(t_i), t_i, x) \\mathrm{d}t_i``.
 
-It is a sub-type of [`AbstractBoundaryFunction`](@ref). The integrand is stored in the `dyn_fun` field.
+It is a sub-type of [`AbstractBoundaryFunction`](@ref). The integrand is stored in the `integrand` field.
 """
 struct Integral{DF<:AbstractDynamicFunction} <: AbstractBoundaryFunction
-    dyn_fun::DF
+    integrand::DF
 end
 
 function MOI.Utilities._to_string(
@@ -166,34 +168,75 @@ function MOI.Utilities._to_string(
 )
     return string(
         "∫(",
-        MOI.Utilities._to_string(options, model, integral.dyn_fun),
+        MOI.Utilities._to_string(options, model, integral.integrand),
         ")d(",
         MOI.Utilities._to_string(options, model, phase_index(integral)),
         ")",
     )
 end
 
-phase_index(integral::Integral) = phase_index(integral.dyn_fun)
+phase_index(integral::Integral) = phase_index(integral.integrand)
+
+"""
+    MultiPhaseIntegral{DF}(
+        integrands::Vector{DF},
+    ) where {DF<:AbstractDynamicFunction}
+
+Represents the sum of integrals
+``\\sum_i \\big[ \\int_{t_i^o}^{t_i^f} f_d(\\dot{y}(t_i), y(t_i), t_i, x) \\mathrm{d}t_i \\big]``.
+
+It is a sub-type of [`AbstractBoundaryFunction`](@ref). The vector of integrands is
+stored in the `integrands` field.
+"""
+struct MultiPhaseIntegral{DF<:AbstractDynamicFunction} <: AbstractBoundaryFunction
+    integrands::Vector{DF}
+end 
+
+function MOI.Utilities._to_string(
+    options::MOI.Utilities._PrintOptions,
+    model::MOI.ModelLike,
+    multi_phase_integral::MultiPhaseIntegral,
+)
+    integrands = multi_phase_integral.integrands
+
+    s = string(
+        "∫(",
+        MOI.Utilities._to_string(options, model, integrands[1]),
+        ")d(",
+        MOI.Utilities._to_string(options, model, phase_index(integrands[1])),
+        ")",
+    )
+
+    for i in 2:length(integrands)
+        s *= string(
+            " + ∫(",
+            MOI.Utilities._to_string(options, model, integrands[i]),
+            ")d(",
+            MOI.Utilities._to_string(options, model, phase_index(integrands[i])),
+            ")",
+        )
+    end
+    return s
+end
 
 """
-    Bolza{BF,DF}(
+    Bolza{BF,IF}(
         bou_fun::BF,
-        integral::Integral{DF},
-    ) where {BF<:AbstractBoundaryFunction,DF<:AbstractDynamicFunction}
+        integral::IF,
+    ) where {BF<:AbstractBoundaryFunction,IF<:Union{Integral,MultiPhaseIntegral}}
 
 ```math
 f_b(y_0, y_f, t_0, t_f, x) + \\int_{t_i^o}^{t_i^f} f_d(\\dot{y}(t_i), y(t_i), t_i, x) \\mathrm{d}t_i
 ```
-Represents the sum of an [`AbstractBoundaryFunction`](@ref) with the integral of
-an [`AbstractDynamicFunction`](@ref).
+Represents the sum of an [`AbstractBoundaryFunction`](@ref) with either an [`Integral`](@ref) or a
+[`MultiPhaseIntegral`](@ref).
 
 It is a sub-type of [`AbstractBoundaryFunction`](@ref). The boundary function is stored in the `bou_fun`
 field and the integral is stored in the `integral` field.
 """
-struct Bolza{BF<:AbstractBoundaryFunction,DF<:AbstractDynamicFunction} <:
-       AbstractBoundaryFunction
+struct Bolza{BF<:AbstractBoundaryFunction,IF<:Union{Integral,MultiPhaseIntegral}} <: AbstractBoundaryFunction
     bou_fun::BF
-    integral::Integral{DF}
+    integral::IF
 end
 
 function MOI.Utilities._to_string(

diff --git a/src/dynamic_functions/abstraction.jl b/src/dynamic_functions/abstraction.jl
@@ -6,16 +6,16 @@ Abstract super-type for dynamic functions.
 That is, expressions that may contain:
 * ``t_i`` -- a [`PhaseIndex`](@ref)
 * ``y_j(\\cdot)`` -- a [`DynamicVariableIndex`](@ref)
-* ``\\dot{y}_j(\\cdot)`` -- a [`DynamicVariableDerivative`](@ref)
-Sub-types of [`AbstractDynamicFunction`](@ref) must not contain different 
-[`PhaseIndex`](@ref)s.
+
+Sub-types of [`AbstractDynamicFunction`](@ref) must be defined on a single 
+[`PhaseIndex`](@ref).
 """
 abstract type AbstractDynamicFunction <: MOI.AbstractScalarFunction end
 
 """
     phase_index(dyn_fun::AbstractDynamicFunction)::PhaseIndex
 
-Returns the [`PhaseIndex`](@ref) ``t_i`` of the dynamic function `dyn_fun`.
+Returns the [`PhaseIndex`](@ref) ``t_i`` of a dynamic function `dyn_fun`.
 """
 function phase_index(::AbstractDynamicFunction)::PhaseIndex end