add examples to neglected dynamics docstrings

docs/src/uncertainty.md

@@ -6,10 +6,10 @@ We provide two general means of modeling uncertainty, the traditional $M\Delta$
 - [`δc`](@ref) Creates an uncertain complex parameter.
 - [`δr`](@ref) Creates an uncertain real parameter.
 - [`δss`](@ref) (Experimental) Creates an uncertain statespace model.
-- [`neglected_delay`](@ref)
-- [`neglected_lag`](@ref)
-- [`gain_and_delay_uncertainty`](@ref)
-- [`makeweight`](@ref)
+- [`neglected_delay`](@ref) Create a multiplicative weight that represents uncertainty from an unmodeled delay.
+- [`neglected_lag`](@ref) Create a multiplicative weight that represents uncertainty from an unmodeled lag (pole).
+- [`gain_and_delay_uncertainty`](@ref) Create a multiplicative weight that represents uncertainty from uncertain gains and delay.
+- [`makeweight`](@ref) Create a custom weighting function.
 - [`fit_complex_perturbations`](@ref)
 - See [MonteCarloMeasurements.jl](https://baggepinnen.github.io/MonteCarloMeasurements.jl/stable/) to create uncertain parameters that are represented by samples.
 

src/weights.jl

@@ -37,6 +37,20 @@ end
 Return a multiplicative weight to represent the uncertainty coming from neglecting the dynamics `exp(-s*L)`
 where `L ≤ Lmax`.
 "Multivariable Feedback Control: Analysis and Design" Ch 7.4.5
+
+See also [`gain_and_delay_uncertainty`](@ref) and [`neglected_lag`](@ref).
+
+# Example:
+```julia
+a = 10
+P = ss([0 a; -a 0], I(2), [1 a; -a 1], 0) # Plant
+W0 = neglected_delay(0.005) |> ss # Weight
+W = I(2) + W0*I(2) * uss([δr(), δr()]) # Create a diagonal real uncertainty weighted in frequency by W0
+Ps = P*W # Uncertain plant
+Psamples = rand(Ps, 100) # Sample the uncertain plant for plotting
+w = exp10.(LinRange(-1, 3, 300)) # Frequency vector
+bodeplot(Psamples, w)
+```
 """
 function neglected_delay(Lmax)
     gain_and_delay_uncertainty(1, 1, Lmax)
@@ -48,6 +62,20 @@ end
 Return a multiplicative weight to represent the uncertainty coming from neglecting the dynamics `k*exp(-s*L)`
 where `k ∈ [kmin, kmax]` and `L ≤ Lmax`.
 This weight is slightly optimistic, an expression for a more exact weight appears in eq (7.27), "Multivariable Feedback Control: Analysis and Design"
+
+See also [`neglected_lag`](@ref) and [`neglected_delay`](@ref).
+
+# Example:
+```julia
+a = 10
+P = ss([0 a; -a 0], I(2), [1 a; -a 1], 0) # Plant
+W0 = gain_and_delay_uncertainty(0.5, 2, 0.005) |> ss # Weight
+W = I(2) + W0*I(2) * uss([δr(), δr()]) # Create a diagonal real uncertainty weighted in frequency by W0
+Ps = P*W # Uncertain plant
+Psamples = rand(Ps, 100) # Sample the uncertain plant for plotting
+w = exp10.(LinRange(-1, 3, 300)) # Frequency vector
+bodeplot(Psamples, w)
+```
 """
 function gain_and_delay_uncertainty(kmin, kmax, Lmax)
     kb = (kmin+kmax)/2
@@ -61,6 +89,20 @@ end
 Return a multiplicative weight to represent the uncertainty coming from neglecting the dynamics `1/(s*τ + 1)`
 where `τ ≤ τmax`.
 "Multivariable Feedback Control: Analysis and Design" Ch 7.4.5
+
+See also [`gain_and_delay_uncertainty`](@ref) and [`neglected_delay`](@ref).
+
+# Example:
+```julia
+a = 10
+P = ss([0 a; -a 0], I(2), [1 a; -a 1], 0) # Plant
+W0 = neglected_lag(0.05) |> ss # Weight
+W = I(2) + W0*I(2) * uss([δr(), δr()]) # Create a diagonal real uncertainty weighted in frequency by W0
+Ps = P*W # Uncertain plant
+Psamples = rand(Ps, 100) # Sample the uncertain plant for plotting
+w = exp10.(LinRange(-1, 3, 300)) # Frequency vector
+sigmaplot(Psamples, w)
+```
 """
 function neglected_lag(τmax)
     tf([τmax, 0], [τmax, 1])