Merge pull request #315 from dionysos-dev/vd/Documentation

Vd/documentation
dionysos-dev · Oct 23, 2023 · 6eac99b · 6eac99b
2 parents f8347ad + 92b38b2
commit 6eac99b
Show file tree

Hide file tree

Showing 29 changed files with 136 additions and 1,592 deletions.
diff --git a/BipedRobot/ZMPBipedRobot/docs/2. Optimisation Process/objectives_values_Fs50.txt b/BipedRobot/ZMPBipedRobot/docs/2. Optimisation Process/objectives_values_Fs50.txt
diff --git a/BipedRobot/ZMPBipedRobot/docs/2. Optimisation Process/solutions_Fs50.txt b/BipedRobot/ZMPBipedRobot/docs/2. Optimisation Process/solutions_Fs50.txt
diff --git a/Project.toml b/Project.toml
@@ -1,6 +1,6 @@
 name = "Dionysos"
 uuid = "d92c97cf-b87d-42c1-a9c0-25df00b4d958"
-authors = ["Raphael Jungers <raphael.jungers@uclouvain.be>", "Antoine Aspeel <antoine.aspeel@uclouvain.be>", "Guillaume Berger <guillaume.berger@uclouvain.be>", "Julien Calbert <julien.calbert@uclouvain.be>", "Mahsa Farjadnia <mahsa.farjadnia@uclouvain.be>", "Benoît Legat <benoit.legat@uclouvain.be>", "Zheming Wang <zheming.wang@uclouvain.be>", "Lucas N. Egidio <lucas.egidio@uclouvain.be>", "Adrien Banse <adrien.banse@uclouvain.be>", "Somya Singh <somya.singh@uclouvain.be>"]
+authors = ["Raphael Jungers <raphael.jungers@uclouvain.be>", "Antoine Aspeel <antoine.aspeel@uclouvain.be>", "Guillaume Berger <guillaume.berger@uclouvain.be>", "Julien Calbert <julien.calbert@uclouvain.be>", "Virginie Debauche <virginie.debauche@uclouvain.be>", "Mahsa Farjadnia <mahsa.farjadnia@uclouvain.be>", "Benoît Legat <benoit.legat@uclouvain.be>", "Zheming Wang <zheming.wang@uclouvain.be>", "Lucas N. Egidio <lucas.egidio@uclouvain.be>", "Adrien Banse <adrien.banse@uclouvain.be>", "Somya Singh <somya.singh@uclouvain.be>"]
 version = "0.0.1"
 
 [deps]

diff --git a/docs/src/reference/Optim.md b/docs/src/reference/Optim.md
@@ -1,14 +1,14 @@
 # Optim 
 
