docstrings updates (#646)

Author: baggepinnen

src/analysis.jl

@@ -35,12 +35,12 @@ function poles(sys::TransferFunction{<:TimeEvolution,SisoZpk{T,TR}}) where {T, T
     return lcmpoles
 end
 
+# TODO: Improve implementation, should be more efficient ways.
+# Calculates the same minors several times in some cases.
 """
     minorpoles(sys)
 
 Compute the poles of all minors of the system."""
-# TODO: Improve implementation, should be more efficient ways.
-# Calculates the same minors several times in some cases.
 function minorpoles(sys::Matrix{SisoZpk{T, TR}}) where {T, TR}
     minors = Array{TR,1}[]
     ny, nu = size(sys)
@@ -68,11 +68,11 @@ function minorpoles(sys::Matrix{SisoZpk{T, TR}}) where {T, TR}
     return minors
 end
 
+# TODO: improve this implementation, should be more efficient ones
 """
     det(sys)
 
 Compute the determinant of the Matrix `sys` of SisoTf systems, returns a SisoTf system."""
-# TODO: improve this implementation, should be more efficient ones
 function det(sys::Matrix{S}) where {S<:SisoZpk}
     ny, nu = size(sys)
     ny == nu || throw(ArgumentError("sys matrix is not square"))
@@ -146,13 +146,13 @@ poles, `ps`, of `sys`"""
 function damp(sys::LTISystem)
     ps = poles(sys)
     if isdiscrete(sys)
-        ps = log.(complex.(ps))/sys.Ts
+        ps = @. log(complex(ps))/sys.Ts
     end
     Wn = abs.(ps)
     order = sortperm(Wn; by=z->(abs(z), real(z), imag(z)))
     Wn = Wn[order]
     ps = ps[order]
-    ζ = -cos.(angle.(ps))
+    ζ = @. -cos(angle(ps))
     return Wn, ζ, ps
 end
 
@@ -279,8 +279,7 @@ function reduce_sys(A::AbstractMatrix, B::AbstractMatrix, C::AbstractMatrix, D::
         end
 
         # Compress columns of Ctilde
-        V = qr(Ctilde').Q
-        V = reverse(V,dims=2)
+        V = reverse(qr(Ctilde').Q, dims=2)
         Sj = Ctilde*V
         rho = fastrank(Sj', meps)
         nu = size(Sj, 2) - rho
@@ -294,7 +293,7 @@ function reduce_sys(A::AbstractMatrix, B::AbstractMatrix, C::AbstractMatrix, D::
         end
         # Update System
         n, m = size(B)
-        Vm = [V zeros(T, n, m); zeros(T, m, n) Matrix{T}(I, m, m)]
+        Vm = [V zeros(T, n, m); zeros(T, m, n) Matrix{T}(I, m, m)] # I(m) is not used for type stability reasons (as of julia v1.7)
         if sigma > 0
             M = [A B; Cbar Dbar]
             Vs = [V' zeros(T, n, sigma) ; zeros(T, sigma, n) Matrix{T}(I, sigma, sigma)]
@@ -403,14 +402,13 @@ function relative_gain_array(A::AbstractMatrix; tol = 1e-15)
 end
 
 """
-`ωgₘ, gₘ, ωϕₘ, ϕₘ = margin{S<:Real}(sys::LTISystem, w::AbstractVector{S}; full=false, allMargins=false)`
+    ωgₘ, gₘ, ωϕₘ, ϕₘ = margin(sys::LTISystem, w::Vector; full=false, allMargins=false)
 
 returns frequencies for gain margins, gain margins, frequencies for phase margins, phase margins
 
 If `!allMargins`, return only the smallest margin
 
 If `full` return also `fullPhase`
-
 """
 function margin(sys::LTISystem, w::AbstractVector{<:Real}; full=false, allMargins=false)
     ny, nu = size(sys)
@@ -441,7 +439,7 @@ function margin(sys::LTISystem, w::AbstractVector{<:Real}; full=false, allMargin
 end
 
 """
-`ωgₘ, gₘ, ωϕₘ, ϕₘ = sisomargin{S<:Real}(sys::LTISystem, w::AbstractVector{S}; full=false, allMargins=false)`
+    ωgₘ, gₘ, ωϕₘ, ϕₘ = sisomargin(sys::LTISystem, w::Vector; full=false, allMargins=false)
 
 returns frequencies for gain margins, gain margins, frequencies for phase margins, phase margins
 """
@@ -588,19 +586,13 @@ end
 Given transfer functions describing the Plant `P`, the controller `C` and a feed forward block `F`,
 computes the four transfer functions in the Gang-of-Four and the transferfunctions corresponding to the feed forward.
 
-`S = 1/(1+PC)` Sensitivity function
-
-`PS = P/(1+PC)`
-
-`CS = C/(1+PC)`
-
-`T = PC/(1+PC)` Complementary sensitivity function
-
-`RY = PCF/(1+PC)`
-
-`RU = CF/(1+P*C)`
-
-`RE = F/(1+P*C)`
+- `S = 1/(1+PC)` Sensitivity function
+- `PS = P/(1+PC)`
+- `CS = C/(1+PC)`
+- `T = PC/(1+PC)` Complementary sensitivity function
+- `RY = PCF/(1+PC)`
+- `RU = CF/(1+P*C)`
+- `RE = F/(1+P*C)`
 
 Only supports SISO systems"""
 function gangofseven(P::TransferFunction, C::TransferFunction, F::TransferFunction)

src/freqresp.jl

@@ -147,7 +147,9 @@ function _evalfr_return_type(sys::AbstractStateSpace, s::Number)
 end
 
 """
-`evalfr(sys, x)` Evaluate the transfer function of the LTI system sys
+    evalfr(sys, x)
+    
+Evaluate the transfer function of the LTI system sys
 at the complex number s=x (continuous-time) or z=x (discrete-time).
 
 For many values of `x`, use `freqresp` instead.
@@ -198,10 +200,11 @@ function (sys::TransferFunction)(z_or_omegas::AbstractVector, map_to_unit_circle
     [v[i,j]  for v in vals, i in 1:nu, j in 1:ny]
 end
 
-"""`mag, phase, w = bode(sys[, w])`
+"""
+    mag, phase, w = bode(sys[, w])
 
 Compute the magnitude and phase parts of the frequency response of system `sys`
-at frequencies `w`
+at frequencies `w`. See also [`bodeplot`](@ref)
 
 `mag` and `phase` has size `(length(w), ny, nu)`""" 
 @autovec (1, 2) function bode(sys::LTISystem, w::AbstractVector)
@@ -210,10 +213,11 @@ at frequencies `w`
 end
 @autovec (1, 2) bode(sys::LTISystem) = bode(sys, _default_freq_vector(sys, Val{:bode}()))
 
-"""`re, im, w = nyquist(sys[, w])`
+"""
+    re, im, w = nyquist(sys[, w])
 
 Compute the real and imaginary parts of the frequency response of system `sys`
-at frequencies `w`
+at frequencies `w`. See also [`nyquistplot`](@ref)
 
 `re` and `im` has size `(length(w), ny, nu)`""" 
 @autovec (1, 2) function nyquist(sys::LTISystem, w::AbstractVector)
@@ -222,10 +226,11 @@ at frequencies `w`
 end
 @autovec (1, 2) nyquist(sys::LTISystem) = nyquist(sys, _default_freq_vector(sys, Val{:nyquist}()))
 
-"""`sv, w = sigma(sys[, w])`
+"""
+    sv, w = sigma(sys[, w])
 
 Compute the singular values `sv` of the frequency response of system `sys` at
-frequencies `w`
+frequencies `w`. See also [`sigmaplot`](@ref)
 
 `sv` has size `(length(w), max(ny, nu))`""" 
 @autovec (1) function sigma(sys::LTISystem, w::AbstractVector)
@@ -258,8 +263,8 @@ function _bounds_and_features(sys::LTISystem, plot::Val)
         zp = vcat(zpType[], zs..., ps...) # Emty vector to avoid type unstable vcat()
         zp = zp[imag(zp) .>= 0.0]
     else
-         # For sigma plots, use the MIMO poles and zeros
-         zp = [tzeros(sys); poles(sys)]
+        # For sigma plots, use the MIMO poles and zeros
+        zp = [tzeros(sys); poles(sys)]
     end
     # Get the frequencies of the features, ignoring low frequency dynamics
     fzp = log10.(abs.(zp))

src/pid_design.jl

@@ -224,7 +224,7 @@ function leadlinkat(ω, N, K; h=nothing, Ts=0)
 end
 
 """
-leadlinkcurve(start=1)
+    leadlinkcurve(start=1)
 
 Plot the phase advance as a function of `N` for a lead link (phase advance link)
 If an input argument `s` is given, the curve is plotted from `s` to 10, else from 1 to 10.

src/timeresp.jl

@@ -8,7 +8,7 @@
 
 Calculate the step response of system `sys`. If the final time `tfinal` or time
 vector `t` is not provided, one is calculated based on the system pole
-locations.
+locations. The return value is a structure of type `SimResult` that can be plotted or destructured as `y, t, x = result`.
 
 `y` has size `(ny, length(t), nu)`, `x` has size `(nx, length(t), nu)`"""
 function Base.step(sys::AbstractStateSpace, t::AbstractVector; method=:cont, kwargs...)
@@ -40,7 +40,7 @@ Base.step(sys::TransferFunction, t::AbstractVector; kwargs...) = step(ss(sys), t
 
 Calculate the impulse response of system `sys`. If the final time `tfinal` or time
 vector `t` is not provided, one is calculated based on the system pole
-locations.
+locations. The return value is a structure of type `SimResult` that can be plotted or destructured as `y, t, x = result`.
 
 `y` has size `(ny, length(t), nu)`, `x` has size `(nx, length(t), nu)`"""
 function impulse(sys::AbstractStateSpace, t::AbstractVector; kwargs...)

src/types/DelayLtiSystem.jl

@@ -192,13 +192,22 @@ function feedback(sys1::DelayLtiSystem, sys2::DelayLtiSystem)
 end
 
 """
+    delay(tau)
     delay(T::Type{<:Number}, tau)
 
 Create a pure time delay of length `τ` of type `T`.
 
 The type `T` defaults to `promote_type(Float64, typeof(tau))`
-"""
 
+# Example:
+Create a LTI system with an input delay of `L`
+```julia
+L = 1
+tf(1, [1, 1])*delay(L)
+s = tf("s")
+tf(1, [1, 1])*exp(-s*L) # Equivalent to the version above
+```
+"""
 function delay(T::Type{<:Number}, τ)
     return DelayLtiSystem(ControlSystems.ss([zero(T) one(T); one(T) zero(T)], Continuous()), [T(τ)])
 end

src/utilities.jl

@@ -127,10 +127,16 @@ function unwrap!(M::Array, dim=1)
 end
 
 #Collect will create a copy and collect the elements
+"""
+    unwrap(m::AbstractArray, args...)
+
+Unwrap a vector of phase angles (radians) in (-π, π) such that it does not wrap around the edges -π and π, i.e., the result may leave the range (-π, π).
+"""
 unwrap(m::AbstractArray, args...) = unwrap!(collect(m), args...)
 unwrap(x::Number) = x
 
-"""outs = index2range(ind1, ind2)
+"""
+    outs = index2range(ind1, ind2)
 
 Helper function to convert indexes with scalars to ranges. Used to avoid dropping dimensions
 """
@@ -139,7 +145,8 @@ index2range(ind::T) where {T<:Number} = ind:ind
 index2range(ind::T) where {T<:AbstractArray} = ind
 index2range(ind::Colon) = ind
 
-"""@autovec (indices...) f() = (a, b, c)
+"""
+    @autovec (indices...) f() = (a, b, c)
 
 A macro that helps in creating versions of functions where excessive dimensions are
 removed automatically for specific outputs. `indices` contains each index for which