Adding docs comments

Author: johnaoga

docs/src/examples/solvers/Unicycle robot copy.jl

@@ -1,34 +1,30 @@
 using Test     #src
-# # Example: Path planning problem solved by [Uniform grid abstraction](https://github.com/dionysos-dev/Dionysos.jl/blob/master/docs/src/manual/manual.md#solvers).
+# # Example: Unicycle Robot solved by [Uniform grid abstraction](https://github.com/dionysos-dev/Dionysos.jl/blob/master/docs/src/manual/manual.md#solvers).
 #
-#md # [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/generated/Path planning.ipynb)
-#md # [![nbviewer](https://img.shields.io/badge/show-nbviewer-579ACA.svg)](@__NBVIEWER_ROOT_URL__/generated/Path planning.ipynb)
-#
-# This example was borrowed from [1, IX. Examples, A] whose dynamics comes from the model given in [2, Ch. 2.4].
-# This is a **reachability problem** for a **continuous system**.
+# This example was adapted from the numerical experiments in [1, Sec. 5] from Symbolically guided Model Predictive Control (SgMPC)  [paper](https://doi.org/10.1016/j.ifacol.2022.09.039)..
+# This is a **control problem** for a **discrete-time nonlinear system**.
 #
 # Let us consider the 3-dimensional state space control system of the form
 # ```math
-# \dot{x} = f(x, u)
+# x_{t+1} = f(x_t, u_t)
 # ```
-# with $f: \mathbb{R}^3 × U ↦ \mathbb{R}^3$ given by
+# with $f: \mathbb{R}^3 × \mathbb{R}^2 \to \mathbb{R}^3$ given by
 # ```math
-# f(x,(u_1,u_2)) = \begin{bmatrix} u_1 \cos(α+x_3)\cos(α)^{-1} \\ u_1 \sin(α+x_3)\cos(α)^{-1} \\ u_1 \tan(u_2)  \end{bmatrix}
+# f(x, (u_1, u_2)) = \begin{bmatrix} x_1 + u_1 \cos(x_3) \\ x_2 + u_1 \sin(x_3) \\ x_3 + u_2 \ (\text{mod} \ 2\pi) \end{bmatrix}
 # ```
-# and with $U = [−1, 1] \times [−1, 1]$ and $α = \arctan(\tan(u_2)/2)$. Here, $(x_1, x_2)$ is the position and $x_3$ is the
-# orientation of the vehicle in the 2-dimensional plane. The control inputs $u_1$ and $u_2$ are the rear
-# wheel velocity and the steering angle.
-# The control objective is to drive the vehicle which is situated in a maze made of obstacles from an initial position to a target position.
-#
-#
-# In order to study the concrete system and its symbolic abstraction in a unified framework, we will solve the problem
-# for the sampled system with a sampling time $\tau$.
-# For the construction of the relations in the abstraction, it is necessary to over-approximate attainable sets of
-# a particular cell. In this example, we consider the used of a growth bound function  [1, VIII.2, VIII.5] which is one of the possible methods to over-approximate
-# attainable sets of a particular cell based on the state reach by its center.
+# and with state and control constraints given by:
+# ```math
+# X = \left\{ (x_1, x_2)^T \in \mathbb{R}^2 \ | \ x_1^2 - x_2^2 \leq 4, \ 4x_2^2 - x_1^2 \leq 16 \right\}
+# ```
+# ```math
+# U = [0.2, 2] \times [-1, 1]
+# ```
+# Here, $(x_1, x_2)$ represents the 2D Cartesian coordinates and $x_3$ is the angular orientation of a mobile cart.
+# The control inputs $u_1$ and $u_2$ are the linear and angular velocities.
+# The control objective is to drive the mobile cart to a desired reference position $x_r$.
 #
-# For this reachability problem, the abstraction controller is built by solving a fixed-point equation which consists in computing the pre-image
-# of the target set.
+# Considering this as a reachability problem, we will use it to showcase the capabilities of the Uniform grid abstraction solving discrete-time problem in Dionysos.
+# The nonlinear constraints are handled as obstacles in the state-space.
 
 # First, let us import [StaticArrays](https://github.com/JuliaArrays/StaticArrays.jl) and [Plots](https://github.com/JuliaPlots/Plots.jl).
 using StaticArrays, Plots, Revise
@@ -40,16 +36,15 @@ using Dionysos, JuMP
 # We first create a JuMP model:
 model = Model(Dionysos.Optimizer)
 
-# Define the prediction horizon
-N = 5
+# Define the discretization step
 discretization_step = 0.1
 
-# Define the state variables: x1(t), x2(t), x3(t) for t = 1, ..., N
+# Define the state variables: x1(t), x2(t), x3(t) without specifying the start value since here it's a set. We will specify the start later using constraints.
 x_low = [-3.5, -2.6, -pi]
 x_upp = -x_low
 @variable(model, x_low[i] <= x[i = 1:3] <= x_upp[i])
 