-This folder contains all the different solvers that can be used.
+This folder contains all the different (abstraction-based or not) solvers that can be used. Note that all the solvers are defined using the MathOptInterface framework: for each solver, we define a subtype of  [`AbstractOptimizer`](https://jump.dev/MathOptInterface.jl/stable/reference/models/#MathOptInterface.AbstractOptimizer) and implement the [`Optimize!`](https://jump.dev/MathOptInterface.jl/stable/reference/models/#MathOptInterface.optimize!) function.
 
 ## Abstraction-based solvers
 ```@docs
-Dionysos.Optim.Abstraction.LazyAbstraction.Optimizer
+Dionysos.Optim.Abstraction.NaiveAbstraction.Optimizer
 Dionysos.Optim.Abstraction.EllipsoidsAbstraction.Optimizer
 Dionysos.Optim.Abstraction.HierarchicalAbstraction.Optimizer
+Dionysos.Optim.Abstraction.LazyAbstraction.Optimizer
 Dionysos.Optim.Abstraction.LazyEllipsoidsAbstraction.Optimizer
-Dionysos.Optim.Abstraction.NaiveAbstraction.Optimizer
 ```
 
 ## Other solvers

diff --git a/docs/src/reference/Problem.md b/docs/src/reference/Problem.md
@@ -1,9 +1,14 @@
 # Problem 
 
-This folder contains structures that are used to encode which kind of problem you want to solve.
+This folder contains structures that are used to encode which kind of problem you want to solve. Each problem is encoded as a ProblemType.
 
 ```@docs
 Dionysos.Problem.ProblemType
+```
+
+So far, two types of problems have been considered: the reach-avoid optimal control problems and the safety control problems.
+
+```@docs
 Dionysos.Problem.OptimalControlProblem
 Dionysos.Problem.SafetyProblem
 ```
diff --git a/docs/src/reference/Symbolic.md b/docs/src/reference/Symbolic.md
@@ -1,6 +1,10 @@
 # Symbolic 
 
-This folder contains different methods to build an abstraction.
+This folder contains the data structures needed to encode the different abstractions.
+
+```@docs
+Dionysos.Symbolic.SymbolicModel
+```
 
 ```@docs
 Dionysos.Symbolic.SymbolicModelList

diff --git a/docs/src/reference/System.md b/docs/src/reference/System.md
@@ -3,23 +3,36 @@
 This folder contains different ways to define systems, for instance to encode a controller.
 
 ## Control system
+
+Each control system should be implemented as a ControlSystem.
+
 ```@docs
+Dionysos.System.ControlSystem
+```
+
+So far, we have implemented a few examples of control systems: 
+
+```@docs
+Dionysos.System.SimpleSystem
 Dionysos.System.ControlSystemGrowth
 Dionysos.System.ControlSystemLinearized
-Dionysos.System.SimpleSystem
 Dionysos.System.EllipsoidalAffineApproximatedSystem
-Dionysos.System.AffineApproximationDiscreteSystem
-Dionysos.System.SymbolicSystem
 ```
 
 ## Controller 
+So far, the abstraction-based methods that we use define either piecewise-constant or piecewise-affine controllers.
+
 ```@docs
 Dionysos.System.ConstantController
 Dionysos.System.AffineController
 ```
 
-## SHOULD BE REMOVED 
+## Trajectories 
 ```@docs
 Dionysos.System.DiscreteTrajectory
 Dionysos.System.ContinuousTrajectory
+Dionysos.System.HybridTrajectory
+Dionysos.System.Trajectory
+Dionysos.System.Control_trajectory
+Dionysos.System.Cost_control_trajectory
 ```
diff --git a/docs/src/reference/Utils.md b/docs/src/reference/Utils.md
@@ -2,11 +2,6 @@
 
 This folder contains all the auxiliary functions needed.
 
-## Ellipsoids 
-
-```@docs
-```
-
 ## Functions 
 
 ```@docs

diff --git a/src/domain/continuous_domain.jl b/src/domain/continuous_domain.jl
@@ -3,7 +3,7 @@ abstract type ContinuousDomain{N, T} <: DomainType{N, T} end
 """
     ContinuousUnboundedDomain{N,T}
 
-Struct for a basic unbounded continuous domain
+Struct for a basic unbounded continuous domain.
 """
 struct ContinuousUnboundedDomain{N, T} <: ContinuousDomain{N, T}
     orig::SVector{N, T}
@@ -12,7 +12,7 @@ end
 """
     ContinuousBoundedDomain{N,T,B}
 
-Struct for a basic bounded continuous domain
+Struct for a basic bounded continuous domain.
 """
 struct ContinuousBoundedDomain{N, T, B} <: ContinuousDomain{N, T}
     orig::SVector{N, T}
@@ -22,7 +22,7 @@ end
 """
     ContinuousBoundedEllipsoidDomain{N,T,S<:Grid{N,T}}
 
-Struct for a basic bounded continuous domain formed by a finite number of ellipsoids
+Struct for a basic bounded continuous domain formed by a finite number of ellipsoids.
 """
 struct ContinuousBoundedEllipsoidDomain{N, T, B, E} <: ContinuousDomain{N, T}
     orig::SVector{N, T}

diff --git a/src/domain/custom_domain.jl b/src/domain/custom_domain.jl
@@ -1,7 +1,7 @@
 """
     CustomList{N,T} <: DomainType{N,T}
 
-Struct for a custom generic domain
+Struct for a custom generic domain.
 """
 
 struct CustomList{N, T} <: DomainType{N, T}

diff --git a/src/domain/domain_list.jl b/src/domain/domain_list.jl
@@ -7,7 +7,7 @@ end
 """
     DomainList{N,T,S<:Grid{N,T}}
 
-Struct for a basic domain based on a `Grid`
+Struct for a basic domain based on a `Grid`.
 """
 struct DomainList{N, T, S <: Grid{N, T}} <: DomainType{N, T}
     grid::S
@@ -17,7 +17,7 @@ end
 """
     DomainList(grid::S) where {N,S<:Grid{N}}
 
-Return a new DomainList
+Return a new `DomainList`.
 """
 function DomainList(grid::S) where {N, S <: Grid{N}}
     return DomainList(grid, Set{NTuple{N, Int}}())

diff --git a/src/domain/general_domain.jl b/src/domain/general_domain.jl
@@ -3,7 +3,7 @@ using StaticArrays, Plots
 """
     RectangularObstacles{VT} <: AbstractSet{VT}
 
-Struct for a rectangular domain with rectangular obstacles
+Struct for a rectangular domain with rectangular obstacles.
 """
 struct RectangularObstacles{VT} <: AbstractSet{VT}
     X::UT.HyperRectangle{VT}
@@ -36,7 +36,7 @@ _fit_grid(elems::Set, grid, nx, fit) = elems
 """
     GeneralDomainList{N,E<:AbstractSet{NTuple{N,Int}},T,S<:Grid{N,T},F} <: DomainType{N,T}
 
-Struct for a rectangular domain with rectangular obstacles
+Struct for a rectangular domain with rectangular obstacles.
 """
 struct GeneralDomainList{N, E <: AbstractSet{NTuple{N, Int}}, T, S <: Grid{N, T}, F} <:
        DomainType{N, T}

diff --git a/src/domain/grid.jl b/src/domain/grid.jl
@@ -113,7 +113,7 @@ end
     GridEllipsoidalRectangular{N,T} <: Grid{N,T}
 
 Uniform grid on rectangular space `rect`, centered at `orig` and with steps set by the vector `h`.
-Cells are (possibly overlapping) ellipsoids defined at each grid point `c` as `(x-c)'P(x-c) ≤ 1`
+Cells are (possibly overlapping) ellipsoids defined at each grid point `c` as `(x-c)'P(x-c) ≤ 1`.
 """
 struct GridEllipsoidalRectangular{N, T} <: Grid{N, T}
     orig::SVector{N, T}

diff --git a/src/optim/abstraction/ellipsoids_abstraction.jl b/src/optim/abstraction/ellipsoids_abstraction.jl
@@ -16,7 +16,7 @@ const PR = DI.Problem
 """
     Optimizer{T} <: MOI.AbstractOptimizer
 
-Ellispoids abtraction solver
+Abstraction-based solver for which the domain is covered with ellipsoidal cells, independently of the control task.
 """
 mutable struct Optimizer{T} <: MOI.AbstractOptimizer
     concrete_problem::Union{Nothing, PR.OptimalControlProblem}

diff --git a/src/optim/abstraction/hierarchical_abstraction.jl b/src/optim/abstraction/hierarchical_abstraction.jl
@@ -19,7 +19,7 @@ using ..LazyAbstraction
 """
     Optimizer{T} <: MOI.AbstractOptimizer
     
-Hierarchical abstraction solver
+Abstraction-based solver for which the domain is initially partioned into coarse hyper-rectangular cells, which are iteratively locally smartly refined with respect to the control task.
 """
 mutable struct Optimizer{T} <: MOI.AbstractOptimizer
     concrete_system::Union{Nothing, Any}

diff --git a/src/optim/abstraction/lazy_abstraction.jl b/src/optim/abstraction/lazy_abstraction.jl
@@ -16,7 +16,7 @@ const PR = DI.Problem
 """
     Optimizer{T} <: MOI.AbstractOptimizer
 
-Solver from Lazy Abstraction
+Abstraction-based solver for which the hyper-rectangular abstraction and the controller are co-designed to reduce the computation cost of the abstraction.
 """
 mutable struct Optimizer{T} <: MOI.AbstractOptimizer
     concrete_system::Union{Nothing, Any}

diff --git a/src/optim/abstraction/lazy_ellipsoids_abstraction.jl b/src/optim/abstraction/lazy_ellipsoids_abstraction.jl
@@ -22,7 +22,7 @@ global NI = nothing
 """
     Optimizer{T} <: MOI.AbstractOptimizer
 
-Lazy ellipsoids abstraction solver
+Abstraction-based solver using the lazy abstraction method with ellipsoidal cells.
 """
 mutable struct Optimizer{T} <: MOI.AbstractOptimizer
     concrete_problem::Union{Nothing, PR.OptimalControlProblem}

diff --git a/src/optim/abstraction/naive_abstraction.jl b/src/optim/abstraction/naive_abstraction.jl
@@ -15,7 +15,7 @@ using JuMP
 """
     Optimizer{T} <: MOI.AbstractOptimizer
 
-Naive abstraction solver
+Solver based on the classical abstraction method (used for instance in SCOTS) for which the whole domain is partioned into hyper-rectangular cells, independently of the control task.
 """
 mutable struct Optimizer{T} <: MOI.AbstractOptimizer
     concrete_problem::Union{Nothing, PR.ProblemType}

diff --git a/src/optim/bemporad_morari.jl b/src/optim/bemporad_morari.jl
@@ -20,7 +20,7 @@ using FillArrays, MathematicalSystems, HybridSystems, JuMP, SemialgebraicSets, P
 """
     Optimizer{T} <: MOI.AbstractOptimizer
 
-Bemporad Morari solver
+Bemporad Morari solver: Optimal control of hybrid systems via a predictive control scheme using mixed integer quadratic programming (MIQP) online optimization procedures.
 """
 mutable struct Optimizer{T} <: MOI.AbstractOptimizer
     continuous_solver::Any

diff --git a/src/optim/branch_and_bound.jl b/src/optim/branch_and_bound.jl
@@ -16,7 +16,7 @@ using HybridSystems
 """
     Optimizer{T} <: MOI.AbstractOptimizer
 
-Branch and bound solver
+Branch and bound solver: Optimal control of hybrid systems via a predictive control scheme combining a branch and bound algorithm that can refine Q-functions using Lagrangian duality.
 """
 mutable struct Optimizer{T} <: MOI.AbstractOptimizer
     continuous_solver::Any

diff --git a/src/problem/problems.jl b/src/problem/problems.jl
@@ -13,12 +13,12 @@ The structure
     OptimalControlProblem{S, XI, XT, XC, TC, T}
 
 encodes an optimal control problem where 
-`S` is the system,
-`XI` is the initial set, 
-`XT` is the target set,
-`XC` is the state cost,
-`TC` is transistion cost and
-`T` is the number of allowed time steps
+- `S` is the system,
+- `XI` is the initial set, 
+- `XT` is the target set,
+- `XC` is the state cost,
+- `TC` is transistion cost and
+- `T` is the number of allowed time steps
 """
 struct OptimalControlProblem{S, XI, XT, XC, TC, T <: Real} <: ProblemType
     system::S
@@ -35,10 +35,10 @@ The structure
     SafetyProblem{S, XI, XS, T}
 
 encodes a safety problem where
-`S` is the system,
-`XI` is the initial set, 
-`XS` is the safe set and
-`T` is the number of allowed time steps
+- `S` is the system,
+- `XI` is the initial set, 
+- `XS` is the safe set and
+- `T` is the number of allowed time steps
 """
 struct SafetyProblem{S, XI, XS, T <: Real} <: ProblemType
     system::S

diff --git a/src/symbolic/lazy_symbolic.jl b/src/symbolic/lazy_symbolic.jl
@@ -1,7 +1,7 @@
 """
     LazySymbolicModel{N, M, S1 <: DO.DomainType{N}, S2 <: DO.DomainType{M}, A} <: SymbolicModel{N, M}
 
-TO ADD
+is one implementation of the `SymbolicModel` type for the lazy abstraction-based methods, i.e. when a subset of the domain is partitioned/covered.
 """
 mutable struct LazySymbolicModel{N, M, S1 <: DO.DomainType{N}, S2 <: DO.DomainType{M}, A} <:
                SymbolicModel{N, M}

diff --git a/src/symbolic/symbolicmodel.jl b/src/symbolic/symbolicmodel.jl
@@ -1,11 +1,16 @@
 using Plots, Colors
 
+"""
+    SymbolicModel{N, M}
+
+is the abtract type which defines a symbolic model.
+"""
 abstract type SymbolicModel{N, M} end
 
 """
     SymbolicModelList{N, M, S1 <: DO.DomainType{N}, S2 <: DO.DomainType{M}, A} <: SymbolicModel{N, M}
     
-TO ADD
+is one implementation of the `SymbolicModel` type for classical abstraction-based methods, i.e. when the whole domain is partitioned/covered.
 """
 mutable struct SymbolicModelList{N, M, S1 <: DO.DomainType{N}, S2 <: DO.DomainType{M}, A} <:
                SymbolicModel{N, M}

diff --git a/src/system/controller.jl b/src/system/controller.jl
@@ -8,7 +8,7 @@ end
 """
     ConstantController{T, VT}
 
-encodes a constant state-dependent controller of the κ(x) = c
+encodes a constant state-dependent controller of the κ(x) = c.
 """
 struct ConstantController{T <: Real, VT <: AbstractVector{T}} <: Controller
     c::VT
@@ -24,7 +24,7 @@ end
 """
     AffineController{T, MT, VT1, VT2}
 
-encodes an affine state-dependent controller of the κ(x) = K*(x-c)+ℓ
+encodes an affine state-dependent controller of the κ(x) = K*(x-c)+ℓ.
 """
 struct AffineController{
     T <: Real,