add docstrings

Author: baggepinnen

examples/hinf_example_tank.jl

@@ -36,23 +36,14 @@ D = zeros(2,2)
 G = ss(A,B,C,D);
 
 # Sensitivity weight function
-WSelement = 100*tf([1,1],[1000,1])
-WS = [WSelement 0; 0 WSelement]
-iWSelement = 1/WSelement
-iWS = [iWSelement 0; 0 iWSelement]
+WS = 100*tf([1,1],[1000,1]) .* I(2)
 
 # Output sensitivity weight function
-WUelement = 5*tf([1,1],[0.1,1])
-WUelement = ss(0.01)
-WU = [WUelement 0; 0 WUelement]
-iWUelement = 1/WUelement
-iWU = [iWUelement 0; 0 iWUelement]
+# WUelement = 5*tf([1,1],[0.1,1])
+WU = tf(0.01) .* I(2)
 
 # Complementary sensitivity weight function
-WTelement = tf([10,0.1],[1,1])
-WT  = [WTelement 0; 0 WTelement]
-iWTelement = 1/WTelement
-iWT = [iWTelement 0; 0 iWTelement]
+WT = tf([10,0.1],[1,1]) .* I(2)
 
 # Form augmented P dynamics in state-space
 P = hinfpartition(G, WS, WU, WT)

src/RobustAndOptimalControl.jl

@@ -19,7 +19,7 @@ import MatrixPencils, MatrixEquations
 export ExtendedStateSpace, system_mapping, performance_mapping, noise_mapping, ssdata_e, partition, ss
 include("ExtendedStateSpace.jl")
 
-export δ, δr, δc, δss, nominal, UncertainSS, uss
+export δ, δr, δc, δss, nominal, UncertainSS, uss, blocksort
 include("uncertainty_interface.jl")
 
 export Weights, makeweight, neglected_delay, gain_and_delay_uncertainty, neglected_lag, fit_complex_perturbations

src/diskmargin.jl

@@ -8,11 +8,13 @@ The notation follows "An Introduction to Disk Margins", Peter Seiler, Andrew Pac
 `ω0`: The worst-case frequency
 `f0`: The destabilizing perturbation `f0` is a complex number with simultaneous gain and phase variation. This critical perturbation causes an instability with closed-loop pole on the imaginary axis at the critical frequency ω0 
 `δ0`: The uncertain element generating f0.
-`γmin`: The lower real-axis intercept of the disk (classical lower gain margin).
-`γmax`: The upper real-axis intercept of the disk (classical upper gain margin).
-`ϕm`: is the classical phase margin.
+`γmin`: The lower real-axis intercept of the disk (analogous to classical lower gain margin).
+`γmax`: The upper real-axis intercept of the disk (analogous to classical upper gain margin).
+`ϕm`: is analogous to the classical phase margin.
 `σ`: The skew parameter that was used to calculate the margin
 
+Note, `γmax` and `ϕm` are in smaller than the classical gain and phase margins sicne the classical margins do not consider simultaneous perturbations in gain and phase. 
+
 The "disk" margin becomes a half plane for `α = 2` and an inverted circle for `α > 2`. In this case, the upper gain margin is infinite. See the paper for more details, in particular figure 6.
 """
 struct Diskmargin

src/mimo_diskmargin.jl

@@ -15,6 +15,7 @@ any0det(D::Matrix{<:Complex{<:Interval}}) = 0 ∈ det(D)
 
 """
     bisect_a(P, K, w; W = (:), Z = (:), au0 = 3.0, tol = 0.001, N = 32, upper = true, δ = δc, σ=-1)
+    bisect_a(M, D, w; W = (:), Z = (:), au0 = 3.0, tol = 0.001, N = 32, upper = true, δ = δc, σ=-1)
 
 EXPERIMENTAL AND SUBJECT TO BUGS, BREAKAGE AND REMOVAL
 
@@ -38,8 +39,8 @@ If `upper = true`, a Monte-Carlo approach is used to find an upper bound of the
 - `upper`: Calculate upper or lower bound?
 - `δ = δc` for complex perturbations and `δ = δr` for real perturbations.
 """
-function bisect_a(args...;  au0 = 3.0, tol=1e-3, kwargs...)
-    M0, D = get_M(args...; kwargs...)
+function bisect_a(M0::AbstractArray, D::AbstractMatrix;  au0 = 3.0, tol=1e-3, kwargs...)
+    
     iters = ceil(Int, log2(au0/tol))
     @views map(axes(M0, 3)) do i
         au = au0
@@ -57,6 +58,11 @@ function bisect_a(args...;  au0 = 3.0, tol=1e-3, kwargs...)
     end
 end
 
+function bisect_a(args...;  au0 = 3.0, tol=1e-3, kwargs...)
+    M0, D = get_M(args...; kwargs...)
+    bisect_a(M0, D;  au0 = 3.0, tol=1e-3, kwargs...)
+end
+
 """
     M,D = get_M(P, K, w; W = (:), Z = (:), N = 32, upper = false, δ = δc, σ=-1)
 

src/uncertainty_interface.jl

@@ -523,10 +523,10 @@ end
     block_structure(Δ)
 
 Take a vector of uncertain elements and return a vector of vectors with the block
-structure of perturbation blocks as described expected my μ-tools, i.e.
-- `[-N, 0]` denots a repeated real block of size `N`
-- `[N, 0]` denots a repeated complex block of size `N`
-- `[ny, nu]` denots a full complex block of size `ny × nu`
+structure of perturbation blocks as described by μ-tools, i.e.
+- `[-N, 0]` denotes a repeated real block of size `N`
+- `[N, 0]` denotes a repeated complex block of size `N`
+- `[ny, nu]` denotes a full complex block of size `ny × nu`
 """
 function block_structure(D)
     perm = sortperm(D, by=d->d.name)
@@ -561,6 +561,16 @@ function makeblock(d) # TODO: full uncertain block that is not a dynamical syste
 end
 
 
+"""
+    blocks, M = blocksort(P::UncertainSS)
+
+Returns the block structure of `P.Δ` as well as `P.M` permuted according to the sorted block structure.
+`blocks` is a vector of vectors with the block
+structure of perturbation blocks as described by μ-tools, i.e.
+- `[-N, 0]` denotes a repeated real block of size `N`
+- `[N, 0]` denotes a repeated complex block of size `N`
+- `[ny, nu]` denotes a full complex block of size `ny × nu`
+"""
 function blocksort(P::UncertainSS)
     blocks, perm = block_structure(P.Δ)
     Poutinds = []