-# Define the control variables: u1(t), u2(t) for t = 1, ..., N-1
+# Define the control variables: u1(t), u2(t)
 @variable(model, -1 <= u[1:2] <= 1)
 
 # Define the dynamics
@@ -58,28 +53,18 @@ x_upp = -x_low
 @constraint(model, ∂(x[3]) == x[3] + u[2])
 
 # Define the initial and target sets
-#x_initial = [0.0, 0.0, 0.0]  # Initial state
 x_initial = [1.0, -1.7, 0.0]
-#x_target = [0.5, 0.5, -pi]  # Target state
 x_target = [sqrt(32)/3, sqrt(20)/3, -pi]
 
-#@constraint(model, start(x[1]) in MOI.Interval(-0.2, 0.2))
-#@constraint(model, start(x[2]) in MOI.Interval(-0.2, 0.2))
-#@constraint(model, start(x[3]) in MOI.Interval(-0.2, 0.2))
-
 @constraint(model, start(x[1]) in MOI.Interval(0.8, 1.2))
 @constraint(model, start(x[2]) in MOI.Interval(-1.9, -1.5))
 @constraint(model, start(x[3]) in MOI.Interval(-0.2, 0.2))
 
-#@constraint(model, final(x[1]) in MOI.Interval(0.3, 0.7))
-#@constraint(model, final(x[2]) in MOI.Interval(0.3, 0.7))
-#@constraint(model, final(x[3]) in MOI.Interval(-3.14, 3.14))
-
 @constraint(model, final(x[1]) in MOI.Interval(1.78, 1.98))
 @constraint(model, final(x[2]) in MOI.Interval(1.39, 1.59))
 @constraint(model, final(x[3]) in MOI.Interval(-3.14, 3.14))
 
-# Obstacle boundaries (provided)
+# Obstacle boundaries computed using the function `get_obstacles` below
 function extract_rectangles(matrix)
     if isempty(matrix)
         return []
@@ -135,6 +120,7 @@ function get_obstacles(lb, ub, h)
 end
 
 obstacles = get_obstacles(x_low, x_upp, discretization_step)
+
 # Function to add rectangular obstacle avoidance constraints
 
 for obstacle in obstacles
@@ -143,7 +129,10 @@ end
 
 # ### Definition of the abstraction
 
-# Definition of the grid of the state-space on which the abstraction is based (origin `x0` and state-space discretization `h`):
+# First we need to set the mode of the abstraction to `DIONYSOS.Optim.Abstraction.UniformGridAbstraction.DSICRETE_TIME`:
+set_attribute(model, "approx_mode", Dionysos.Optim.Abstraction.UniformGridAbstraction.DSICRETE_TIME)
+
+# We define the system map $f$:
 function sys_map(x, u, _)
     return StaticArrays.SVector{3}(
             x[1] + u[1] * cos(x[3]),
@@ -153,12 +142,14 @@ function sys_map(x, u, _)
 end
 set_attribute(model, "system_map", sys_map)
 
+# We define the growth bound function of $f$:
 function growth_bound(r, u, _)
     β = u[1] * r[3]
     return StaticArrays.SVector{3}(β, β, 0.0)
 end
 set_attribute(model, "growthbound_map", growth_bound)
 
+# We define the invariant system map:
 function sys_inv(x, u, _)
     return StaticArrays.SVector{3}(
         x[1] - u[1] * cos((x[3] - u[2]) % (2 * π)),
@@ -168,8 +159,10 @@ function sys_inv(x, u, _)
 end
 set_attribute(model, "sys_inv_map", sys_inv)
 
+# We define the time step of the system:
 set_attribute(model, "time_step", 1.0)
 
+# Definition of the grid of the state-space on which the abstraction is based (origin `x0` and state-space discretization `h`):
 x0 = SVector(0.0, 0.0, 0.0);
 h = SVector(0.1, 0.1, 0.2);
 set_attribute(model, "state_grid", Dionysos.Domain.GridFree(x0, h))
@@ -179,7 +172,6 @@ u0 = SVector(1.1, 0.0);
 h = SVector(0.3, 0.3);
 set_attribute(model, "input_grid", Dionysos.Domain.GridFree(u0, h))
 
-set_attribute(model, "approx_mode", Dionysos.Optim.Abstraction.UniformGridAbstraction.DSICRETE_TIME)
 optimize!(model)
 
 # Get the results
@@ -241,5 +233,4 @@ plot!(
 plot!(control_trajectory; ms = 0.5)
 
 # ### References
-# 1. G. Reissig, A. Weber and M. Rungger, "Feedback Refinement Relations for the Synthesis of Symbolic Controllers," in IEEE Transactions on Automatic Control, vol. 62, no. 4, pp. 1781-1796.
-# 2. K. J. Aström and R. M. Murray, Feedback systems. Princeton University Press, Princeton, NJ, 2008.
+# 1. Z. Azaki, A. Girard and S. Olaru, "Predictive and Symbolic Control: Performance and Safety for Non-linear Systems," in IFAC-PapersOnLine, 2022, vol. 55, no 16, pp. 290-295..