Eq29 <: InverseLQRMethod

R is a weighting matrix, determining the relative importance of matching each input to that provided by the original controller.

Eq32 <: InverseLQRMethod
Eq32(q1, r1)

r1 penalizes deviation from the original control signal while q1 penalizes deviation from the original effect the cotrol signal had on the state. In other words, the r1 term tries to use the same actuator configuration as the original controller, while the q1 term ensures that the effec of the controller is the same.

LMI <: InverseLQRMethod

R is a weighting matrix, determining the relative importance of matching each input to that provided by the original controller.

Q,R,S,P,L2 = inverse_lqr(method::Eq29, G::AbstractStateSpace, L)

Solve the inverse optimal control problem that finds the LQR cost function that leads to a controller approximating state feedback controller with gain matrix L. P is the solution to the Riccati equation and L2 is the recreated feedback gain. Note: S will in general not be zero, and including this cross term in the cost function may be important. If including S is not possible, use the LMI method to find a cost function with as small S as possible.

Creates the stage-cost matrix

\[\begin{bmatrix} L^T R L & -L^T R\\ -R L & R \end{bmatrix} = \begin{bmatrix} Q & -S\\ -S^T & R \end{bmatrix} \]

Ref: "Designing MPC controllers by reverse-engineering existing LTI controllers", E. N. Hartley, J. M. Maciejowski

Q,R,S,P,L2 = inverse_lqr(method::Eq32, G::AbstractStateSpace, L)

Solve the inverse optimal control problem that finds the LQR cost function that leads to a controller approximating state feedback controller with gain matrix L. P is the solution to the Riccati equation and L2 is the recreated feedback gain. Note: S will in general not be zero, and including this cross term in the cost function may be important. If including S is not possible, use the LMI method to find a cost function with as small S as possible.

Creates the cost function

\[||Bu - BLu||^2_{q_1} + ||u - Lu||^2_{r_1}\]

Ref: "Designing MPC controllers by reverse-engineering existing LTI controllers", E. N. Hartley, J. M. Maciejowski

Q,R,S,P,L2 = inverse_lqr(method::GMF)

Solve the inverse optimal control problem that finds the LQR cost function on the form

\[x'Qx + u'Ru\]

that leads to an LQR controller approximating a Glover McFarlane controller. Using this method, S = 0.

Ref: Rowe and Maciejowski, "Tuning MPC using H∞ Loop Shaping" .

Example

disc = (x) -> c2d(ss(x), 0.01)
G = tf([1, 5], [1, 2, 10]) |> disc # Plant model
W1 = tf(1,[1, 0])          |> disc # Loop shaping weight
gmf2 = glover_mcfarlane(G; W1) # Design Glover McFarlane controller
Q,R,S,P,L = inverse_lqr(GMF(gmf2)) # Get cost function

using Test
L3 = lqr(G*W1, Q, R) # Test equivalence to LQR
@test L3 ≈ -L2

Q,R,S,P,L2 = inverse_lqr(method::LMI, G::AbstractStateSpace, L; optimizer = Hypatia.Optimizer)

Solve the inverse optimal control problem that finds the LQR cost function that leads to a controller approximating state feedback controller with gain matrix L. P is the solution to the Riccati equation and L2 is the recreated feedback gain. Note, L is supposed to be used with negative feedback, i.e., it's designed such that u = -Lx.

Solves a convex LMI problem minimizing the cross term S. Note: there is no guarantee that the corss term will be driven to 0 exactly. If S remains large in relation to Q and R, S must be included in the cost function for high fidelity reproduction of the original controller.

Ref: "Designing MPC controllers by reverse-engineering existing LTI controllers", E. N. Hartley, J. M. Maciejowski

FixedGainObserver{F <: Function, x} <: AbstractFilter
FixedGainObserver(sys::AbstractStateSpace, x0, K)

A linear observer, similar to a Kalman filer, but with a fixed measurement feedback gain. The gain can be designed using, e.g., pole placement or solving a Riccati equation. For a robust observer, consider using glover_mcfarlane followed by inverse_lqr.

OperatingPoint(x, u, y)
OperatingPoint()

Structure representing an operating point around which a system is linearized. If no arguments are supplied, an empty operating point is created.

Arguments:

• x: State
• u: Control input
• y: Output

StateFeedback{F <: Function, x} <: AbstractFilter
StateFeedback(discrete_dynamics, x0, nu, ny)
StateFeedback(sys::FunctionSystem, x0)

An observer that uses the dynamics model without any measurement feedback. This observer can be used as an oracle that has full knowledge of the state. Note, this is often an unrealistic assumption in real-world contexts and open-loop observers can not account for load disturbances. Use of this observer in a closed-loop context creates a false closed loop.

UnscentedKalmanFilter(sys::FunctionSystem, R1, R2, d0=MvNormal(Matrix(R1)); p = SciMLBase.NullParameters())

Convencience constructor for systems of type FunctionSystem.

mussv(M::AbstractMatrix; optimizer = Hypatia.Optimizer{eltype(M)}, bu = opnorm(M), tol = 0.001)

Compute (an upper bound of) the structured singular value μ for diagonal Δ of complex perturbations (other structures of Δ are handled by supplying the block structure mussv(M, blocks)). M is assumed to be an (n × n × N_freq) array or a matrix.

Solves a convex LMI.

Arguments:

• bu: Upper bound for bisection.
• tol: tolerance.

See also mussv, mussv_tv, mussv_DG.

Extended help

By default, the Hypatia solver (native Julia) is used to solve the problem. Other solvers that handle the this problem formulation is

• Mosek (requires license)
• SCS

The solver can be selected using the keyword argument optimizer.

mussv(M::AbstractStateSpace, blocks; optimizer = Hypatia.Optimizer, bu0 = 20, tol = 0.001)

Compute (an upper bound of) the structured singular value μ of statespace model M interconnected with uncertainty structure described by blocks. Reference: MAE509 (LMIs in Control): Lecture 14, part C - LMIs for Robust Control with Structured Uncertainty

Example:

The following example illustrates how to use the structured singular value to determine how large diagonal complex uncertainty can be added at the input of a plant P before the closed-loop system becomes unstable

julia> Δ = uss([δc(), δc()]); # Diagonal uncertainty element

julia> a = 1;

julia> P = ss([0 a; -a -1], I(2), [1 a; 0 1], 0) * (I(2) + Δ);

julia> K = ss(I(2));

julia> G = lft(P, -K);

julia> stabmargin = 1/mussv(G) # We can handle 134% of the modeled uncertainty
1.3429508196721311

julia> # Compare with the input diskmargin
       diskmargin(K*system_mapping(P), -1)
Disk margin with:
Margin: 1.3469378397689664
Frequency: -0.40280561122244496
Gain margins: [-0.3469378397689664, 2.3469378397689664]
Phase margin: 84.67073122411068
Skew: -1
Worst-case perturbation: missing

Extended help

By default, the Hypatia solver is used to solve the problem. Other solvers that handle the this problem formulation is

• Mosek (requires license)
• Hypatia.jl (native Julia)
• Clarabel.jl (native Julia)
• SCS (typically performs poorly for this problem)

The solver can be selected using the keyword argument optimizer.

mussv(G::UncertainSS; kwargs...)

Compute (an upper bound of) the structured singular value μ of uncertain system model G.

mussv_DG(M::AbstractMatrix; optimizer = Hypatia.Optimizer{eltype(M)}, bu = opnorm(M), tol = 0.001)

Compute (an upper bound of) the structured singular value μ for diagonal Δ of real perturbations (other structures of Δ are not yet supported). M is assumed to be an (n × n × N_freq) array or a matrix.

See mussv for more details. See also mussv, mussv_tv, mussv_DG.

mussv_tv(G::AbstractStateSpace, blocks; optimizer = Hypatia.Optimizer, bu = 20, tol = 0.001)

Compute (an upper bound of) the structured singular value margin when G is interconnected with time-varying uncertainty structure described by blocks. This value will in general be larger than the one returned by mussv, but can be used to guarantee stability for infinitely fast time-varying perturbations, i.e., if the return value is < 1, the system is stable no matter how fast the dynamics of the perturbations change.

The result will in general be more accurate if G is passed rather than a matrix M, unless a very dense grid around the critical frequency is used for to calculate M.

Solves a convex LMI.

Arguments:

• bu: Upper bound for bisection.
• tol: tolerance.

See also mussv, mussv_tv, mussv_DG.

mussv_tv(M::AbstractArray{<:Any, 3}; optimizer = Hypatia.Optimizer, bu = 20, tol = 0.001)
mussv_tv(G::UncertainSS; optimizer = Hypatia.Optimizer, bu0 = 20, tol = 0.001)

Compute (an upper bound of) the structured singular value μ for diagonal, complex and time-varying Δ(t) using constant (over frequency) matrix scalings. This value will in general be larger than the one returned by mussv, but can be used to guarantee stability for infinitely fast time-varying perturbations, i.e., if the return value is < 1, the system is stable no matter how fast the dynamics of the perturbations change.

M is assumed to be an (n × n × N_freq) array or a matrix. G is an UncertainSS. The result will in general be more accurate if G is passed rather than M, unless a very dense grid around the critical frequency is used for to calculate M.

Solves a convex LMI.

Arguments:

• bu: Upper bound for bisection.
• tol: tolerance.

See also mussv, mussv_tv, mussv_DG.

Extended help

The normal μ is calculated by minimizing

\[\operatorname{min}_D ||D(\omega) M(\omega) D(\omega)^{-1}||\]

where a unique $D(\omega)$ is allowed for each frequency. However, in this problem, the $D$ scalings are constant over frequency, yielding a more conservative answer, with the additional bonus of being applicable for time-varying perturbations.

This strong guarantee can be used to prove stability of nonlinear systems by formulating them as linear systems with time-varying, norm-bounded perturbations. For such systems, mussv_tv < 1 is a sufficient condition for stability. See Boyd et al., "Linear Matrix Inequalities in System and Control Theory" for more details.

K, γ = hinfsyn_lmi(P::ExtendedStateSpace;
    opt = Hypatia.Optimizer(), γrel = 1.01, ϵ = 1e-3, balance = true, perm = false,)

Computes an H-infinity optimal controller K for an extended plant P such that ||F_l(P, K)||∞ < γ (lft(P, K)) for the smallest possible γ given P. This implementation solves a convex LMI problem.

Arguments:

• opt: A MathOptInterface solver constructor.
• γrel: If γrel > 1, the optimal γ will be found by γ iteration after which a controller will be designed for γ = γopt * γrel. It is often a good idea to design a slightly suboptimal controller, both for numerical reasons, but also since the optimal controller may contain very fast dynamics. If γrel → ∞, the computed controller will approach the 𝑯₂ optimal controller. Getting a mix between 𝑯∞ and 𝑯₂ properties is another reason to choose γrel > 1.
• ϵ: A small offset to enforce strict LMI inequalities. This can be tuned if numerical issues arise.
• balance: Perform a balancing transformation on P using ControlSystemsBase.balance_statespace.
• perm: If balance=true, perm=true, the balancing transform is allowed to permute the state vector. This is not allowed by default, but can improve the numerics slightly if allowed.

The Hypatia solver takes the following arguments https://github.com/chriscoey/Hypatia.jl/blob/42e4b10318570ea22adb39fec1c27d8684161cec/src/Solvers/Solvers.jl#L73

ispassive_lmi(P::AbstractStateSpace{ControlSystemsBase.Continuous}; ftype = Float64, opt = Hypatia.Optimizer{ftype}(), ϵ = 0.001, balance = true, verbose = true, silent_solver = true)

Determine if square system P is passive, i.e., $P(s) + Pᴴ(s) > 0$.

A passive system has a Nyquist curve that lies completely in the right half plane, and satisfies the following inequality (dissipation of energy)

\[\int_0^T y^T u dt > 0 ∀ T\]

The negative feedback-interconnection of two passive systems is stable and parallel connections of two passive systems as well as the inverse of a passive system are also passive. A passive controller will thus always yeild a stable feedback loop for a passive system. A series connection of two passive systems is not always passive.

This functions solves a convex LMI related to the KYP (positive real) lemma.

Arguments:

• balance: Balance the system before calculations?
• verbose: Print status messages

K, Gcl = spr_synthesize(P0::ExtendedStateSpace{Continuous};, opt = Hypatia.Optimizer, balance = true, verbose = true, silent_solver = true, ϵ = 1e-6)

Design a strictly positive real controller (passive) that optimizes the closed-loop H₂-norm subject to being passive.

For plants that are known to be passive, control using a passive controller is guaranteed to be stable.

The returned controller is supposed to be used with positive feedback, so ispassive(-K) should hold. The resulting closed-loop system from disturbances to performance outputs is also returned, Gcl = lft(P0, K).

Implements the algorithm labeled as "Pseudocode 1" in "Synthesis of strictly positive real H2 controllers using dilated LMI", Forbes 2018

Arguments:

• P0: An ExtendedStateSpace object. This object can be designed using H₂ or H∞ methods. See, e.g., hinfpartition.
• opt: A JuMP compatible solver.
• balance: Perform balancing of the statespace system before solving.
• verbose: Print info?
• silent_solver:
• ϵ: A small numerical constant to enforce strict positive definiteness.

See also h2synthesize, hinfsynthesize.

FunctionSystem(sys::ODESystem, u, y; z=nothing, w=nothing, kwargs...)

Generate code for the dynamics and output of sys by calling build_controlled_dynamics. See build_controlled_dynamics for more details.

f, xout, pout = build_controlled_dynamics(sys, u; kwargs...)
f, obsf, xout, pout = build_controlled_dynamics(sys, u, y; z=nothing, w=nothing, kwargs...)

Build a function on the form (x,u,p,t) -> ẋ where

• x are the differential states

• u are control inputs

• p are parameters

• t is time

• kwargs are sent to ModelingToolkit.build_function

• f is a tuple of functions, one out of palce and one in place (x,u,p,t) -> ẋ and (ẋ,x,u,p,t) -> nothing

• xout contains the order of the states included in the dynamics

• pout contains the order of the parameters included in the dynamics

If in addition to u, outputs y are also specified, an additional observed function tuple is returned.

Example

This example forms a feedback system and builds a function of the dynamics from the reference r to the output y.

using ModelingToolkit, Test

@variables t x(t)=0 y(t)=0 u(t)=0 r(t)=0
@parameters kp=1
D = Differential(t)

eqs = [
    u ~ kp * (r - y) # P controller
    D(x) ~ -x + u    # Plant dynamics
    y ~ x            # Output equation
]

@named sys = ODESystem(eqs, t)

funsys = DyadControlSystems.build_controlled_dynamics(sys, r, y; checkbounds=true)
x  = zeros(funsys.nx) # sys.x
u  = [1] # r
p  = [1] # kp
xd = funsys(x,u,p,1)
varmap = Dict(
    funsys.x[] => 1,
    kp => 1,
)

@test xd == ModelingToolkit.varmap_to_vars(varmap, funsys.x)

FunctionSystem{TE <: ControlSystemsBase.TimeEvolution, F, G}

A structure representing the dynamical system

\[�egin{aligned} x′ &= f(x,u,p,t)\ y &= g(x,u,p,t) �nd{aligned}\]

To build a FunctionSystem for a DAE on mass-matrix form, use an ODEFunction as f

f = ODEFunction(dae_dyn, mass_matrix = M)

To obtain the simplified system and default values for the initial condition and parameters, see simplified_system.

Fields:

• dynamics::F
• measurement::G
• timeevol::TE: ControlSystemsBase.TimeEvolution
• x: states
• u: controlled inputs
• y: measured outputs
• w: disturbance inputs
• z: performance outputs
• p: parameters

FunctionSystem(f, g;           kwargs...)
FunctionSystem(f, g, Ts::Real; kwargs...)

Constructor for FunctionSystem.

Arguments:

• f: Discrete dynamics with signature (x,u,p,t)
• g: Measurement function with signature (x,u,p,t)
• Ts: If the sample time Ts is provided, the system represents a discrete-time system, otherwise the dynamics is assumed to be continuous.
• kwargs: Signal names

simplified_system(funcsys::FunctionSystem)

Obtain the result from structural_simplify that was obtained after input-output processing. This system is often of a lower order than the original system. To obtain the default initial condition and parameters of the simplified system, call

ssys = simplified_system(funcsys)
defs = ModelingToolkit.defaults(ssys)
x0, p0 = ModelingToolkit.get_u0_p(ssys, defs, defs)

Simulator

Fields:

P::StateSpace
f = (x,p,t) -> x
y = (x,t)   -> y

Simulator(P::StateSpace, u = (x,t) -> 0)

Used to simulate continuous-time systems. See function ?solve for additional info.

Usage:

using OrdinaryDiffEq, Plots
dt             = 0.1
tfinal         = 20
t              = 0:dt:tfinal
P              = ss(tf(1,[2,1])^2)
K              = 5
reference(x,t) = [1.]
s              = Simulator(P, reference)
x0             = [0.,0]
tspan          = (0.0,tfinal)
sol            = solve(s, x0, tspan, Tsit5())
plot(t, s.y(sol, t)[:], lab="Open loop step response")

roots, Z, K = rlocus(P::LTISystem, K = 500)

Compute the root locus of the SISO LTISystem P with a negative feedback loop and feedback gains between 0 and K. rlocus will use an adaptive step-size algorithm to determine the values of the feedback gains used to generate the plot.

roots is a complex matrix containing the poles trajectories of the closed-loop 1+k⋅G(s) as a function of k, Z contains the zeros of the open-loop system G(s) and K the values of the feedback gain.

res = lsim(sys::DelayLtiSystem, u, t::AbstractArray{<:Real}; x0=fill(0.0, nstates(sys)), alg=MethodOfSteps(Tsit5()), abstol=1e-6, reltol=1e-6, force_dtmin=true, kwargs...)

Simulate system sys, over time t, using input signal u, with initial state x0, using method alg .

Arguments:

t: Has to be an AbstractVector with equidistant time samples (t[i] - t[i-1] constant) u: Function to determine control signal ut at a time t, on any of the following forms:

• u: Function to determine control signal uₜ at a time t, on any of the following forms:
  • A constant Number or Vector, interpreted as a constant input.
  • Function u(x, t) that takes the internal state and time, note, the state representation for delay systems is not the same as for rational systems.
  • In-place function u(uₜ, x, t). (Slightly more efficient)

alg, abstol, reltol and kwargs...: are sent to DelayDiffEq.solve.

This methods sets force_dtmin=true by default to handle the discontinuity implied by, e.g., step inputs. This may lead to the solver taking a long time to solve ill-conditioned problems rather than exiting early with a warning.

Returns an instance of SimResult which can be plotted directly or destructured into y, t, x, u = res.

lsim(sys::HammersteinWienerSystem, u, t::AbstractArray{<:Real}; x0=fill(0.0, nstates(sys)), alg=Tsit5(), abstol=1e-6, reltol=1e-6, kwargs...)

Simulate system sys, over time t, using input signal u, with initial state x0, using method alg .

Arguments:

• t: Has to be an AbstractVector with equidistant time samples (t[i] - t[i-1] constant)
• u: Function to determine control signal uₜ at a time t, on any of the following forms: Can be a constant Number or Vector, interpreted as uₜ .= u , or Function uₜ .= u(x, t), or In-place function u(uₜ, x, t). (Slightly more efficient)
• alg, abstol, reltol and kwargs...: are sent to OrdinaryDiffEq.solve.

Returns an instance of SimResult.

BodemagWorkspace(sys::LTISystem, N::Int)
BodemagWorkspace(sys::LTISystem, ω::AbstractVector)
BodemagWorkspace(R::Array{Complex{T}, 3}, mag::Array{T, 3})
BodemagWorkspace{T}(ny, nu, N)

Generate a workspace object for use with the in-place function bodemag!. N is the number of frequency points, alternatively, the input ω can be provided instead of N. Note: for threaded applications, create one workspace object per thread.

Arguments:

• mag: The output array ∈ 𝐑(ny, nu, nω)
• R: Frequency-response array ∈ 𝐂(ny, nu, nω)

struct DelayLtiSystem{T, S <: Real} <: LTISystem

Represents an LTISystem with internal time-delay. See ?delay for a convenience constructor.

DelayLtiSystem{T, S}(sys::StateSpace, Tau::AbstractVector{S}=Float64[]) where {T <: Number, S <: Real}

Create a delayed system by specifying both the system and time-delay vector. NOTE: if you want to create a system with simple input or output delays, use the Function delay(τ).

LsimWorkspace(sys::AbstractStateSpace, N::Int)
LsimWorkspace(sys::AbstractStateSpace, u::AbstractMatrix)
LsimWorkspace{T}(ny, nu, nx, N)

Generate a workspace object for use with the in-place function lsim!. sys is the discrete-time system to be simulated and N is the number of time steps, alternatively, the input u can be provided instead of N. Note: for threaded applications, create one workspace object per thread.

StateSpace{TE, T} <: AbstractStateSpace{TE}

An object representing a standard state space system.

See the function ss for a user facing constructor as well as the documentation page creating systems.

Fields:

• A::Matrix{T}
• B::Matrix{T}
• C::Matrix{T}
• D::Matrix{T}
• timeevol::TE

StaticStateSpace(sys::AbstractStateSpace)

Return a HeteroStateSpace where the system matrices are of type SMatrix.

NOTE: This function is fundamentally type unstable. For maximum performance, create the static system manually, or make use of the function-barrier technique.

StepInfo

Computed using stepinfo

Fields:

• y0: The initial value of the step response.
• yf: The final value of the step response.
• stepsize: The size of the step.
• peak: The peak value of the step response.
• peaktime: The time at which the peak occurs.
• overshoot: The overshoot of the step response.
• settlingtime: The time at which the step response has settled to within settling_th of the final value.
• settlingtimeind::Int: The index at which the step response has settled to within settling_th of the final value.
• risetime: The time at which the response rises from risetime_th[1] to risetime_th[2] of the final value
• i10::Int: The index at which the response reaches risetime_th[1]
• i90::Int: The index at which the response reaches risetime_th[2]
• res::SimResult{SR}: The simulation result used to compute the step response characteristics.
• settling_th: The threshold used to compute settlingtime and settlingtimeind.
• risetime_th: The thresholds used to compute risetime, i10, and i90.

F(s), F(omega, true), F(z, false)

Notation for frequency response evaluation.

• F(s) evaluates the continuous-time transfer function F at s.
• F(omega,true) evaluates the discrete-time transfer function F at exp(imTsomega)
• F(z,false) evaluates the discrete-time transfer function F at z

y, t, x = step(sys[, tfinal])
y, t, x = step(sys[, t])

Calculate the response of the system sys to a unit step at time t = 0. If the final time tfinal or time vector t is not provided, one is calculated based on the system pole locations.

The return value is a structure of type SimResult. A SimResul can be plotted by plot(result), or destructured as y, t, x = result.

y has size (ny, length(t), nu), x has size (nx, length(t), nu)

See also stepinfo and lsim.

G_CS(P, C)

The closed-loop transfer function from (-) measurement noise or (+) reference to control signal. Technically, the transfer function is given by (1 + CP)⁻¹C so SC would be a better, but nonstandard name.

         ▲
         │e₁
         │  ┌─────┐
d₁────+──┴──►  P  ├─────┬──►e₄
      │     └─────┘     │
      │                 │
      │     ┌─────┐    -│
 e₂◄──┴─────┤  C  ◄──┬──+───d₂
            └─────┘  │
                     │e₃
                     ▼

• input_sensitivity is the transfer function from d₁ to e₁, (I + CP)⁻¹
• output_sensitivity is the transfer function from d₂ to e₃, (I + PC)⁻¹
• input_comp_sensitivity is the transfer function from d₁ to e₂, (I + CP)⁻¹CP
• output_comp_sensitivity is the transfer function from d₂ to e₄, (I + PC)⁻¹PC
• G_PS is the transfer function from d₁ to e₄, (1 + PC)⁻¹P
• G_CS is the transfer function from d₂ to e₂, (1 + CP)⁻¹C

G_PS(P, C)

The closed-loop transfer function from load disturbance to plant output. Technically, the transfer function is given by (1 + PC)⁻¹P so SP would be a better, but nonstandard name.

         ▲
         │e₁
         │  ┌─────┐
d₁────+──┴──►  P  ├─────┬──►e₄
      │     └─────┘     │
      │                 │
      │     ┌─────┐    -│
 e₂◄──┴─────┤  C  ◄──┬──+───d₂
            └─────┘  │
                     │e₃
                     ▼

• input_sensitivity is the transfer function from d₁ to e₁, (I + CP)⁻¹
• output_sensitivity is the transfer function from d₂ to e₃, (I + PC)⁻¹
• input_comp_sensitivity is the transfer function from d₁ to e₂, (I + CP)⁻¹CP
• output_comp_sensitivity is the transfer function from d₂ to e₄, (I + PC)⁻¹PC
• G_PS is the transfer function from d₁ to e₄, (1 + PC)⁻¹P
• G_CS is the transfer function from d₂ to e₂, (1 + CP)⁻¹C

Ms_from_gain_margin(g_m)

Compute the maximum sensitivity peak $M_S = ||S||_∞$ such that if respected, gives a gain margin of at least g_m.

See also Ms_from_phase_margin and margin_bounds.

Ms_from_phase_margin(ϕ_m)

Compute the maximum sensitivity peak $M_S = ||S||_∞$ such that if respected, gives a phase margin of at least ϕ_m (in radians).

See also Ms_from_gain_margin and margin_bounds.

add_input(sys::AbstractStateSpace, B2::AbstractArray, D2 = 0)

Add inputs to sys by forming

\[\begin{aligned} x' &= Ax + [B \; B_2]u \\ y &= Cx + [D \; D_2]u \\ \end{aligned}\]

If B2 is an integer it will be interpreted as an index and an input matrix containing a single 1 at the specified index will be used.

Example: The following example forms an innovation model that takes innovations as inputs

G   = ssrand(2,2,3, Ts=1)
K   = kalman(G, I(G.nx), I(G.ny))
sys = add_input(G, K)

add_output(sys::AbstractStateSpace, C2::AbstractArray, D2 = 0)

Add outputs to sys by forming

\[\begin{aligned} x' &= Ax + Bu \\ y &= [C; C_2]x + [D; D_2]u \\ \end{aligned}\]

If C2 is an integer it will be interpreted as an index and an output matrix containing a single 1 at the specified index will be used.

When called with C2 = I(sys.nx), this function is in some settings known to as augstate.

append(systems::StateSpace...), append(systems::TransferFunction...)

Append systems in block diagonal form

are(::Continuous, A, B, Q, R)

Compute 'X', the solution to the continuous-time algebraic Riccati equation, defined as A'X + XA - (XB)R^-1(B'X) + Q = 0, where R is non-singular.

In an LQR problem, Q is associated with the state penalty $x'Qx$ while R is associated with the control penalty $u'Ru$. See lqr for more details.

Uses MatrixEquations.arec. For keyword arguments, see the docstring of ControlSystemsBase.MatrixEquations.arec, note that they define the input arguments in a different order.

are(::Discrete, A, B, Q, R; kwargs...)

Compute X, the solution to the discrete-time algebraic Riccati equation, defined as A'XA - X - (A'XB)(B'XB + R)^-1(B'XA) + Q = 0, where Q>=0 and R>0

In an LQR problem, Q is associated with the state penalty $x'Qx$ while R is associated with the control penalty $u'Ru$. See lqr for more details.

Uses MatrixEquations.ared. For keyword arguments, see the docstring of ControlSystemsBase.MatrixEquations.ared, note that they define the input arguments in a different order.

array2mimo(M::AbstractArray{<:LTISystem})

Take an array of LTISystems and create a single MIMO system.

S, P, B = balance(A[, perm=true])

Compute a similarity transform T = S*P resulting in B = T\A*T such that the row and column norms of B are approximately equivalent. If perm=false, the transformation will only scale A using diagonal S, and not permute A (i.e., set P=I).

A, B, C, T = balance_statespace{S}(A::Matrix{S}, B::Matrix{S}, C::Matrix{S}, perm::Bool=false)
sys, T = balance_statespace(sys::StateSpace, perm::Bool=false)

Computes a balancing transformation T that attempts to scale the system so that the row and column norms of [TA/T TB; C/T 0] are approximately equal. If perm=true, the states in A are allowed to be reordered.

The inverse of sysb, T = balance_statespace(sys) is given by similarity_transform(sysb, T)

This is not the same as finding a balanced realization with equal and diagonal observability and reachability gramians, see balreal

sysr, G, T = balreal(sys::StateSpace)

Calculates a balanced realization of the system sys, such that the observability and reachability gramians of the balanced system are equal and diagonal diagm(G). T is the similarity transform between the old state x and the new state z such that z = Tx.

See also gram, baltrunc.

Reference: Varga A., Balancing-free square-root algorithm for computing singular perturbation approximations.

sysr, G, T = baltrunc(sys::StateSpace; atol = √ϵ, rtol=1e-3, n = nothing, residual = false)

Reduces the state dimension by calculating a balanced realization of the system sys, such that the observability and reachability gramians of the balanced system are equal and diagonal diagm(G), and truncating it to order n. If n is not provided, it's chosen such that all states corresponding to singular values less than atol and less that rtol σmax are removed.

T is the projection matrix between the old state x and the newstate z such that z = Tx. T will in general be a non-square matrix.

If residual = true, matched static gain is achieved through "residualization", i.e., setting

\[0 = A_{21}x_{1} + A_{22}x_{2} + B_{2}u\]

where indices 1/2 correspond to the remaining/truncated states respectively.

See also gram, balreal

Glad, Ljung, Reglerteori: Flervariabla och Olinjära metoder.

For more advanced model reduction, see RobustAndOptimalControl.jl - Model Reduction.

Extended help

Note: Gramian computations are sensitive to input-output scaling. For the result of a numerical balancing, gramian computation or truncation of MIMO systems to be meaningful, the inputs and outputs of the system must thus be scaled in a meaningful way. A common (but not the only) approach is:

• The outputs are scaled such that the maximum allowed control error, the maximum expected reference variation, or the maximum expected variation, is unity.
• The input variables are scaled to have magnitude one. This is done by dividing each variable by its maximum expected or allowed change, i.e., $u_{scaled} = u / u_{max}$

Without such scaling, the result of balancing will depend on the units used to measure the input and output signals, e.g., a change of unit for one output from meter to millimeter will make this output 1000x more important.

mag, phase, w = bode(sys[, w]; unwrap=true)

Compute the magnitude and phase parts of the frequency response of system sys at frequencies w. See also bodeplot

mag and phase has size (ny, nu, length(w)). If unwrap is true (default), the function unwrap! will be applied to the phase angles. This procedure is costly and can be avoided if the unwrapping is not required.

For higher performance, see the function bodemag! that computes the magnitude only.

mag = bodemag!(ws::BodemagWorkspace, sys::LTISystem, w::AbstractVector)

Compute the Bode magnitude operating in-place on an instance of BodemagWorkspace. Note that the returned magnitude array is aliased with ws.mag. The output array mag is ∈ 𝐑(ny, nu, nω).

fig = bodeplot(sys, args...)
bodeplot(LTISystem[sys1, sys2...], args...; plotphase=true, balance = true, kwargs...)

Create a Bode plot of the LTISystem(s). A frequency vector w can be optionally provided. To change the Magnitude scale see setPlotScale. The default magnitude scale is "log10" (absolute scale).

• If hz=true, the plot x-axis will be displayed in Hertz, the input frequency vector is still treated as rad/s.
• balance: Call balance_statespace on the system before plotting.
• adjust_phase_start: If true, the phase will be adjusted so that it starts at -90*intexcess degrees, where intexcess is the integrator excess of the system.
• adaptive: If true, an adaptive frequency grid is used in order to keep the number of plotted points low, while resolving features in the frequency response well. If a manually provided frequency vector is used, this may be downsampled before plotting.

kwargs is sent as argument to RecipesBase.plot.

bodev(sys::LTISystem, w::AbstractVector; $(Expr(:kw, :unwrap, true)))

For use with SISO systems where it acts the same as bode but with the extra dimensions removed in the returned values.

bodev(sys::LTISystem; )

For use with SISO systems where it acts the same as bode but with the extra dimensions removed in the returned values.

sysd = c2d(sys::AbstractStateSpace{<:Continuous}, Ts, method=:zoh; w_prewarp=0)
Gd = c2d(G::TransferFunction{<:Continuous}, Ts, method=:zoh)

Convert the continuous-time system sys into a discrete-time system with sample time Ts, using the specified method (:zoh, :foh, :fwdeuler or :tustin).

method = :tustin performs a bilinear transform with prewarp frequency w_prewarp.

• w_prewarp: Frequency (rad/s) for pre-warping when using the Tustin method, has no effect for other methods.

See also c2d_x0map

Extended help

ZoH sampling is exact for linear systems with piece-wise constant inputs (step invariant), i.e., the solution obtained using lsim is not approximative (modulu machine precision). ZoH sampling is commonly used to discretize continuous-time plant models that are to be controlled using a discrete-time controller.

FoH sampling is exact for linear systems with piece-wise linear inputs (ramp invariant), this is a good choice for simulation of systems with smooth continuous inputs.

To approximate the behavior of a continuous-time system well in the frequency domain, the :tustin (trapezoidal / bilinear) method may be most appropriate. In this case, the pre-warping argument can be used to ensure that the frequency response of the discrete-time system matches the continuous-time system at a given frequency. The tustin transformation alters the meaning of the state components, while ZoH and FoH preserve the meaning of the state components. The Tustin method is commonly used to discretize a continuous-time controller.

The forward-Euler method generally requires the sample time to be very small relative to the time constants of the system, and its use is generally discouraged.

Classical rules-of-thumb for selecting the sample time for control design dictate that Ts should be chosen as $0.2 ≤ ωgc⋅Ts ≤ 0.6$ where $ωgc$ is the gain-crossover frequency (rad/s).

c2d(G::DelayLtiSystem, Ts, method=:zoh)

Qd     = c2d(sys::StateSpace{Continuous}, Qc::Matrix, Ts;             opt=:o)
Qd, Rd = c2d(sys::StateSpace{Continuous}, Qc::Matrix, Rc::Matrix, Ts; opt=:o)
Qd     = c2d(sys::StateSpace{Discrete},   Qc::Matrix;                 opt=:o)
Qd, Rd = c2d(sys::StateSpace{Discrete},   Qc::Matrix, Rc::Matrix;     opt=:o)

Sample a continuous-time covariance or LQR cost matrix to fit the provided discrete-time system.

If opt = :o (default), the matrix is assumed to be a covariance matrix. The measurement covariance R may also be provided. If opt = :c, the matrix is instead assumed to be a cost matrix for an LQR problem.

The method used comes from theorem 5 in the reference below.

Ref: "Discrete-time Solutions to the Continuous-time Differential Lyapunov Equation With Applications to Kalman Filtering", Patrik Axelsson and Fredrik Gustafsson

On singular covariance matrices: The traditional double integrator with covariance matrix Qc = diagm([0,σ²]) warrants special consideration since it is rank-deficient, i.e., it indicates that there is a single source of randomness only, despite the presence of two state variables. If we assume that the noise is piecewise constant, we can use the input matrix ("Cholesky factor") of Qc, e.g., the noise of variance σ² enters like N = [0, 1] which is sampled using ZoH and becomes Nd = [Ts^2 / 2; Ts] which results in the covariance matrix σ² * Nd * Nd'. If we assume that the noise is a continuous-time white noise process, the discretized covariance matrix is full rank and can be computed by c2d(sys::StateSpace{Continuous}, Qc, Ts). In some applications, a rank-1 approximation to this matrix is favored. In such situation, a good rank-1 approximation to this matrix is obtained by σ² * Nd * Nd' ./ Ts. This has the benefit of being both low rank, and produce covariance dynamics that are approximately invariant to the choice of sample interval. If the ZoH assumption is made, the covariance matrix is rank 1 but the covariance dynamics are not invariant to the choice of sample interval.`

Example:

The following example designs a continuous-time LQR controller for a resonant system. This is simulated with OrdinaryDiffEq to allow the ODE integrator to also integrate the continuous-time LQR cost (the cost is added as an additional state variable). We then discretize both the system and the cost matrices and simulate the same thing. The discretization of an LQR contorller in this way is sometimes refered to as lqrd.

using ControlSystemsBase, LinearAlgebra, OrdinaryDiffEq, Test
sysc = DemoSystems.resonant()
x0 = ones(sysc.nx)
Qc = [1 0.01; 0.01 2] # Continuous-time cost matrix for the state
Rc = I(1)             # Continuous-time cost matrix for the input

L = lqr(sysc, Qc, Rc)
dynamics = function (xc, p, t)
    x = xc[1:sysc.nx]
    u = -L*x
    dx = sysc.A*x + sysc.B*u
    dc = dot(x, Qc, x) + dot(u, Rc, u)
    return [dx; dc]
end
prob = ODEProblem(dynamics, [x0; 0], (0.0, 10.0))
sol = solve(prob, Tsit5(), reltol=1e-8, abstol=1e-8)
cc = sol.u[end][end] # Continuous-time cost

# Discrete-time version
Ts = 0.01 
sysd = c2d(sysc, Ts)
Qd, Rd = c2d(sysd, Qc, Rc, opt=:c)
Ld = lqr(sysd, Qd, Rd)
sold = lsim(sysd, (x, t) -> -Ld*x, 0:Ts:10, x0 = x0)
function cost(x, u, Q, R)
    dot(x, Q, x) + dot(u, R, u)
end
cd = cost(sold.x, sold.u, Qd, Rd) # Discrete-time cost
@test cc ≈ cd rtol=0.01           # These should be similar

c2d_poly2poly(ro, Ts)

returns the polynomial coefficients in discrete time given polynomial coefficients in continuous time

c2d_roots2poly(ro, Ts)

returns the polynomial coefficients in discrete time given a vector of roots in continuous time

sysd, x0map = c2d_x0map(sys::AbstractStateSpace{<:Continuous}, Ts, method=:zoh; w_prewarp=0)

Returns the discretization sysd of the system sys and a matrix x0map that transforms the initial conditions to the discrete domain by x0_discrete = x0map*[x0; u0]

See c2d for further details.

See output_comp_sensitivity

         ▲
         │e₁
         │  ┌─────┐
d₁────+──┴──►  P  ├─────┬──►e₄
      │     └─────┘     │
      │                 │
      │     ┌─────┐    -│
 e₂◄──┴─────┤  C  ◄──┬──+───d₂
            └─────┘  │
                     │e₃
                     ▼

• input_sensitivity is the transfer function from d₁ to e₁, (I + CP)⁻¹
• output_sensitivity is the transfer function from d₂ to e₃, (I + PC)⁻¹
• input_comp_sensitivity is the transfer function from d₁ to e₂, (I + CP)⁻¹CP
• output_comp_sensitivity is the transfer function from d₂ to e₄, (I + PC)⁻¹PC
• G_PS is the transfer function from d₁ to e₄, (1 + PC)⁻¹P
• G_CS is the transfer function from d₂ to e₂, (1 + CP)⁻¹C

controllability(A, B; atol, rtol)
controllability(sys; atol, rtol)

Check for controllability of the pair (A, B) or sys using the PHB test.

The return value contains the field iscontrollable which is true if the rank condition is met at all eigenvalues of A, and false otherwise. The returned structure also contains the rank and smallest singular value at each individual eigenvalue of A in the fields ranks and sigma_min.

Technically, this function checks for controllability from the origin, also called reachability.

Kp, Ti, Td = convert_pidparams_from_parallel(Kp, Ki, Kd, to_form)

Convert parameters from form :parallel to form to_form.

The form can be chosen as one of the following

• :standard - $K_p(1 + 1/(T_i s) + T_d s)$
• :series - $K_c(1 + 1/(τ_i s))(τ_d s + 1)$
• :parallel - $K_p + K_i/s + K_d s$

param_p, param_i, param_d = convert_pidparams_from_standard(Kp, Ti, Td, form)

Convert parameters to form form from :standard form.

The form can be chosen as one of the following

• :standard - $K_p(1 + 1/(T_i s) + T_d s)$
• :series - $K_c(1 + 1/(τ_i s))(τ_d s + 1)$
• :parallel - $K_p + K_i/s + K_d s$

convert_pidparams_from_to(kp, ki, kd, from::Symbol, to::Symbol)

Convert PID parameters from from form to to form.

The from and to forms can be chosen as one of the following

• :standard - $K_p(1 + 1/(T_i s) + T_d s)$
• :series - $K_c(1 + 1/(τ_i s))(τ_d s + 1)$
• :parallel - $K_p + K_i/s + K_d s$

Kp, Ti, Td = convert_pidparams_to_parallel(param_p, param_i, param_d, form)

Convert parameters from form form to :parallel form.

The form can be chosen as one of the following

• :standard - $K_p(1 + 1/(T_i s) + T_d s)$
• :series - $K_c(1 + 1/(τ_i s))(τ_d s + 1)$
• :parallel - $K_p + K_i/s + K_d s$

Kp, Ti, Td = convert_pidparams_to_standard(param_p, param_i, param_d, form)

Convert parameters from form form to :standard form.

The form can be chosen as one of the following

• :standard - $K_p(1 + 1/(T_i s) + T_ds)$
• :series - $K_c(1 + 1/(τ_i s))(τ_d s + 1)$
• :parallel - $K_p + K_i/s + K_d s$

P = covar(sys, W)

Calculate the stationary covariance P = E[y(t)y(t)'] of the output y of a StateSpace model sys driven by white Gaussian noise w with covariance E[w(t)w(τ)]=W*δ(t-τ) (δ is the Dirac delta).

Remark: If sys is unstable then the resulting covariance is a matrix of Infs. Entries corresponding to direct feedthrough (DWD' .!= 0) will equal Inf for continuous-time systems.

See also innovation_form.

ctrb(A, B)
ctrb(sys)

Compute the controllability matrix for the system described by (A, B) or sys.

Note that checking for controllability by computing the rank from ctrb is not the most numerically accurate way, a better method is checking if gram(sys, :c) is positive definite or to call the function controllability.

The controllable subspace is given by the range of this matrix, and the uncontrollable subspace is nullspace(ctrb(A, B)') (note the transpose).

Qc = d2c(sys::AbstractStateSpace{<:Discrete}, Qd::AbstractMatrix; opt=:o)

Resample discrete-time covariance matrix belonging to sys to the equivalent continuous-time matrix.

The method used comes from theorem 5 in the reference below.

If opt = :c, the matrix is instead assumed to be a cost matrix for an LQR problem.

Ref: Discrete-time Solutions to the Continuous-time Differential Lyapunov Equation With Applications to Kalman Filtering Patrik Axelsson and Fredrik Gustafsson

d2c(sys::AbstractStateSpace{<:Discrete}, method::Symbol = :zoh; w_prewarp=0)

Convert discrete-time system to a continuous time system, assuming that the discrete-time system was discretized using method. Available methods are `:zoh, :fwdeuler´.

• w_prewarp: Frequency for pre-warping when using the Tustin method, has no effect for other methods.

See also d2c_exact.

d2c_exact(sys::AbstractStateSpace{<:Discrete}, method = :causal)

Translate a discrete-time system to a continuous-time system by one of the substitutions

• $z^{-1} = e^{-sT_s}$ if method = :causal (default)
• $z = e^{sT_s}$ if method = :acausal

The translation is exact in the frequency domain, i.e., the frequency response of the resulting continuous-time system is identical to the frequency response of the discrete-time system.

This method of translation is useful when analyzing hybrid continuous/discrete systems in the frequency domain and high accuracy is required.

The resulting system will be be a static system in feedback with pure delays. When method = :causal, the delays will be positive, resulting in a causal system that can be simulated in the time domain. When method = :acausal, the delays will be negative, resulting in an acausal system that can not be simulated in the time domain. The acausal translation results in a smaller system with half as many delay elements in the feedback path.

X,Y = dab(A,B,C)

Solves the Diophantine-Aryabhatta-Bezout identity

$AX + BY = C$, where $A, B, C, X$ and $Y$ are polynomials and $deg Y = deg A - 1$.

See Computer-Controlled Systems: Theory and Design, Third Edition Karl Johan Åström, Björn Wittenmark

Wn, zeta, ps = damp(sys)

Compute the natural frequencies, Wn, and damping ratios, zeta, of the poles, ps, of sys

dampreport(sys)

Display a report of the poles, damping ratio, natural frequency, and time constant of the system sys

dcgain(sys, ϵ=0)

Compute the dcgain of system sys.

equal to G(0) for continuous-time systems and G(1) for discrete-time systems.

ϵ can be provided to evaluate the dcgain with a small perturbation into the stability region of the complex plane.

delay(tau)
delay(tau, Ts)
delay(T::Type{<:Number}, tau)
delay(T::Type{<:Number}, tau, Ts)

Create a pure time delay of length τ of type T.

The type T defaults to promote_type(Float64, typeof(tau)).

If Ts is given, the delay is discretized with sampling time Ts and a discrete-time StateSpace object is returned.

Example:

Create a LTI system with an input delay of L

L = 1
tf(1, [1, 1])*delay(L)
s = tf("s")
tf(1, [1, 1])*exp(-s*L) # Equivalent to the version above

dₘ = delaymargin(G::LTISystem)

Return the delay margin, dₘ. For discrete-time systems, the delay margin is normalized by the sample time, i.e., the value represents the margin in number of sample times. Only supports SISO systems.

The delay margin is computed as the phase margin in radians divided by the cross-over frequency in rad/s. The delay margin is the maximum time delay that can be added to the system before it becomes unstable.

dsys = diagonalize(s::StateSpace, digits=12) Diagonalizes the system such that the A-matrix is diagonal.

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.

extended_gangoffour(P, C, pos=true)

Returns a single statespace system that maps

• w1 reference or measurement noise
• w2 load disturbance

to

• z1 control error
• z2 control input

      z1          z2
      ▲  ┌─────┐  ▲      ┌─────┐
      │  │     │  │      │     │
w1──+─┴─►│  C  ├──┴───+─►│  P  ├─┐
    │    │     │      │  │     │ │
    │    └─────┘      │  └─────┘ │
    │                 w2         │
    └────────────────────────────┘

The returned system has the transfer-function matrix

\[\begin{bmatrix} I \\ C \end{bmatrix} (I + PC)^{-1} \begin{bmatrix} I & P \end{bmatrix}\]

or in code

# For SISO P
S  = G[1, 1]
PS = G[1, 2]
CS = G[2, 1]
T  = G[2, 2]

# For MIMO P
S  = G[1:P.ny,     1:P.nu]
PS = G[1:P.ny,     P.ny+1:end]
CS = G[P.ny+1:end, 1:P.ny]
T  = G[P.ny+1:end, P.ny+1:end] # Input complimentary sensitivity function

The gang of four can be plotted like so

Gcl = extended_gangoffour(G, C) # Form closed-loop system
bodeplot(Gcl, lab=["S" "PS" "CS" "T"], plotphase=false) |> display # Plot gang of four

Note, the last input of Gcl is the negative of the PS and T transfer functions from gangoffour2. To get a transfer matrix with the same sign as G_PS and input_comp_sensitivity, call extended_gangoffour(P, C, pos=false). See glover_mcfarlane from RobustAndOptimalControl.jl for an extended example. See also ncfmargin and feedback_control from RobustAndOptimalControl.jl.

feedback(sys1::AbstractStateSpace, sys2::AbstractStateSpace;
         U1=:, Y1=:, U2=:, Y2=:, W1=:, Z1=:, W2=Int[], Z2=Int[],
         Wperm=:, Zperm=:, pos_feedback::Bool=false)

Basic usefeedback(sys1, sys2) forms the (negative) feedback interconnection

           ┌──────────────┐
◄──────────┤     sys1     │◄──── Σ ◄──────
    │      │              │      │
    │      └──────────────┘      -1
    │                            |
    │      ┌──────────────┐      │
    └─────►│     sys2     ├──────┘
           │              │
           └──────────────┘

If no second system sys2 is given, negative identity feedback (sys2 = 1) is assumed. The returned closed-loop system will have a state vector comprised of the state of sys1 followed by the state of sys2.

Advanced usefeedback also supports more flexible use according to the figure below

              ┌──────────────┐
      z1◄─────┤     sys1     │◄──────w1
 ┌─── y1◄─────┤              │◄──────u1 ◄─┐
 │            └──────────────┘            │
 │                                        α
 │            ┌──────────────┐            │
 └──► u2─────►│     sys2     ├───────►y2──┘
      w2─────►│              ├───────►z2
              └──────────────┘

• U1, W1 specify the indices of the input signals of sys1 corresponding to u1 and w1. W1 contains the indices of the inputs of sys1 that are included among the inputs to the returned system, i.e., external inputs.
• Y1, Z1 specify the indices of the output signals of sys1 corresponding to y1 and z1. Z1 contains the indices of the outputs ofsys1` that are included among the outputs of the returned system, i.e., external outputs.
• U2, W2, Y2, Z2 specify the corresponding signals of sys2. W2 contains the indices of the inputs ofsys2that are included among the inputs to the returned system, i.e., external inputs.Z2contains the indices of the outputs ofsys2` that are included among the outputs of the returned system, i.e., external outputs.

Specify Wperm and Zperm to reorder the inputs (corresponding to [w1; w2]) and outputs (corresponding to [z1; z2]) in the resulting statespace model.

Negative feedback (α = -1) is the default. Specify pos_feedback=true for positive feedback (α = 1).

See also lft, starprod, sensitivity, input_sensitivity, output_sensitivity, comp_sensitivity, input_comp_sensitivity, output_comp_sensitivity, G_PS, G_CS.

The manual section From block diagrams to code contains higher-level instructions on how to use this function. See also RobustAndOptimalControl.jl: Connections using named signals for a higher-level interface.

See Zhou, Doyle, Glover (1996) for similar (somewhat less symmetric) formulas.

feedback(sys)
feedback(sys1, sys2)

For a general LTI-system, feedback forms the negative feedback interconnection

>-+ sys1 +-->
  |      |
 (-)sys2 +

If no second system is given, negative identity feedback is assumed

feedback2dof(P,R,S,T)
feedback2dof(B,A,R,S,T)

• Return BT/(AR+ST) where B and A are the numerator and denominator polynomials of P respectively
• Return BT/(AR+ST)

feedback2dof(P, C, F)

Return the transfer function P(F+C)/(1+PC) which is the closed-loop system with process P, controller C and feedforward filter F from reference to control signal (by-passing C).

         +-------+
         |       |
   +----->   F   +----+
   |     |       |    |
   |     +-------+    |
   |     +-------+    |    +-------+
r  |  -  |       |    |    |       |    y
+--+----->   C   +----+---->   P   +---+-->
      |  |       |         |       |   |
      |  +-------+         +-------+   |
      |                                |
      +--------------------------------+

freqresp!(R::Array{T, 3}, sys::LTISystem, w_vec::AbstractVector{<:Real})

In-place version of freqresp that takes a pre-allocated array R of size (ny, nu, nw)`

sys_fr = freqresp(sys, w)

Evaluate the frequency response of a linear system

w -> C*((iw*im*I - A)^-1)*B + D

of system sys over the frequency vector w.

freqrespv(G::AbstractMatrix, w_vec::AbstractVector{<:Real}; )

For use with SISO systems where it acts the same as freqresp but with the extra dimensions removed in the returned values.

freqrespv(G::Number, w_vec::AbstractVector{<:Real}; )

For use with SISO systems where it acts the same as freqresp but with the extra dimensions removed in the returned values.

freqrespv(sys::LTISystem, w_vec::AbstractVector{W}; )

For use with SISO systems where it acts the same as freqresp but with the extra dimensions removed in the returned values.

S, PS, CS, T = gangoffour(P, C; minimal=true)
gangoffour(P::AbstractVector, C::AbstractVector; minimal=true)

Given a transfer function describing the plant P and a transfer function describing the controller C, computes the four transfer functions in the Gang-of-Four.

• S = 1/(1+PC) Sensitivity function
• PS = (1+PC)\P Load disturbance to measurement signal
• CS = (1+PC)\C Measurement noise to control signal
• T = PC/(1+PC) Complementary sensitivity function

If minimal=true, minreal will be applied to all transfer functions.

fig = gangoffourplot(P::LTISystem, C::LTISystem; minimal=true, plotphase=false, Ms_lines = [1.0, 1.25, 1.5], Mt_lines = [], sigma = true, kwargs...)

Gang-of-Four plot.

sigma determines whether a sigmaplot is used instead of a bodeplot for MIMO S and T. kwargs are sent as argument to RecipesBase.plot.

S, PS, CS, T, RY, RU, RE = gangofseven(P,C,F)

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)

gram(sys, opt; kwargs...)

Compute the grammian of system sys. If opt is :c, computes the controllability grammian. If opt is :o, computes the observability grammian.

See also grampd For keyword arguments, see grampd.

Extended help

Note: Gramian computations are sensitive to input-output scaling. For the result of a numerical balancing, gramian computation or truncation of MIMO systems to be meaningful, the inputs and outputs of the system must thus be scaled in a meaningful way. A common (but not the only) approach is:

• The outputs are scaled such that the maximum allowed control error, the maximum expected reference variation, or the maximum expected variation, is unity.
• The input variables are scaled to have magnitude one. This is done by dividing each variable by its maximum expected or allowed change, i.e., $u_{scaled} = u / u_{max}$

Without such scaling, the result of balancing will depend on the units used to measure the input and output signals, e.g., a change of unit for one output from meter to millimeter will make this output 1000x more important.

U = grampd(sys, opt; kwargs...)

Return a Cholesky factor U of the grammian of system sys. If opt is :c, computes the controllability grammian G = U*U'. If opt is :o, computes the observability grammian G = U'U.

Obtain a Cholesky object by Cholesky(U) for observability grammian

Uses MatrixEquations.plyapc/plyapd. For keyword arguments, see the docstring of ControlSystemsBase.MatrixEquations.plyapc/plyapd

Ninf, ω_peak = hinfnorm(sys; tol=1e-6)

Compute the H∞ norm Ninf of the LTI system sys, together with a frequency ω_peak at which the gain Ninf is achieved.

Ninf := sup_ω σ_max[sys(iω)] if G is stable (σ_max = largest singular value) := Inf' ifG` is unstable

tol is an optional keyword argument for the desired relative accuracy for the computed H∞ norm (not an absolute certificate).

sys is first converted to a state space model if needed.

The continuous-time L∞ norm computation implements the 'two-step algorithm' in:
N.A. Bruinsma and M. Steinbuch, 'A fast algorithm to compute the H∞-norm of a transfer function matrix', Systems and Control Letters (1990), pp. 287-293.

For the discrete-time version, see:
P. Bongers, O. Bosgra, M. Steinbuch, 'L∞-norm calculation for generalized state space systems in continuous and discrete time', American Control Conference, 1991.

See also linfnorm.

y, t, x = impulse(sys[, tfinal])
y, t, x = impulse(sys[, t])

Calculate the response of the system sys to an impulse at time t = 0. For continous-time systems, the impulse is a unit Dirac impulse. For discrete-time systems, the impulse lasts one sample and has magnitude 1/Ts. If the final time tfinal or time vector t is not provided, one is calculated based on the system pole locations.

The return value is a structure of type SimResult. A SimResul can be plotted by plot(result), or destructured as y, t, x = result.

y has size (ny, length(t), nu), x has size (nx, length(t), nu)

See also lsim.

sysi = innovation_form(sys, R1, R2[, R12])
sysi = innovation_form(sys; sysw=I, syse=I, R1=I, R2=I)

Takes a system

x' = Ax + Bu + w ~ R1
y  = Cx + Du + e ~ R2

and returns the system

x' = Ax + Kv
y  = Cx + v

where v is the innovation sequence.

If sysw (syse) is given, the covariance resulting in filtering noise with R1 (R2) through sysw (syse) is used as covariance.

See Stochastic Control, Chapter 4, Åström

sysi = innovation_form(sys, K)

Takes a system

x' = Ax + Bu + Kv
y  = Cx + Du + v

and returns the system

x' = Ax + Kv
y  = Cx + v

where v is the innovation sequence.

See Stochastic Control, Chapter 4, Åström

input_comp_sensitivity(P,C)

Transfer function from load disturbance to control signal.

• "Input" signifies that the transfer function is from the input of the plant.
• "Complimentary" signifies that the transfer function is to an output (in this case controller output)

         ▲
         │e₁
         │  ┌─────┐
d₁────+──┴──►  P  ├─────┬──►e₄
      │     └─────┘     │
      │                 │
      │     ┌─────┐    -│
 e₂◄──┴─────┤  C  ◄──┬──+───d₂
            └─────┘  │
                     │e₃
                     ▼

• input_sensitivity is the transfer function from d₁ to e₁, (I + CP)⁻¹
• output_sensitivity is the transfer function from d₂ to e₃, (I + PC)⁻¹
• input_comp_sensitivity is the transfer function from d₁ to e₂, (I + CP)⁻¹CP
• output_comp_sensitivity is the transfer function from d₂ to e₄, (I + PC)⁻¹PC
• G_PS is the transfer function from d₁ to e₄, (1 + PC)⁻¹P
• G_CS is the transfer function from d₂ to e₂, (1 + CP)⁻¹C

input_names(P)
input_names(P, i)

Get a vector of strings with the names of the inputs of P, or the i:th name if an index is given.

input_resolvent(sys::AbstractStateSpace)

Return the input-mapped resolvent of sys

\[(sI - A)^{-1}B\]

i.e., the system ss(A, B, I, 0).

input_sensitivity(P, C)

Transfer function from load disturbance to total plant input.

• "Input" signifies that the transfer function is from the input of the plant.

         ▲
         │e₁
         │  ┌─────┐
d₁────+──┴──►  P  ├─────┬──►e₄
      │     └─────┘     │
      │                 │
      │     ┌─────┐    -│
 e₂◄──┴─────┤  C  ◄──┬──+───d₂
            └─────┘  │
                     │e₃
                     ▼

• input_sensitivity is the transfer function from d₁ to e₁, (I + CP)⁻¹
• output_sensitivity is the transfer function from d₂ to e₃, (I + PC)⁻¹
• input_comp_sensitivity is the transfer function from d₁ to e₂, (I + CP)⁻¹CP
• output_comp_sensitivity is the transfer function from d₂ to e₄, (I + PC)⁻¹PC
• G_PS is the transfer function from d₁ to e₄, (1 + PC)⁻¹P
• G_CS is the transfer function from d₂ to e₂, (1 + CP)⁻¹C

iscontinuous(sys)

Returns true for a continuous-time system sys, else returns false.

isdiscrete(sys)

Returns true for a discrete-time system sys, else returns false.

isproper(tf)

Returns true if the TransferFunction is proper. This means that order(den)

= order(num))

isstable(sys)

Returns true if sys is stable, else returns false.

kalman(Continuous, A, C, R1, R2)
kalman(Discrete, A, C, R1, R2; direct = false)
kalman(sys, R1, R2; direct = false)

Calculate the optimal asymptotic Kalman gain for the linear-Gaussian model

\[\begin{aligned} dx &= Ax + Bu + w \\ y &= Cx + v \end{aligned}\]

where w is the dynamics noise with covariance R1 and v is the measurement noise with covariance R2.

If direct = true, the observer gain is computed for the pair (A, CA) instead of (A,C). This option is intended to be used together with the option direct = true to observer_controller. Ref: "Computer-Controlled Systems" pp 140. direct = false is sometimes referred to as a "delayed" estimator, while direct = true is a "current" estimator.

To obtain a discrete-time approximation to a continuous-time LQG problem, the function c2d can be used to obtain corresponding discrete-time covariance matrices.

To obtain an LTISystem that represents the Kalman filter, pass the obtained Kalman feedback gain into observer_filter. To obtain an LQG controller, pass the obtained Kalman feedback gain as well as a state-feedback gain computed using lqr into observer_controller.

The args...; kwargs... are sent to the Riccati solver, allowing specification of cross-covariance etc. See ?MatrixEquations.arec/ared for more help.

FAQ

This function requires

• R1 must be positive semi-definite
• R2 must be positive definite
• The pair (A,R1) must not have any uncontrollable modes on the imaginary axis (cont) / unit circle (disc), e.g., there must not be any integrating modes that are not affected through R1. if this condition does not hold, you may get the error "The Hamiltonian matrix is not dichotomic".

laglink(a, M; [Ts])

Returns a phase retarding link, the rule of thumb a = 0.1ωc guarantees less than 6 degrees phase margin loss. The bode curve will go from M, bend down at a/M and level out at 1 for frequencies > a

\[\dfrac{s + a}{s + a/M} = M \dfrac{1 + s/a}{1 + sM/a}\]

leadlink(b, N, K=1; [Ts])

Returns a phase advancing link, the top of the phase curve is located at ω = b√(N) where the link amplification is K√(N) The bode curve will go from K, bend up at b and level out at KN for frequencies > bN

The phase advance at ω = b√(N) can be plotted as a function of N with leadlinkcurve()

Values of N < 1 will give a phase retarding link.

\[KN \dfrac{s + b}{s + bN} = K \dfrac{1 + s/b}{1 + s/(bN)}\]

See also leadlinkatlaglink

leadlinkat(ω, N, K=1; [Ts])

Returns a phase advancing link, the top of the phase curve is located at ω where the link amplification is K√(N) The bode curve will go from K, bend up at ω/√(N) and level out at KN for frequencies > ω√(N)

The phase advance at ω can be plotted as a function of N with leadlinkcurve()

Values of N < 1 will give a phase retarding link.

See also leadlinklaglink

leadlinkcurve(start=1)

Plot the phase advance as a function of N for a lead link (phase advance link) If an input argument start is given, the curve is plotted from start to 10, else from 1 to 10.

See also leadlink, leadlinkat

lft(G, Δ, type=:l)

Lower and upper linear fractional transformation between systems G and Δ.

Specify :l lor lower LFT, and :u for upper LFT.

G must have more inputs and outputs than Δ has outputs and inputs.

For details, see Chapter 9.1 in Zhou, K. and JC Doyle. Essentials of robust control, Prentice hall (NJ), 1998

Ninf, ω_peak = linfnorm(sys; tol=1e-6)

Compute the L∞ norm Ninf of the LTI system sys, together with a frequency ω_peak at which the gain Ninf is achieved.

Ninf := sup_ω σ_max[sys(iω)] (σ_max denotes the largest singular value)

tol is an optional keyword argument representing the desired relative accuracy for the computed L∞ norm (this is not an absolute certificate however).

sys is first converted to a state space model if needed.

The continuous-time L∞ norm computation implements the 'two-step algorithm' in:
N.A. Bruinsma and M. Steinbuch, 'A fast algorithm to compute the H∞-norm of a transfer function matrix', Systems and Control Letters (1990), pp. 287-293.

For the discrete-time version, see:
P. Bongers, O. Bosgra, M. Steinbuch, 'L∞-norm calculation for generalized state space systems in continuous and discrete time', American Control Conference, 1991.

See also hinfnorm.

C, kp, ki, fig, CF = loopshapingPI(P, ωp; ϕl, rl, phasemargin, form=:standard, doplot=false, Tf, F)

Selects the parameters of a PI-controller (on parallel form) such that the Nyquist curve of P at the frequency ωp is moved to rl exp(i ϕl)

The parameters can be returned as one of several common representations chosen by form, the options are

• :standard - $K_p(1 + 1/(T_i s) + T_d s)$
• :series - $K_c(1 + 1/(τ_i s))(τ_d s + 1)$
• :parallel - $K_p + K_i/s + K_d s$

If phasemargin is supplied (in degrees), ϕl is selected such that the curve is moved to an angle of phasemargin - 180 degrees

If no rl is given, the magnitude of the curve at ωp is kept the same and only the phase is affected, the same goes for ϕl if no phasemargin is given.

• Tf: An optional time constant for second-order measurement noise filter on the form tf(1, [Tf^2, 2*Tf/sqrt(2), 1]) to make the controller strictly proper.
• F: A pre-designed filter to use instead of the default second-order filter that is used if Tf is given.
• doplot plot the gangoffourplot and nyquistplot of the system.

See also loopshapingPID, pidplots, stabregionPID and placePI.

C, kp, ki, kd, fig, CF = loopshapingPID(P, ω; Mt = 1.3, ϕt=75, form=:standard, doplot=false, lb=-10, ub=10, Tf = 1/1000ω, F = nothing)

Selects the parameters of a PID-controller such that the Nyquist curve of the loop-transfer function $L = PC$ at the frequency ω is tangent to the circle where the magnitude of $T = PC / (1+PC)$ equals Mt. ϕt denotes the positive angle in degrees between the real axis and the tangent point.

The default values for Mt and ϕt are chosen to give a good design for processes with inertia, and may need tuning for simpler processes.

The gain of the resulting controller is generally increasing with increasing ω and Mt.

Arguments:

• P: A SISO plant.
• ω: The specification frequency.
• Mt: The magnitude of the complementary sensitivity function at the specification frequency, $|T(iω)|$.
• ϕt: The positive angle in degrees between the real axis and the tangent point.
• doplot: If true, gang of four and Nyquist plots will be returned in fig.
• lb: log10 of lower bound for kd.
• ub: log10 of upper bound for kd.
• Tf: Time constant for second-order measurement noise filter on the form tf(1, [Tf^2, 2*Tf/sqrt(2), 1]) to make the controller strictly proper. A practical controller typically sets this time constant slower than the default, e.g., Tf = 1/100ω or Tf = 1/10ω
• F: A pre-designed filter to use instead of the default second-order filter.

The parameters can be returned as one of several common representations chosen by form, the options are

• :standard - $K_p(1 + 1/(T_i s) + T_ds)$
• :series - $K_c(1 + 1/(τ_i s))(τ_d s + 1)$
• :parallel - $K_p + K_i/s + K_d s$

See also loopshapingPI, pidplots, stabregionPID and placePI.

Example:

P  = tf(1, [1,0,0]) # A double integrator
Mt = 1.3  # Maximum magnitude of complementary sensitivity
ω  = 1    # Frequency at which the specification holds
C, kp, ki, kd, fig, CF = loopshapingPID(P, ω; Mt, ϕt = 75, doplot=true)

lqr(sys, Q, R)
lqr(Continuous, A, B, Q, R, args...; kwargs...)
lqr(Discrete, A, B, Q, R, args...; kwargs...)

Calculate the optimal gain matrix K for the state-feedback law u = -K*x that minimizes the cost function:

J = integral(x'Qx + u'Ru, 0, inf) for the continuous-time model dx = Ax + Bu. J = sum(x'Qx + u'Ru, 0, inf) for the discrete-time model x[k+1] = Ax[k] + Bu[k].

Solve the LQR problem for state-space system sys. Works for both discrete and continuous time systems.

The args...; kwargs... are sent to the Riccati solver, allowing specification of cross-covariance etc. See ?MatrixEquations.arec / ared for more help.

To obtain also the solution to the Riccati equation and the eigenvalues of the closed-loop system as well, call ControlSystemsBase.MatrixEquations.arec / ared instead (note the different order of the arguments to these functions).

To obtain a discrete-time approximation to a continuous-time LQR problem, the function c2d can be used to obtain corresponding discrete-time cost matrices.

Examples

Continuous time

using LinearAlgebra # For identity matrix I
using Plots
A = [0 1; 0 0]
B = [0; 1]
C = [1 0]
sys = ss(A,B,C,0)
Q = I
R = I
L = lqr(sys,Q,R) # lqr(Continuous,A,B,Q,R) can also be used

u(x,t) = -L*x # Form control law,
t=0:0.1:5
x0 = [1,0]
y, t, x, uout = lsim(sys,u,t,x0=x0)
plot(t,x', lab=["Position" "Velocity"], xlabel="Time [s]")

Discrete time

using LinearAlgebra # For identity matrix I
using Plots
Ts = 0.1
A = [1 Ts; 0 1]
B = [0;1]
C = [1 0]
sys = ss(A, B, C, 0, Ts)
Q = I
R = I
L = lqr(Discrete, A,B,Q,R) # lqr(sys,Q,R) can also be used

u(x,t) = -L*x # Form control law,
t=0:Ts:5
x0 = [1,0]
y, t, x, uout = lsim(sys,u,t,x0=x0)
plot(t,x', lab=["Position"  "Velocity"], xlabel="Time [s]")

FAQ

This function requires

• Q must be positive semi-definite
• R must be positive definite
• The pair (Q,A) must not have any unobservable modes on the imaginary axis (cont) / unit circle (disc), e.g., there must not be any integrating modes that are not penalized by Q. if this condition does not hold, you may get the error "The Hamiltonian matrix is not dichotomic".

res = lsim!(ws::LsimWorkspace, sys::AbstractStateSpace{<:Discrete}, u, [t]; x0)

In-place version of lsim that takes a workspace object created by calling LsimWorkspace. Notice, if u is a function, res.u === ws.u. If u is an array, res.u === u.

result = lsim(sys, u[, t]; x0, method])
result = lsim(sys, u::Function, t; x0, method)

Calculate the time response of system sys to input u. If x0 is omitted, a zero vector is used.

The result structure contains the fields y, t, x, u and can be destructured automatically by iteration, e.g.,

y, t, x, u = result

result::SimResult can also be plotted directly:

plot(result, plotu=true, plotx=false)

y, x, u have time in the second dimension. Initial state x0 defaults to zero.

Continuous-time systems are simulated using an ODE solver if u is a function (requires using ControlSystems). If u is an array, the system is discretized (with method=:zoh by default) before simulation. For a lower-level interface, see ?Simulator and ?solve. For continuous-time systems, keyword arguments are forwarded to the ODE solver. By default, the option dtmax = t[2]-t[1] is used to prevent the solver from stepping over discontinuities in u(x, t). This prevents the solver from taking too large steps, but may also slow down the simulation when u is smooth. To disable this behavior, set dtmax = Inf.

u can be a function or a matrix of precalculated control signals and must have dimensions (nu, length(t)). If u is a function, then u(x,i) (for discrete systems) or u(x,t) (for continuous ones) is called to calculate the control signal at every iteration (time instance used by solver). This can be used to provide a control law such as state feedback u(x,t) = -L*x calculated by lqr. To simulate a unit step at t=t₀, use (x,t)-> t ≥ t₀, for a ramp, use (x,t)-> t, for a step at t=5, use (x,t)-> (t >= 5) etc.

Note: The function u will be called once before simulating to verify that it returns an array of the correct dimensions. This can cause problems if u is stateful or has other side effects. You can disable this check by passing check_u = false.

For maximum performance, see function lsim!, available for discrete-time systems only.

Usage example:

using ControlSystems
using LinearAlgebra: I
using Plots

A = [0 1; 0 0]
B = [0;1]
C = [1 0]
sys = ss(A,B,C,0)
Q = I
R = I
L = lqr(sys,Q,R)

u(x,t) = -L*x # Form control law
t  = 0:0.1:5
x0 = [1,0]
y, t, x, uout = lsim(sys,u,t,x0=x0)
plot(t,x', lab=["Position" "Velocity"], xlabel="Time [s]")

# Alternative way of plotting
res = lsim(sys,u,t,x0=x0)
plot(res)

wgm, gm, wpm, pm = margin(sys::LTISystem, w::Vector; full=false, allMargins=false, adjust_phase_start=true)

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
• adjust_phase_start: If true, the phase will be adjusted so that it starts at -90*intexcess degrees, where intexcess is the integrator excess of the system.

See also delaymargin and RobustAndOptimalControl.diskmargin

g_m, ϕ_m = margin_bounds(M_S)

Compute the phase margin lower bound ϕm (in radians) and gain margin lower bound gm given a maximum sensitivity peak $M_S = ||S||_∞$. These bounds are derived from the fact that the inverse of the sensitivity function is the distance from the open-loop Nyquist curve to the critical point -1.

See also Ms_from_phase_margin and Ms_from_gain_margin for the inverse functions. The circle corresponding to the maximum sensitivity peak $M_S$ can be plotted in nyquistplot by passing the keyword argument Ms_circles = [Ms].

fig = marginplot(sys::LTISystem [,w::AbstractVector];  balance=true, kwargs...)
marginplot(sys::Vector{LTISystem}, w::AbstractVector;  balance=true, kwargs...)

Plot all the amplitude and phase margins of the system(s) sys.

• A frequency vector w can be optionally provided.
• balance: Call balance_statespace on the system before plotting.
• adjust_phase_start: If true, the phase will be adjusted so that it starts at -90*intexcess degrees, where intexcess is the integrator excess of the system.

kwargs is sent as argument to RecipesBase.plot.

markovparam(sys, n)

Compute the nth markov parameter of discrete-time state-space system sys. This is defined as the following:

h(0) = D

h(n) = C*A^(n-1)*B

minreal(tf::TransferFunction, eps=sqrt(eps()))

Create a minimal representation of each transfer function in tf by cancelling poles and zeros will promote system to an appropriate numeric type

minreal(sys::StateSpace; fast=false, balance=true, kwargs...)

Minimal realisation algorithm from P. Van Dooreen, The generalized eigenstructure problem in linear system theory, IEEE Transactions on Automatic Control

For information about the options, see ?ControlSystemsBase.MatrixPencils.lsminreal

See also sminreal, which is both numerically exact and substantially faster than minreal, but with a much more limited potential in removing non-minimal dynamics.

fig = nicholsplot{T<:LTISystem}(systems::Vector{T}, w::AbstractVector; kwargs...)

Create a Nichols plot of the LTISystem(s). A frequency vector w can be optionally provided.

Keyword arguments:

text = true
Gains = [12, 6, 3, 1, 0.5, -0.5, -1, -3, -6, -10, -20, -40, -60]
pInc = 30
sat = 0.4
val = 0.85
fontsize = 10

pInc determines the increment in degrees between phase lines.

sat ∈ [0,1] determines the saturation of the gain lines

val ∈ [0,1] determines the brightness of the gain lines

Additional keyword arguments are sent to the function plotting the systems and can be used to specify colors, line styles etc. using regular RecipesBase.jl syntax

This function is based on code subject to the two-clause BSD licence Copyright 2011 Will Robertson Copyright 2011 Philipp Allgeuer

nonlinearity(f)
nonlinearity(T, f)

Create a pure nonlinearity. f is assumed to be a static (no memory) nonlinear function from $f : R -> R$.

The type T defaults to Float64.

NOTE: The nonlinear functionality in ControlSystemsBase.jl is currently experimental and subject to breaking changes not respecting semantic versioning. Use at your own risk.

Example:

Create a LTI system with a static input nonlinearity that saturates the input to [-1,1].

tf(1, [1, 1])*nonlinearity(x->clamp(x, -1, 1))

See also predefined nonlinearities saturation, offset.

Note: when composing linear systems with nonlinearities, it's often important to handle operating points correctly. See ControlSystemsBase.offset for handling operating points.

re, im, w = nyquist(sys[, w])

Compute the real and imaginary parts of the frequency response of system sys at frequencies w. See also nyquistplot

re and im has size (ny, nu, length(w))

fig = nyquistplot(sys;                Ms_circles=Float64[], Mt_circles=Float64[], unit_circle=false, hz=false, critical_point=-1, kwargs...)
nyquistplot(LTISystem[sys1, sys2...]; Ms_circles=Float64[], Mt_circles=Float64[], unit_circle=false, hz=false, critical_point=-1, kwargs...)

Create a Nyquist plot of the LTISystem(s). A frequency vector w can be optionally provided.

• unit_circle: if the unit circle should be displayed. The Nyquist curve crosses the unit circle at the gain crossover frequency.
• Ms_circles: draw circles corresponding to given levels of sensitivity (circles around -1 with radii 1/Ms). Ms_circles can be supplied as a number or a vector of numbers. A design staying outside such a circle has a phase margin of at least 2asin(1/(2Ms)) rad and a gain margin of at least Ms/(Ms-1). See also margin_bounds, Ms_from_phase_margin and Ms_from_gain_margin.
• Mt_circles: draw circles corresponding to given levels of complementary sensitivity. Mt_circles can be supplied as a number or a vector of numbers.
• critical_point: point on real axis to mark as critical for encirclements
• If hz=true, the hover information will be displayed in Hertz, the input frequency vector is still treated as rad/s.
• balance: Call balance_statespace on the system before plotting.

kwargs is sent as argument to plot.

nyquistv(sys::LTISystem, w::AbstractVector; )

For use with SISO systems where it acts the same as nyquist but with the extra dimensions removed in the returned values.

nyquistv(sys::LTISystem; )

For use with SISO systems where it acts the same as nyquist but with the extra dimensions removed in the returned values.

observability(A, C; atol, rtol)

Check for observability of the pair (A, C) or sys using the PHB test.

The return value contains the field isobservable which is true if the rank condition is met at all eigenvalues of A, and false otherwise. The returned structure also contains the rank and smallest singular value at each individual eigenvalue of A in the fields ranks and sigma_min.

cont = observer_controller(sys, L::AbstractMatrix, K::AbstractMatrix; direct=false)

If direct = false

Return the observer_controller cont that is given by ss(A - B*L - K*C + K*D*L, K, L, 0) such that feedback(sys, cont) produces a closed-loop system with eigenvalues given by A-KC and A-BL.

This controller does not have a direct term, and corresponds to state feedback operating on state estimated by observer_predictor. Use this form if the computed control signal is applied at the next sampling instant, or with an otherwise large delay in relation to the measurement fed into the controller.

Ref: "Computer-Controlled Systems" Eq 4.37

If direct = true

Return the observer controller cont that is given by ss((I-KC)(A-BL), (I-KC)(A-BL)K, L, LK) such that feedback(sys, cont) produces a closed-loop system with eigenvalues given by A-BL and A-BL-KC. This controller has a direct term, and corresponds to state feedback operating on state estimated by observer_filter. Use this form if the computed control signal is applied immediately after receiveing a measurement. This version typically has better performance than the one without a direct term.

Ref: Ref: "Computer-Controlled Systems" pp 140 and "Computer-Controlled Systems" pp 162 prob 4.7

Arguments:

• sys: Model of system
• L: State-feedback gain u = -Lx
• K: Observer gain

See also observer_predictor and innovation_form.

observer_filter(sys, K; output_state = false)

Return the observer filter

\[\begin{aligned} x̂(k|k) &= (I - KC)Ax̂(k-1|k-1) + (I - KC)Bu(k-1) + Ky(k) \\ \end{aligned}\]

with the input equation [(I - KC)B K] * [u(k-1); y(k)].

Note the time indices in the equations, the filter assumes that the user passes the current$y(k)$, but the past$u(k-1)$, that is, this filter is used to estimate the state before the current control input has been applied. This causes a state-feedback controller acting on the estimate produced by this observer to have a direct term.

This is similar to observer_predictor, but in contrast to the predictor, the filter output depends on the current measurement, whereas the predictor output only depend on past measurements.

The observer filter is equivalent to the observer_predictor for continuous-time systems.

Ref: "Computer-Controlled Systems" Eq 4.32

observer_predictor(sys::AbstractStateSpace, K; h::Int = 1, output_state = false)
observer_predictor(sys::AbstractStateSpace, R1, R2[, R12]; output_state = false)

If sys is continuous, return the observer predictor system

\[\begin{aligned} x̂' &= (A - KC)x̂ + (B-KD)u + Ky \\ ŷ &= Cx + Du \end{aligned}\]

with the input equation [B-KD K] * [u; y]

If sys is discrete, the prediction horizon h may be specified, in which case measurements up to and including time t-h and inputs up to and including time t are used to predict y(t).

If covariance matrices R1, R2 are given, the kalman gain K is calculated using kalman.

If output_state is true, the output is the state estimate x̂ instead of the output estimate ŷ.

See also innovation_form, observer_controller and observer_filter.

obsv(A, C, n=size(A,1))
obsv(sys, n=sys.nx)

Compute the observability matrix with n rows for the system described by (A, C) or sys. Providing the optional n > sys.nx returns an extended observability matrix.

Note that checking for observability by computing the rank from obsv is not the most numerically accurate way, a better method is checking if gram(sys, :o) is positive definite or to call the function observability.

The unobservable subspace is nullspace(obsv(A, C)), initial conditions in this subspace produce a zero response.

output_comp_sensitivity(P,C)

Transfer function from measurement noise / reference to plant output.

• "output" signifies that the transfer function is from the output of the plant.
• "Complimentary" signifies that the transfer function is to an output (in this case plant output)

         ▲
         │e₁
         │  ┌─────┐
d₁────+──┴──►  P  ├─────┬──►e₄
      │     └─────┘     │
      │                 │
      │     ┌─────┐    -│
 e₂◄──┴─────┤  C  ◄──┬──+───d₂
            └─────┘  │
                     │e₃
                     ▼

• input_sensitivity is the transfer function from d₁ to e₁, (I + CP)⁻¹
• output_sensitivity is the transfer function from d₂ to e₃, (I + PC)⁻¹
• input_comp_sensitivity is the transfer function from d₁ to e₂, (I + CP)⁻¹CP
• output_comp_sensitivity is the transfer function from d₂ to e₄, (I + PC)⁻¹PC
• G_PS is the transfer function from d₁ to e₄, (1 + PC)⁻¹P
• G_CS is the transfer function from d₂ to e₂, (1 + CP)⁻¹C

output_names(P)
output_names(P, i)

Get a vector of strings with the names of the outputs of P, or the i:th name if an index is given.

output_sensitivity(P, C)

Transfer function from measurement noise / reference to control error.

• "output" signifies that the transfer function is from the output of the plant.

         ▲
         │e₁
         │  ┌─────┐
d₁────+──┴──►  P  ├─────┬──►e₄
      │     └─────┘     │
      │                 │
      │     ┌─────┐    -│
 e₂◄──┴─────┤  C  ◄──┬──+───d₂
            └─────┘  │
                     │e₃
                     ▼

• input_sensitivity is the transfer function from d₁ to e₁, (I + CP)⁻¹
• output_sensitivity is the transfer function from d₂ to e₃, (I + PC)⁻¹
• input_comp_sensitivity is the transfer function from d₁ to e₂, (I + CP)⁻¹CP
• output_comp_sensitivity is the transfer function from d₂ to e₄, (I + PC)⁻¹PC
• G_PS is the transfer function from d₁ to e₄, (1 + PC)⁻¹P
• G_CS is the transfer function from d₂ to e₂, (1 + CP)⁻¹C

pade(G::DelayLtiSystem, N)

Approximate all time-delays in G by Padé approximations of degree N.

pade(τ::Real, N_num::Int, N_den::Int)

Compute the Padé approximation of a time-delay of length τ with N_num and N_den degrees in the numerator and denominator, respectively.

pade(τ::Real, N::Int)

Compute the Nth order Padé approximation of a time-delay of length τ.

See also thiran for discretization of delays.

parallel(sys1::LTISystem, sys2::LTISystem)

Connect systems in parallel, equivalent to sys2+sys1

C = pid(param_p, param_i, [param_d]; form=:standard, state_space=false, [Tf], [Ts], filter_order=2, d=1/√(2))

Calculates and returns a PID controller.

The form can be chosen as one of the following (determines how the arguments param_p, param_i, param_d are interpreted)

• :standard - $K_p(1 + 1/(T_i s) + T_d s)$
• :series - $K_c(1 + 1/(τ_i s))(τ_d s + 1)$
• :parallel - $K_p + K_i/s + K_d s$

If state_space is set to true, either Kd has to be zero or a positive Tf has to be provided for creating a filter on the input to allow for a state-space realization. A balanced state-space realization is returned, unless balance = false.

Filter

If Tf is supplied, a filter is added, the filter used is either

• filter_order = 2 (default): $1 / ((sT_f)^2/(4d^2) + sT_f + 1)$ in series with the controller. Note: this parametrization of the filter differs in behavior from the common parameterizaiton $1/(s^2 + 2dws + w^2)$ as the parameters vary, the former maintains an almost fixed bandwidth while d varies, while the latter maintains a fixed distance of the poles from the origin.
• filter_order = 1: $1 / (1 + sT_f)$ applied to the derivative term only

$T_f$ can typically be chosen as $T_i/N$ for a PI controller and $T_d/N$ for a PID controller, and N is commonly in the range 2 to 20. With a second-order filter, d controls the damping. d = 1/√(2) gives a Butterworth configuration of the poles, and d=1 gives a critically damped filter (no overshoot). d above one may be used, although d > 1 yields an increasingly over-damped filter (this parametrization does not send one pole to the origin $d → ∞$ like the $(ω,ζ)$ parametrization does).

Discrete-time

For a discrete controller a positive Ts can be supplied. In this case, the continuous-time controller is discretized using the Tustin method.

Examples

C1 = pid(3.3, 1, 2)                             # Kd≠0 works without filter in tf form
C2 = pid(3.3, 1, 2; Tf=0.3, state_space=true)   # In statespace a filter is needed
C3 = pid(2.,  3, 0; Ts=0.4, state_space=true)   # Discrete

The functions pid_tf and pid_ss are also exported. They take the same parameters and is what is actually called in pid based on the state_space parameter. See also pid_2dof for a 2DOF controller with inputs [r; y] and outputs u.

C = pid_2dof(param_p, param_i, [param_d]; form=:standard, state_space=true, N = 10, [Ts], b=1, c=0, disc=:tustin)

Calculates and returns a PID controller on 2DOF form with inputs [r; y] and outputs u where r is the reference signal, y is the measured output and u is the control signal.

Belowm we show two different depections of the contorller, one as a 2-input system (left) and one where the tw internal SISO systems of the controller are shown (right).

                                ┌──────┐                      
                             r  │      │                      
                            ───►│  Cr  ├────┐                 
r  ┌─────┐     ┌─────┐          │      │    │    ┌─────┐      
──►│     │  u  │     │ y        └──────┘    │    │     │ y    
   │  C  ├────►│  P  ├─┬─►                  +───►│  P  ├─┬───►
 ┌►│     │     │     │ │        ┌──────┐    │    │     │ │    
 │ └─────┘     └─────┘ │      y │      │    │    └─────┘ │    
 │                     │     ┌─►│  Cy  ├────┘            │    
 └─────────────────────┘     │  │      │                 │    
                             │  └──────┘                 │    
                             │                           │    
                             └───────────────────────────┘     

The form can be chosen as one of the following (determines how the arguments param_p, param_i, param_d are interpreted)

• :standard - $K_p(br-y + (r-y)/(T_i s) + T_d s (cr-y)/(T_f s + 1))$

• :parallel - $K_p(br-y) + K_i (r-y)/s + K_d s (cr-y)/(Tf s + 1)$

• b is a set-point weighting for the proportional term

• c is a set-point weighting for the derivative term, this defaults to 0.

• If both b and c are set to zero, the feedforward path of the controller will be strictly proper.

• Tf is a time constant for a filter on the derivative term, this defaults to Td/N where N is set to 10. Instead of passing Tf one can also pass N directly. The proportional term is not affected by this filter. Please note: this derivative filter is not the same as the one used in the pid function, where the filter is of second order and applied in series with the contorller, i.e., it affects all three PID terms.

• A PD controller is constructed by setting param_i to zero.

• A balanced state-space realization is returned, unless balance = false

• If Ts is supplied, the controller is discretized using the method disc (defaults to :tustin).

This controller has negative feedback built in, and the closed-loop system from r to y is thus formed as

Cr, Cy = C[1, 1], C[1, 2]
feedback(P, Cy, pos_feedback=true)*Cr                    # Alternative 1
feedback(P, -Cy)*Cr                                      # Alternative 2
feedback(P, C, U2=2, W2=1, W1=[], pos_feedback=true) # Alternative 3, less pretty but more efficient, returns smaller realization

pidplots(P, args...; params_p, params_i, params_d=0, form=:standard, ω=0, grid=false, kwargs...)

Display the relevant plots related to closing the loop around process P with a PID controller supplied in params on one of the following forms:

• :standard - Kp*(1 + 1/(Ti*s) + Td*s)
• :series - Kc*(1 + 1/(τi*s))*(τd*s + 1)
• :parallel - Kp + Ki/s + Kd*s

The sent in values can be arrays to evaluate multiple different controllers, and if grid=true it will be a grid search over all possible combinations of the values.

Available plots are :gof for Gang of four, :nyquist, :controller for a bode plot of the controller TF and :pz for pole-zero maps and should be supplied as additional arguments to the function.

One can also supply a frequency vector ω to be used in Bode and Nyquist plots.

See also loopshapingPI, stabregionPID

place(A, B, p, opt=:c; direct = false)
place(sys::StateSpace, p, opt=:c; direct = false)

Calculate the gain matrix K such that A - BK has eigenvalues p.

place(A, C, p, opt=:o)
place(sys::StateSpace, p, opt=:o)

Calculate the observer gain matrix L such that A - LC has eigenvalues p.

If direct = true and opt = :o, the the observer gain K is calculated such that A - KCA has eigenvalues p, this option is to be used together with direct = true in observer_controller.

Note: only apply direct = true to discrete-time systems.

Ref: "Computer-Controlled Systems" pp 140.

Uses Ackermann's formula for SISO systems and place_knvd for MIMO systems.

Please note that this function can be numerically sensitive, solving the placement problem in extended precision might be beneficial.

C, kp, ki = placePI(P, ω₀, ζ; form=:standard)

Selects the parameters of a PI-controller such that the poles of closed loop between P and C are placed to match the poles of s^2 + 2ζω₀s + ω₀^2.

The parameters can be returned as one of several common representations chose by form, the options are

• :standard - $K_p(1 + 1/(T_i s))$
• :series - $K_c(1 + 1/(τ_i s))$ (equivalent to above for PI controllers)
• :parallel - $K_p + K_i/s$

C is the returned transfer function of the controller and params is a named tuple containing the parameters. The parameters can be accessed as params.Kp or params["Kp"] from the named tuple, or they can be unpacked using Kp, Ti, Td = values(params).

See also loopshapingPI

place_knvd(A::AbstractMatrix, B, λ; verbose = false, init = :s)

Robust pole placement using the algorithm from

"Robust Pole Assignment in Linear State Feedback", Kautsky, Nichols, Van Dooren

This implementation uses "method 0" for the X-step and the QR factorization for all factorizations.

This function will be called automatically when place is called with a MIMO system.

Arguments:

• init: Determines the initialization strategy for the iterations for find the X matrix. Possible choices are :id, :rand, :s (default).

Xc = plyap(sys::AbstractStateSpace, Ql; kwargs...)

Lyapunov solver that takes the L Cholesky factor of Q and returns a triangular matrix Xc such that Xc*Xc' = X.

poles(sys)

Compute the poles of system sys.

Note: Poles with multiplicity n > 1 may suffer numerical inaccuracies on the order eps(numeric_type(sys))^(1/n), i.e., a double pole in a system with Float64 coefficients may be computed with an error of about √(eps(Float64)) ≈ 1.5e-8.

To compute the poles of a system with non-BLAS floats, such as BigFloat, install and load the package GenericSchur.jl before calling poles.

fig = pzmap(fig, system, args...; hz = false, kwargs...)

Create a pole-zero map of the LTISystem(s) in figure fig, args and kwargs will be sent to the scatter plot command.

To customize the unit-circle drawn for discrete systems, modify the line attributes, e.g., linecolor=:red.

If hz is true, all poles and zeros are scaled by 1/2π.

relative_gain_array(A::AbstractMatrix; tol = 1.0e-15)

Reference: "On the Relative Gain Array (RGA) with Singular and Rectangular Matrices" Jeffrey Uhlmann https://arxiv.org/pdf/1805.10312.pdf

relative_gain_array(G, w::AbstractVector)
relative_gain_array(G, w::Number)

Calculate the relative gain array of G at frequencies w. G(iω) .* pinv(tranpose(G(iω)))

The RGA can be used to find input-output pairings for MIMO control using individually tuned loops. Pair the inputs and outputs such that the RGA(ωc) at the crossover frequency becomes as close to diagonal as possible. Avoid pairings such that RGA(0) contains negative diagonal elements.

• The sum of the absolute values of the entries in the RGA is a good measure of the "true condition number" of G, the best condition number that can be achieved by input/output scaling of G, -Glad, Ljung.
• The RGA is invariant to input/output scaling of G.
• If the RGA contains large entries, the system may be sensitive to model errors, -Skogestad, "Multivariable Feedback Control: Analysis and Design":
  • Uncertainty in the input channels (diagonal input uncertainty). Plants with
  large RGA-elements around the crossover frequency are fundamentally difficult to control because of sensitivity to input uncertainty (e.g. caused by uncertain or neglected actuator dynamics). In particular, decouplers or other inverse-based controllers should not be used for plants with large RGAeleme
  • Element uncertainty. Large RGA-elements imply sensitivity to element-by-element uncertainty.
  However, this kind of uncertainty may not occur in practice due to physical couplings between the transfer function elements. Therefore, diagonal input uncertainty (which is always present) is usually of more concern for plants with large RGA elements.

The relative gain array is computed using the The unit-consistent (UC) generalized inverse Reference: "On the Relative Gain Array (RGA) with Singular and Rectangular Matrices" Jeffrey Uhlmann https://arxiv.org/pdf/1805.10312.pdf

resolvent(sys::AbstractStateSpace)

Return the resolvent of sys

\[(sI - A)^{-1}\]

i.e., the system ss(A, I, I, 0).

See also input_resolvent.

rgaplot(sys, args...; hz=false)
rgaplot(LTISystem[sys1, sys2...], args...; hz=false, balance=true)

Plot the relative-gain array entries of the LTISystem(s). A frequency vector w can be optionally provided.

• If hz=true, the plot x-axis will be displayed in Hertz, the input frequency vector is still treated as rad/s.
• balance: Call balance_statespace on the system before plotting.

kwargs is sent as argument to Plots.plot.

See ?rstd for the discrete case

R,S,T = rstd(BPLUS,BMINUS,A,BM1,AM,AO,AR,AS)
R,S,T = rstd(BPLUS,BMINUS,A,BM1,AM,AO,AR)
R,S,T = rstd(BPLUS,BMINUS,A,BM1,AM,AO)

Polynomial synthesis in discrete time.

Polynomial synthesis according to "Computer-Controlled Systems" ch 10 to design a controller $R(q) u(k) = T(q) r(k) - S(q) y(k)$

Inputs:

• BPLUS : Part of open loop numerator
• BMINUS : Part of open loop numerator
• A : Open loop denominator
• BM1 : Additional zeros
• AM : Closed loop denominator
• AO : Observer polynomial
• AR : Pre-specified factor of R,

e.g integral part [1, -1]^k

• AS : Pre-specified factor of S,

e.g notch filter [1, 0, w^2]

Outputs: R,S,T : Polynomials in controller

See function dab how the solution to the Diophantine- Aryabhatta-Bezout identity is chosen.

See Computer-Controlled Systems: Theory and Design, Third Edition Karl Johan Åström, Björn Wittenmark

See output_sensitivity

The output sensitivity function$S_o = (I + PC)^{-1}$ is the transfer function from a reference input to control error, while the input sensitivity function $S_i = (I + CP)^{-1}$ is the transfer function from a disturbance at the plant input to the total plant input. For SISO systems, input and output sensitivity functions are equal. In general, we want to minimize the sensitivity function to improve robustness and performance, but practical constraints always cause the sensitivity function to tend to 1 for high frequencies. A robust design minimizes the peak of the sensitivity function, $M_S$. The peak magnitude of $S$ is the inverse of the distance between the open-loop Nyquist curve and the critical point -1. Upper bounding the sensitivity peak $M_S$ gives lower-bounds on phase and gain margins according to

\[ϕ_m ≥ 2\text{sin}^{-1}(\frac{1}{2M_S}), g_m ≥ \frac{M_S}{M_S-1}\]

(see margin_bounds for a function that computes these bounds, and Ms_from_phase_margin and Ms_from_gain_margin for the inverse functions.) Generally, bounding $M_S$ is a better objective than looking at gain and phase margins due to the possibility of combined gain and pahse variations, which may lead to poor robustness despite large gain and pahse margins.

         ▲
         │e₁
         │  ┌─────┐
d₁────+──┴──►  P  ├─────┬──►e₄
      │     └─────┘     │
      │                 │
      │     ┌─────┐    -│
 e₂◄──┴─────┤  C  ◄──┬──+───d₂
            └─────┘  │
                     │e₃
                     ▼

• input_sensitivity is the transfer function from d₁ to e₁, (I + CP)⁻¹
• output_sensitivity is the transfer function from d₂ to e₃, (I + PC)⁻¹
• input_comp_sensitivity is the transfer function from d₁ to e₂, (I + CP)⁻¹CP
• output_comp_sensitivity is the transfer function from d₂ to e₄, (I + PC)⁻¹PC
• G_PS is the transfer function from d₁ to e₄, (1 + PC)⁻¹P
• G_CS is the transfer function from d₂ to e₂, (1 + CP)⁻¹C

series(sys1::LTISystem, sys2::LTISystem)

Connect systems in series, equivalent to sys2*sys1

setPlotScale(str)

Set the default scale of magnitude in bodeplot and sigmaplot. str should be either "dB" or "log10". The default scale if none is chosen is "log10".

sv, w = sigma(sys[, w])

Compute the singular values sv of the frequency response of system sys at frequencies w. See also sigmaplot

sv has size (min(ny, nu), length(w))

sigmaplot(sys, args...; hz=false balance=true, extrema)
sigmaplot(LTISystem[sys1, sys2...], args...; hz=false, balance=true, extrema)

Plot the singular values of the frequency response of the LTISystem(s). A frequency vector w can be optionally provided.

• If hz=true, the plot x-axis will be displayed in Hertz, the input frequency vector is still treated as rad/s.
• balance: Call balance_statespace on the system before plotting.
• extrema: Only plot the largest and smallest singular values.

kwargs is sent as argument to Plots.plot.

sigmav(sys::LTISystem, w::AbstractVector; )

For use with SISO systems where it acts the same as sigma but with the extra dimensions removed in the returned values.

sigmav(sys::LTISystem; )

For use with SISO systems where it acts the same as sigma but with the extra dimensions removed in the returned values.

syst = similarity_transform(sys, T; unitary=false)

Perform a similarity transform T : Tx̃ = x on sys such that

à = T⁻¹AT
B̃ = T⁻¹ B
C̃ = CT
D̃ = D

If unitary=true, T is assumed unitary and the matrix adjoint is used instead of the inverse. See also balance_statespace.

sminreal(sys)

Compute the structurally minimal realization of the state-space system sys. A structurally minimal realization is one where only states that can be determined to be uncontrollable and unobservable based on the location of 0s in sys are removed.

Systems with numerical noise in the coefficients, e.g., noise on the order of eps require truncation to zero to be affected by structural simplification, e.g.,

trunc_zero!(A) = A[abs.(A) .< 10eps(maximum(abs, A))] .= 0
trunc_zero!(sys.A); trunc_zero!(sys.B); trunc_zero!(sys.C)
sminreal(sys)

In contrast to minreal, which performs pole-zero cancellation using linear-algebra operations, has an 𝑂(nₓ^3) complexity and is subject to numerical tolerances, sminreal is computationally very cheap and numerically exact (operates on integers). However, the ability of sminreal to reduce the order of the model is much less powerful.

See also minreal.

sys = ss(A, B, C, D)      # Continuous
sys = ss(A, B, C, D, Ts)  # Discrete
sys = ss(P::TransferFunction; balance=true, minimal=false) # Convert TransferFunction to StateSpace

Create a state-space model sys::StateSpace{TE, T} with matrix element type T and TE is Continuous or <:Discrete.

This is a continuous-time model if Ts is omitted. Otherwise, this is a discrete-time model with sampling period Ts.

D may be specified as 0 in which case a zero matrix of appropriate size is constructed automatically. sys = ss(D [, Ts]) specifies a static gain matrix D.

When a transfer function P is converted to a state-space model, the user may choose whether to balance the state-space model (default=true) and/or to return a minimal realization (default=false). This conversion has more keyword argument options, see ?ControlSystemsBase.MatrixPencils.rm2ls for additional details.

To associate names with state variables, inputs and outputs, see named_ss.

A, B, C, D = ssdata(sys)

Outputs the statespace matrices of sys. The matrices are not copies: no new memory is allocated, but modifying the matrices in-place will change the behavior of sys.

ssrand(T::Type, ny::Int, nu::Int, nstates::Int; proper=false, stable=true, Ts=nothing)

Returns a random StateSpace model with ny outputs, nu inputs, and nstates states, whose matrix elements are normally distributed.

It is possible to specify if the system should be proper or stable.

Specify a sample time Ts to obtain a discrete-time system.

stab, unstab, sep = stab_unstab(sys; kwargs...)

Decompose sys into sys = stab + unstab where stab contains all stable poles and unstab contains unstable poles.

0 ≤ sep ≤ 1 is the estimated separation between the stable and unstable spectra.

The docstring of MatrixPencils.ssblkdiag, reproduced below, provides more information on the keyword arguments: Base.Docs.DocStr(svec(" ssblkdiag(A, B, C; smarg, disc = false, stableunstable = false, withQ = true, withZ = true) -> (At, Bt, Ct, Q, Z, blkdims, sep)\n\nReduce the regular matrix pencil A - λI to an equivalent block diagonal triangular form At - λI = Q*(A - λI)*Z \nusing the transformation matrices Q and Z, where Q = inv(Z), such that the transformed matrix At have \nseparated stable and unstable eigenvalues with respect to a stability domain Cs defined by the \nstability margin parameter smarg and the stability type parameter disc. \nIf disc = false, Cs is the set of complex numbers with real parts less than smarg, \nwhile if disc = true, Cs is the set of complex numbers with moduli less than smarg (i.e., the interior of a disc \nof radius smarg centered in the origin). If smarg = missing, the default value used is smarg = 0, if disc = false,\nand smarg = 1, if disc = true.\nThe matrix At results in the following block diagonal form\n \n At = | A1 0 |\n | 0 A2 |\n \nwhere the n1 x n1 matrix A1 and the n2 x n2 matrix A2 are in Schur form. \nThe matrix A1 has unstable eigenvalues and A2 has stable eigenvalues if `stableunstable = false,\nwhileA1has stable eigenvalues andA2has unstable eigenvalues ifstableunstable = true.\nThe dimensions of the diagonal blocks are returned inblkdims = (n1, n2). \nIfwithQ = true,Qcontains the left transformation matrix. IfwithQ = false,Qis set tonothing. \nIfwithZ = true,Zcontains the right transformation matrix. IfwithZ = false,Zis set tonothing. \nBt = QB, unlessB = missing, in which caseBt = missingis returned, andCt = CZ, \nunlessC = missing, in which caseCt = missingis returned . \nAn estimation of the separation of the spectra of the two underlying diagonal blocks is returned insep, \nwhere0 ≤ sep ≤ 1. A valuesep ≈ 0indicates thatA1andA2` have some almost equal eigenvalues. \n"), nothing, Dict{Symbol, Any}(:typesig => Union{Tuple{T}, Tuple{AbstractMatrix{T}, Union{Missing, AbstractMatrix{T}}, Union{Missing, AbstractMatrix{T}}}} where T<:Union{Float32, Float64, ComplexF64, ComplexF32}, :module => MatrixPencils, :linenumber => 657, :binding => MatrixPencils.ssblkdiag, :path => "/home/githubactions/actions-runner-1/home/.julia/packages/MatrixPencils/aCDeH/src/gsep.jl"))

kp, ki, fig = stabregionPID(P, [ω]; kd=0, doplot=false, form=:standard)

Segments of the curve generated by this program is the boundary of the stability region for a process with transfer function P(s) The provided derivative gain is expected on parallel form, i.e., the form kp + ki/s + kd s, but the result can be transformed to any form given by the form keyword. The curve is found by analyzing

\[P(s)C(s) = -1 ⟹ \\ |PC| = |P| |C| = 1 \\ arg(P) + arg(C) = -π\]

If P is a function (e.g. s -> exp(-sqrt(s)) ), the stability of feedback loops using PI-controllers can be analyzed for processes with models with arbitrary analytic functions See also loopshapingPI, loopshapingPID, pidplots

starprod(sys1, sys2, dimu, dimy)

Compute the Redheffer star product.

length(U1) = length(Y2) = dimu and length(Y1) = length(U2) = dimy

For details, see Chapter 9.3 in Zhou, K. and JC Doyle. Essentials of robust control, Prentice hall (NJ), 1998

state_names(P)
state_names(P, i)

Get a vector of strings with the names of the states of P, or the i:th name if an index is given.

stepinfo(res::SimResult; y0 = nothing, yf = nothing, settling_th = 0.02, risetime_th = (0.1, 0.9))

Compute the step response characteristics for a simulation result. The following information is computed and stored in a StepInfo struct:

• y0: The initial value of the response
• yf: The final value of the response
• stepsize: The size of the step
• peak: The peak value of the response
• peaktime: The time at which the peak occurs
• overshoot: The percentage overshoot of the response
• undershoot: The percentage undershoot of the response. If the step response never reaches below the initial value, the undershoot is zero.
• settlingtime: The time at which the response settles within settling_th of the final value
• settlingtimeind: The index at which the response settles within settling_th of the final value
• risetime: The time at which the response rises from risetime_th[1] to risetime_th[2] of the final value

Arguments:

• res: The result from a simulation using step (or lsim)
• y0: The initial value, if not provided, the first value of the response is used.
• yf: The final value, if not provided, the last value of the response is used. The simulation must have reached steady-state for an automatically computed value to make sense. If the simulation has not reached steady state, you may provide the final value manually.
• settling_th: The threshold for computing the settling time. The settling time is the time at which the response settles within settling_th of the final value.
• risetime_th: The lower and upper threshold for computing the rise time. The rise time is the time at which the response rises from risetime_th[1] to risetime_th[2] of the final value.

Example:

G = tf([1], [1, 1, 1])
res = step(G, 15)
si = stepinfo(res)
plot(si)

system_name(nothing::LTISystem)

Return the name of the system. If the system does not have a name, an empty string is returned.

sys = tf(num, den[, Ts])
sys = tf(gain[, Ts])

Create as a fraction of polynomials:

• sys::TransferFunction{SisoRational{T,TR}} = numerator/denominator

where T is the type of the coefficients in the polynomial.

• num: the coefficients of the numerator polynomial. Either scalar or vector to create SISO systems

or an array of vectors to create MIMO system.

• den: the coefficients of the denominator polynomial. Either vector to create SISO systems

or an array of vectors to create MIMO system.

• Ts: Sample time if discrete time system.

The polynomial coefficients are ordered starting from the highest order term.

Other uses:

• tf(sys): Convert sys to tf form.
• tf("s"), tf("z"): Create the continuous-time transfer function s, or the discrete-time transfer function z.
• numpoly(sys), denpoly(sys): Get the numerator and denominator polynomials of sys as a matrix of vectors, where the outer matrix is of size n_output × n_inputs.

See also: zpk, ss.

thiran(τ::Real, Ts)

Discretize a potentially fractional delay $τ$ as a Thiran all-pass filter with sample time Ts.

The Thiran all-pass filter gives an a maximally flat group delay.

If $τ$ is an integer multiple of $Ts$, the Thiran all-pass filter reduces to $z^{-τ/Ts}$.

Ref: T. I. Laakso, V. Valimaki, M. Karjalainen and U. K. Laine, "Splitting the unit delay [FIR/all pass filters design]," in IEEE Signal Processing Magazine, vol. 13, no. 1, 1996.

time_scale(sys::AbstractStateSpace{Continuous}, a; balanced = false)
time_scale(G::TransferFunction{Continuous},     a; balanced = true)

Rescale the time axis (change time unit) of sys.

For systems where the dominant time constants are very far from 1, e.g., in electronics, rescaling the time axis may be beneficial for numerical performance, in particular for continuous-time simulations.

Scaling of time for a function $f(t)$ with Laplace transform $F(s)$ can be stated as

\[f(at) \leftrightarrow \dfrac{1}{a} F\big(\dfrac{s}{a}\big)\]

The keyword argument balanced indicates whether or not to apply a balanced scaling on the B and C matrices. For statespace systems, this defaults to false since it changes the state representation, only B will be scaled. For transfer functions, it defaults to true.

Example:

The following example show how a system with a time constant on the order of one micro-second is rescaled such that the time constant becomes 1, i.e., the time unit is changed from seconds to micro-seconds.

Gs  = tf(1, [1e-6, 1])     # micro-second time scale modeled in seconds
Gms = time_scale(Gs, 1e-6) # Change to micro-second time scale
Gms == tf(1, [1, 1])       # Gms now has micro-seconds as time unit

The next example illustrates how the time axis of a time-domain simulation changes by time scaling

t = 0:0.1:50 # original time axis
a = 10       # Scaling factor
sys1 = ssrand(1,1,5)
res1 = step(sys1, t)      # Perform original simulation
sys2 = time_scale(sys, a) # Scale time
res2 = step(sys2, t ./ a) # Simulate on scaled time axis, note the `1/a`
isapprox(res1.y, res2.y, rtol=1e-3, atol=1e-3)

to_sized(sys::AbstractStateSpace)

Return a HeteroStateSpace where the system matrices are of type SizedMatrix.

NOTE: This function is fundamentally type unstable. For maximum performance, create the sized system manually, or make use of the function-barrier technique.

tzeros(sys)
tzeros(sys::AbstractStateSpace; extra=Val(false))

Compute the invariant zeros of the system sys. If sys is a minimal realization, these are also the transmission zeros.

If sys is a state-space system the function has additional keyword arguments, see ?ControlSystemsBase.MatrixPencils.spzeros for more details. If extra = Val(true), the function returns z, iz, KRInfo where z are the transmission zeros, information on the multiplicities of infinite zeros in iz and information on the Kronecker-structure in the KRInfo object. The number of infinite zeros is the sum of the components of iz.

To compute zeros of a system with non-BLAS floats, such as BigFloat, install and load the package GenericSchur.jl before calling tzeros.

zpc(a,r,b,s)

form conv(a,r) + conv(b,s) where the lengths of the polynomials are equalized by zero-padding such that the addition can be carried out

zpk(gain[, Ts])
zpk(num, den, k[, Ts])
zpk(sys)

Create transfer function on zero pole gain form. The numerator and denominator are represented by their poles and zeros.

• sys::TransferFunction{SisoZpk{T,TR}} = k*numerator/denominator

where T is the type of k and TR the type of the zeros/poles, usually Float64 and Complex{Float64}.

• num: the roots of the numerator polynomial. Either scalar or vector to create SISO systems

or an array of vectors to create MIMO system.

• den: the roots of the denominator polynomial. Either vector to create SISO systems

or an array of vectors to create MIMO system.

• k: The gain of the system. Obs, this is not the same as dcgain.
• Ts: Sample time if discrete time system.

Other uses:

• zpk(sys): Convert sys to zpk form.
• zpk("s"): Create the transferfunction s.

z, p, k = zpkdata(sys)

Compute the zeros, poles, and gains of system sys.

Returns

• z : Matrix{Vector{ComplexF64}}, (ny × nu)
• p : Matrix{Vector{ComplexF64}}, (ny × nu)
• k : Matrix{Float64}, (ny × nu)

lyap(A, Q; kwargs...)

Compute the solution X to the discrete Lyapunov equation AXA' - X + Q = 0.

Uses MatrixEquations.lyapc / MatrixEquations.lyapd. For keyword arguments, see the docstring of ControlSystemsBase.MatrixEquations.lyapc / ControlSystemsBase.MatrixEquations.lyapd

norm(sys, p=2; tol=1e-6)

norm(sys) or norm(sys,2) computes the H2 norm of the LTI system sys.

norm(sys, Inf) computes the H∞ norm of the LTI system sys. The H∞ norm is the same as the L∞ for stable systems, and Inf for unstable systems. If the peak gain frequency is required as well, use the function hinfnorm instead. See hinfnorm for further documentation.

tol is an optional keyword argument, used only for the computation of L∞ norms. It represents the desired relative accuracy for the computed L∞ norm (this is not an absolute certificate however).

sys is first converted to a StateSpace model if needed.

Disk

Represents a perturbation disc in the complex plane. Disk(0.5, 2) represents all perturbations in the circle centered at 1.25 with radius 0.75, or in other words, a gain margin of 2 and a phase margin of 36.9 degrees.

A disk can be converted to a Nyquist exclusion disk by nyquist(disk) and plotted using plot(disk).

Arguments:

• γmin: Lower intercept
• γmax: Upper intercept
• c: Center
• r: Radius
• ϕm: Angle of tangent line through origin.

If γmax < γmin the disk is inverted. See diskmargin for disk margin computations.

Diskmargin

The notation follows "An Introduction to Disk Margins", Peter Seiler, Andrew Packard, and Pascal Gahinet

Fields:

α: The disk margin ω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 (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.

ExtendedStateSpace{TE, T} <: AbstractStateSpace{TE}

A type that represents the two-input, two-output system

z  ┌─────┐  w
◄──┤     │◄──
   │  P  │
◄──┤     │◄──
y  └─────┘  u

where

• z denotes controlled outputs (sometimes called performance outputs)
• y denotes measured outputs
• w denotes external inputs, such as disturbances or references
• u denotes control inputs

The call lft(P, K) forms the (lower) linear fractional transform

z  ┌─────┐  w
◄──┤     │◄──
   │  P  │
┌──┤     │◄─┐
│y └─────┘ u│
│           │
│  ┌─────┐  │
│  │     │  │
└─►│  K  ├──┘
   │     │
   └─────┘

i.e., closing the lower loop around K.

An ExtendedStateSpace can be converted to a standard StateSpace by ss(P), this will keep all inputs and outputs, effectively removing the partitioning only.

When feedback is called on this type, defaults are automatically set for the feedback indices. Other functions defined for this type include

• system_mapping
• performance_mapping
• noise_mapping
• lft
• feedback has special overloads that sets defaults connections for ExtendedStateSpace.

and the following design functions expect ExtendedStateSpace as inputs

• hinfsynthesize
• h2synthesize
• LQGProblem (also accepts other types)

A video tutorial on how to use this type is available here.

se = ExtendedStateSpace(s::AbstractStateSpace; kwargs...)

The conversion from a regular statespace object to an ExtendedStateSpace creates the following system by default

\[\begin{bmatrix} A & B & B \\ C & D & D \\ C & D & D \end{bmatrix}\]

i.e., the system and performance mappings are identical, system_mapping(se) == performance_mapping(se) == s. However, all matrices B1, B2, C1, C2; D11, D12, D21, D22 are overridable by a corresponding keyword argument. In this case, the controlled outputs are the same as measured outputs.

Related: se = convert(ExtendedStateSpace, s::StateSpace) produces an ExtendedStateSpace with empty performance_mapping from w->z such that ss(se) == s.

G = LQGProblem(sys::ExtendedStateSpace, Q1, Q2, R1, R2; qQ=0, qR=0, SQ=nothing, SR=nothing)

Return an LQG object that describes the closed control loop around the process sys=ss(A,B,C,D) where the controller is of LQG-type. The controller is specified by weight matrices Q1,Q2 that penalizes state deviations and control signal variance respectively, and covariance matrices R1,R2 which specify state drift and measurement covariance respectively.

sys is an extended statespace object where the upper channel corresponds to disturbances to performance variables (w→z), and the lower channel corresponds to inputs to outputs (u→y), such that lft(sys, K) forms the closed-loop transfer function from external inputs/disturbances to performance variables.

qQ and qR can be set to incorporate loop-transfer recovery, i.e.,

L = lqr(A, B, Q1+qQ*C'C, Q2)
K = kalman(A, C, R1+qR*B*B', R2)

Increasing qQ will add more cost in output direction, e.g., encouraging the use of cheap control, while increasing qR adds fictious dynamics noise, makes the observer faster in the direction we control.

Example

In this example we will control a MIMO system with one unstable pole and one unstable zero. When the system has both unstable zeros and poles, there are fundamental limitations on performance. The unstable zero is in this case faster than the unstable pole, so the system is controllable. For good performance, we want as large separation between the unstable zero dynamics and the unstable poles as possible.

s = tf("s")
P = [1/(s+1) 2/(s+2); 1/(s+3) 1/(s-1)]
sys = ExtendedStateSpace(ss(P)) # Controlled outputs same as measured outputs and state noise affects at inputs only. 
eye(n) = Matrix{Float64}(I,n,n) # For convinience

qQ = 0
qR = 0
Q1 = 10eye(2)
Q2 = 1eye(2)
R1 = 1eye(2)
R2 = 1eye(2)

G = LQGProblem(sys, Q1, Q2, R1, R2, qQ=qQ, qR=qR)

T = comp_sensitivity(G)
S = sensitivity(G)
Gcl = closedloop(G)*static_gain_compensation(G)
plot(
    sigmaplot([S,T, Gcl],exp10.(range(-3, stop=3, length=1000)), lab=["S" "T" "Gry"]),
    plot(step(Gcl, 5))
)

Extended help

Several functions are defined for instances of LQGProblem

• closedloop
• extended_controller
• ff_controller
• gangoffour
• G_CS
• G_PS
• input_comp_sensitivity
• input_sensitivity
• output_comp_sensitivity
• output_sensitivity
• system_mapping
• performance_mapping
• static_gain_compensation
• gangoffourplot
• kalman
• lft
• lqr
• observer_controller

A video tutorial on how to use the LQG interface is available here

Introduction of references

The most principled way of introducing references is to add references as measured inputs to the extended statespace model, and to let the performance output z be the differences between the references and the outputs for which references are provided.

A less cumbersome way is not not consider references when constructing the LQGProblem, and instead pass the z keyword arugment to extended_controller in order to obtain a closed-loop system from state references to controlled outputs, and use some form of inverse of the DC gain of this system (or one of its subsystems) to pre-compensate the reference input.

LQGProblem(P::ExtendedStateSpace)

If only an ExtendedStateSpace system is provided, e.g. from hinfpartition, the system P is assumed to correspond to the H₂ optimal control problem with

C1'C1    = Q1
D12'D12  = Q2
SQ       = C1'D12 # Cross term

B1*B1'   = R1
D21*D21' = R2
SR       = B1*D21' # Cross term

and an LQGProblem with the above covariance matrices is returned. The system description in the returned LQGProblem will have B1 = C1 = I. See Ch. 14 in Robust and optimal control for reference.

Example:

All the following ways of obtaining the H2 optimal controller are (almost) equivalent

using Test
G = ss(tf(1, [10, 1]))
WS = tf(1, [1, 1e-6]) 
WU = makeweight(1e-2, 0.1, 100) 
Gd = hinfpartition(G, WS, WU, [])

K, Gcl = h2synthesize(Gd)              # First option, using H2 formulas
K2, Gcl2 = h2synthesize(Gd, 1000)      # Second option, using H∞ formulas with large γ

lqg = LQGProblem(Gd)                   # Third option, convert to an LQGProblem and obtain controller
K3 = -observer_controller(lqg)

@test h2norm(lft(Gd, K )) ≈ 3.0568 atol=1e-3
@test h2norm(lft(Gd, K2)) ≈ 3.0568 atol=1e-3
@test h2norm(lft(Gd, K3)) ≈ 3.0568 atol=1e-3

See named_ss for a convenient constructor.

UncertainSS{TE} <: AbstractStateSpace{TE}

Represents LFT_u(M, Diagonal(Δ))

nyquistcircles(w, centers, radii)

Plot the nyquist curve with circles. It only makes sense to call this function if the circles represent additive uncertainty, i.e., were calculated with relative=false.

See also fit_complex_perturbations

δ(N=32)

Create an uncertain element of N uniformly distributed samples ∈ [-1, 1]

G_CS(l::LQGProblem)

G_PS(l::LQGProblem)

input_comp_sensitivity(l::LQGProblem)

input_sensitivity(l::LQGProblem)

output_comp_sensitivity(l::LQGProblem)

output_sensitivity(l::LQGProblem)

ss(A, B1, B2, C1, C2, D11, D12, D21, D22 [, Ts])

Create an ExtendedStateSpace.

DescriptorSystems.dss(sys::AbstractStateSpace)

Convert sys to a descriptor statespace system from DescriptorSystems.jl

add_disturbance(sys::StateSpace, Ad::Matrix, Cd::Matrix)

See CCS pp. 144

Arguments:

• sys: System to augment
• Ad: The dynamics of the disturbance
• Cd: How the disturbance states affect the states of sys. This matrix has the shape (sys.nx, size(Ad, 1))

See also add_low_frequency_disturbance, add_resonant_disturbance

add_input_differentiator(sys::StateSpace, ui = 1:sys.nu; goodwin=false)

Augment the output of sys with the difference u(k+1)-u(k)

Arguments:

• ui: An index or vector of indices indicating which inputs to differentiate.
• goodwin: If true, the difference operator will use the Goodwin δ operator, i.e., (u(k+1)-u(k)) / sys.Ts.

The augmented system will have the matrices

[A 0; 0 0]  [B; I]  [C 0; 0 -I]  [D; I]

with length(ui) added states and outputs.

add_input_integrator(sys::StateSpace, ui = 1, ϵ = 0)

Augment the output of sys with the integral of input at index ui, i.e., y_aug = [y; ∫u[ui]] See also add_low_frequency_disturbance

add_low_frequency_disturbance(sys::StateSpace; ϵ = 0, measurement = false)
add_low_frequency_disturbance(sys::StateSpace, Cd; ϵ = 0, measurement = false)

Augment sys with a low-frequency (integrating if ϵ=0) disturbance model. If an integrating input disturbance is used together with an observer, the controller will have integral action.

• Cd: If adding an input disturbance. this matrix indicates how the disturbance states affect the states of sys, and defaults to sys.B. If measurement=true, this matrix indicates how the disturbance states affect the outputs of sys, and defaults to I(sys.ny).

Arguments:

• ϵ: Move the integrator pole ϵ into the stable region.
• measurement: If true, the disturbance is a measurement disturbance, otherwise it's an input diturbance.

add_low_frequency_disturbance(sys::StateSpace, Ai::Integer; ϵ = 0)

A disturbance affecting only state Ai.

add_measurement_disturbance(sys::StateSpace{Continuous}, Ad::Matrix, Cd::Matrix)

Create the system

Ae = [A 0; 0 Ad]
Be = [B; 0]
Ce = [C Cd]

add_differentiator(sys::StateSpace{<:Discrete})

Augment the output of sys with the numerical difference (discrete-time derivative) of output, i.e., y_aug = [y; (y-y_prev)/sys.Ts] To add both an integrator and a differentiator to a SISO system, use

Gd = add_output_integrator(add_output_differentiator(G), 1)

add_output_integrator(sys::StateSpace{<:Discrete}, ind = 1; ϵ = 0)

Augment the output of sys with the integral of output at index ind, i.e., y_aug = [y; ∫y[ind]] To add both an integrator and a differentiator to a SISO system, use

Gd = add_output_integrator(add_output_differentiator(G), 1)

Note: numerical integration is subject to numerical drift. If the output of the system corresponds to, e.g., a velocity reference and the integral to position reference, consider methods for mitigating this drift.

add_resonant_disturbance(sys::AbstractStateSpace, ω, ζ, Bd::AbstractArray)

• Bd: The disturbance input matrix.

add_resonant_disturbance(sys::StateSpace{Continuous}, ω, ζ, Ai::Int; measurement = false)

Augment sys with a resonant disturbance model.

Arguments:

• ω: Frequency
• ζ: Relative damping.
• Ai: The affected state
• measurement: If true, the disturbace is acting on the output, this will cause the controller to have zeros at ω (roots of poly s² + 2ζωs + ω²). If false, the disturbance is acting on the input, this will cause the controller to have poles at ω (roots of poly s² + 2ζωs + ω²).

sysr, hs = baltrunc2(sys::LTISystem; residual=false, n=missing, kwargs...)

Compute the a balanced truncation of order n and the hankel singular values

For keyword arguments, see the docstring of DescriptorSystems.gbalmr, reproduced below Base.Docs.DocStr(svec(" gbalmr(sys, balance = false, matchdc = false, ord = missing, offset = √ϵ,\n atolhsv = 0, rtolhsv = nϵ, atolmin = atolhsv, rtolmin = rtolhsv, \n atol = 0, atol1 = atol, atol2 = atol, rtol, fast = true) -> (sysr, hs)\n\nCompute for a proper and stable descriptor system sys = (A-λE,B,C,D) with the transfer function\nmatrix G(λ), a reduced order realization sysr = (Ar-λEr,Br,Cr,Dr) and the vector hs of decreasingly \nordered Hankel singular values of the system sys. If balance = true, a balancing-based approach\nis used to determine a reduced order minimal realization \nof the form sysr = (Ar-λI,Br,Cr,Dr). For a continuous-time system sys, the resulting realization sysr\nis balanced, i.e., the controllability and observability grammians are equal and diagonal. \nIf additonally matchdc = true, the resulting sysr is computed using state rezidualization formulas \n(also known as singular perturbation approximation) which additionally preserves the DC-gain of sys. \nIn this case, the resulting realization sysr is balanced (for both continuous- and discrete-time systems).\nIf balance = false, an enhanced accuracy balancing-free approach is used to determine the \nreduced order system sysr. \n\nIf ord = nr, the resulting order of sysr is min(nr,nrmin), where nrmin is the order of a minimal \nrealization of sys determined as the number of Hankel singular values exceeding max(atolmin,rtolmin*HN), with\nHN, the Hankel norm of G(λ). If ord = missing, the resulting order is chosen as the number of Hankel \nsingular values exceeding max(atolhsv,rtolhsv*HN). \n\nTo check the stability of the eigenvalues of the pencil A-λE, the real parts of eigenvalues must be less than -β\nfor a continuous-time system or \nthe moduli of eigenvalues must be less than 1-β for a discrete-time system, where β is the stability domain boundary offset. \nThe offset β to be used can be specified via the keyword parameter offset = β. \nThe default value used for β is sqrt(ϵ), where ϵ is the working machine precision. \n\nThe keyword arguments atol1, atol2, and rtol, specify, respectively, \nthe absolute tolerance for the nonzero elements of A, B, C, D, \nthe absolute tolerance for the nonzero elements of E, \nand the relative tolerance for the nonzero elements of A, B, C, D and E. \nThe default relative tolerance is nϵ, where ϵ is the working machine epsilon \nand n is the order of the system sys. The keyword argument atol can be used \nto simultaneously set atol1 = atol and atol2 = atol. \n\nIf E is singular, the uncontrollable infinite eigenvalues of the pair (A,E) and\nthe non-dynamic modes are elliminated using minimal realization techniques.\nThe rank determinations in the performed reductions\nare based on rank revealing QR-decompositions with column pivoting \nif fast = true or the more reliable SVD-decompositions if fast = false. \n\nMethod: For the order reduction of a standard system, the balancing-free method of [1] or \nthe balancing-based method of [2] are used. For a descriptor system the balancing related order reduction \nmethods of [3] are used. To preserve the DC-gain of the original system, the singular perturbation \napproximation method of [4] is used in conjunction with the balancing-based or balancing-free\napproach of [5]. \n\nReferences\n\n[1] A. Varga. \n Efficient minimal realization procedure based on balancing.\n In A. El Moudni, P. Borne, and S.G. Tzafestas (Eds.), \n Prepr. of the IMACS Symp. on Modelling and Control of Technological \n Systems, Lille, France, vol. 2, pp.42-47, 1991.\n\n[2] M. S. Tombs and I. Postlethwaite. \n Truncated balanced realization of a stable non-minimal state-space \n system. Int. J. Control, vol. 46, pp. 1319–1330, 1987.\n\n[3] T. Stykel. \n Gramian based model reduction for descriptor systems. \n Mathematics of Control, Signals, and Systems, 16:297–319, 2004.\n\n[4] Y. Liu Y. and B.D.O. Anderson \n Singular Perturbation Approximation of Balanced Systems,\n Int. J. Control, Vol. 50, pp. 1379-1405, 1989.\n\n[5] Varga A.\n Balancing-free square-root algorithm for computing singular perturbation approximations.\n Proc. 30-th IEEE CDC, Brighton, Dec. 11-13, 1991, Vol. 2, pp. 1062-1065.\n"), nothing, Dict{Symbol, Any}(:typesig => Union{Tuple{DescriptorSystems.DescriptorStateSpace{T, ET, MT} where {ET<:Union{LinearAlgebra.UniformScaling{Bool}, AbstractMatrix{T}}, MT<:AbstractMatrix{T}}}, Tuple{T}} where T, :module => DescriptorSystems, :linenumber => 461, :binding => DescriptorSystems.gbalmr, :path => "/home/githubactions/actions-runner-1/home/.julia/packages/DescriptorSystems/7S3aT/src/orderreduction.jl"))

sysr, hs, info = baltrunc_coprime(sys; residual = false, n = missing, factorization::F = DescriptorSystems.gnlcf, kwargs...)

Compute a balanced truncation of the left coprime factorization of sys. See baltrunc2 for additional keyword-argument help.

Coprime-factor reduction performs a coprime factorization of the model into $P(s) = M(s)^{-1}N(s)$ where $M$ and $N$ are stable factors even if $P$ contains unstable modes. After this, the system $NM = \begin{bmatrix}N & M \end{bmatrix}$ is reduced using balanced truncation and the final reduced-order model is formed as $P_r(s) = M_r(s)^{-1}N_r(s)$. For this method, the Hankel signular values of $NM$ are reported and the reported errors are $||NM - N_rM_r||_\infty$. This method is of particular interest in closed-loop situations, where a model-reduction error $||NM - N_rM_r||_\infty$ no greater than the normalized-coprime margin of the plant and the controller, guaratees that the closed loop remains stable when either $P$ or $K$ are reduced. The normalized-coprime margin can be computed with ncfmargin(P, K) (ncfmargin).

Arguments:

• factorization: The function to perform the coprime factorization. A non-normalized factorization may be used by passing RobustAndOptimalControl.DescriptorSystems.glcf.
• kwargs: Are passed to DescriptorSystems.gbalmr, the docstring of which is reproduced below:

Base.Docs.DocStr(svec(" gbalmr(sys, balance = false, matchdc = false, ord = missing, offset = √ϵ,\n atolhsv = 0, rtolhsv = nϵ, atolmin = atolhsv, rtolmin = rtolhsv, \n atol = 0, atol1 = atol, atol2 = atol, rtol, fast = true) -> (sysr, hs)\n\nCompute for a proper and stable descriptor system sys = (A-λE,B,C,D) with the transfer function\nmatrix G(λ), a reduced order realization sysr = (Ar-λEr,Br,Cr,Dr) and the vector hs of decreasingly \nordered Hankel singular values of the system sys. If balance = true, a balancing-based approach\nis used to determine a reduced order minimal realization \nof the form sysr = (Ar-λI,Br,Cr,Dr). For a continuous-time system sys, the resulting realization sysr\nis balanced, i.e., the controllability and observability grammians are equal and diagonal. \nIf additonally matchdc = true, the resulting sysr is computed using state rezidualization formulas \n(also known as singular perturbation approximation) which additionally preserves the DC-gain of sys. \nIn this case, the resulting realization sysr is balanced (for both continuous- and discrete-time systems).\nIf balance = false, an enhanced accuracy balancing-free approach is used to determine the \nreduced order system sysr. \n\nIf ord = nr, the resulting order of sysr is min(nr,nrmin), where nrmin is the order of a minimal \nrealization of sys determined as the number of Hankel singular values exceeding max(atolmin,rtolmin*HN), with\nHN, the Hankel norm of G(λ). If ord = missing, the resulting order is chosen as the number of Hankel \nsingular values exceeding max(atolhsv,rtolhsv*HN). \n\nTo check the stability of the eigenvalues of the pencil A-λE, the real parts of eigenvalues must be less than -β\nfor a continuous-time system or \nthe moduli of eigenvalues must be less than 1-β for a discrete-time system, where β is the stability domain boundary offset. \nThe offset β to be used can be specified via the keyword parameter offset = β. \nThe default value used for β is sqrt(ϵ), where ϵ is the working machine precision. \n\nThe keyword arguments atol1, atol2, and rtol, specify, respectively, \nthe absolute tolerance for the nonzero elements of A, B, C, D, \nthe absolute tolerance for the nonzero elements of E, \nand the relative tolerance for the nonzero elements of A, B, C, D and E. \nThe default relative tolerance is nϵ, where ϵ is the working machine epsilon \nand n is the order of the system sys. The keyword argument atol can be used \nto simultaneously set atol1 = atol and atol2 = atol. \n\nIf E is singular, the uncontrollable infinite eigenvalues of the pair (A,E) and\nthe non-dynamic modes are elliminated using minimal realization techniques.\nThe rank determinations in the performed reductions\nare based on rank revealing QR-decompositions with column pivoting \nif fast = true or the more reliable SVD-decompositions if fast = false. \n\nMethod: For the order reduction of a standard system, the balancing-free method of [1] or \nthe balancing-based method of [2] are used. For a descriptor system the balancing related order reduction \nmethods of [3] are used. To preserve the DC-gain of the original system, the singular perturbation \napproximation method of [4] is used in conjunction with the balancing-based or balancing-free\napproach of [5]. \n\nReferences\n\n[1] A. Varga. \n Efficient minimal realization procedure based on balancing.\n In A. El Moudni, P. Borne, and S.G. Tzafestas (Eds.), \n Prepr. of the IMACS Symp. on Modelling and Control of Technological \n Systems, Lille, France, vol. 2, pp.42-47, 1991.\n\n[2] M. S. Tombs and I. Postlethwaite. \n Truncated balanced realization of a stable non-minimal state-space \n system. Int. J. Control, vol. 46, pp. 1319–1330, 1987.\n\n[3] T. Stykel. \n Gramian based model reduction for descriptor systems. \n Mathematics of Control, Signals, and Systems, 16:297–319, 2004.\n\n[4] Y. Liu Y. and B.D.O. Anderson \n Singular Perturbation Approximation of Balanced Systems,\n Int. J. Control, Vol. 50, pp. 1379-1405, 1989.\n\n[5] Varga A.\n Balancing-free square-root algorithm for computing singular perturbation approximations.\n Proc. 30-th IEEE CDC, Brighton, Dec. 11-13, 1991, Vol. 2, pp. 1062-1065.\n"), nothing, Dict{Symbol, Any}(:typesig => Union{Tuple{DescriptorSystems.DescriptorStateSpace{T, ET, MT} where {ET<:Union{LinearAlgebra.UniformScaling{Bool}, AbstractMatrix{T}}, MT<:AbstractMatrix{T}}}, Tuple{T}} where T, :module => DescriptorSystems, :linenumber => 461, :binding => DescriptorSystems.gbalmr, :path => "/home/githubactions/actions-runner-1/home/.julia/packages/DescriptorSystems/7S3aT/src/orderreduction.jl"))

baltrunc_unstab(sys::LTISystem; residual = false, n = missing, kwargs...)

Balanced truncation for unstable models. An additive decomposition of sys into sys = sys_stable + sys_unstable is performed after which sys_stable is reduced. The order n must not be less than the number of unstable poles.

See baltrunc2 for other keyword arguments.

bilinearc2d(Ac::AbstractArray, Bc::AbstractArray, Cc::AbstractArray, Dc::AbstractArray, Ts::Number; tolerance=1e-12)

Balanced Bilinear transformation in State-Space. This method computes a discrete time equivalent of a continuous-time system, such that

\[G_d(z) = s2z[G_c(s)]\]

in a manner which accomplishes the following (i) Preserves the infinity L-infinity norm over the transformation (ii) Finds a system which balances B and C, in the sense that $||B||_2=||C||_2$ (iii) Satisfies $G_c(s) = z2s[s2z[G_c(s)]]$ for some map z2s[]

bilinearc2d(sys::ExtendedStateSpace, Ts::Number)

Applies a Balanced Bilinear transformation to a discrete-time extended statespace object

bilinearc2d(sys::StateSpace, Ts::Number)

Applies a Balanced Bilinear transformation to a discrete-time statespace object

bilineard2c(Ad::AbstractArray, Bd::AbstractArray, Cd::AbstractArray, Dd::AbstractArray, Ts::Number; tolerance=1e-12)

Balanced Bilinear transformation in State-Space. This method computes a continuous time equivalent of a discrete time system, such that

G_c(z) = z2s[G_d(z)]

in a manner which accomplishes the following (i) Preserves the infinity L-infinity norm over the transformation (ii) Finds a system which balances B and C, in the sense that ||B||2=||C||2 (iii) Satisfies Gd(z) = s2z[z2s[Gd(z)]] for some map s2z[]

bilineard2c(sys::ExtendedStateSpace)

Applies a Balanced Bilinear transformation to continuous-time extended statespace object

bilineard2c(sys::StateSpace)

Applies a Balanced Bilinear transformation to continuous-time statespace object

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

broken_feedback(L, i)

Closes all loops in square MIMO system L except for loops i. Forms L1 in fig 14. of "An Introduction to Disk Margins", Peter Seiler, Andrew Packard, and Pascal Gahinet

closedloop(l::LQGProblem, L = lqr(l), K = kalman(l))

Closed-loop system as defined in Glad and Ljung eq. 8.28. Note, this definition of closed loop is not the same as lft(P, K), which has B1 instead of B2 as input matrix. Use lft(l) to get the system from disturbances to controlled variables w -> z.

The return value will be the closed loop from filtred reference only, other disturbance signals (B1) are ignored. See feedback for a more advanced option. This function assumes that the control signal is computed as u = r̃ - Lx̂ (not u = L(xᵣ - x̂)), i.e., the feedforward signal r̃ is added directly to the plant input. r̃ must thus be produced by an inverse-like model that takes state references and output the feedforward signal.

Use static_gain_compensation to adjust the gain from references acting on the input B2, dcgain(closedloop(l))*static_gain_compensation(l) ≈ I

connect(systems, connections; external_inputs, external_outputs = (:), verbose = true, unique = true, kwargs...)

Create block connections using named inputs and outputs.

Addition and subtraction nodes are achieved by creating a linear combination node, i.e., a system with a D matrix only.

Arguments:

• systems: A vector of named systems to be connected
• connections: a vector of pairs output => input, where each pair maps an output to an input. Each output must appear as an output in one of systems, and similarly each input must appear as an input in one of systems. All inputs must have unique names and so must all outputs, but an input may have the same name as an output. In the example below the connection :uP => :uP connects the output :uP of the addP block to P's input :uP
• external_inputs: external signals to be used as inputs in the constructed system. Use (:) to indicate all signals
• external_outputs: outputs of the constructed system. Use (:) to indicate all signals
• verbose: Issue warnings for signals that have no connection
• unique: If true, all input names must be unique. If false, a single external input signal may be connected to multiple input ports with the same name.

Note: Positive feedback is used, controllers that are intended to be connected with negative feedback must thus be negated.

Example: The following complicated feedback interconnection

                 yF
               ┌────────────────────────────────┐
               │                                │
    ┌───────┐  │  ┌───────┐        ┌───────┐    │    ┌───────┐
uF  │       │  │  │       | yR     │       │ yC │ uP │       │   yP
────►   F   ├──┴──►   R   │────+───►   C   ├────+────►   P   ├───┬────►
    │       │     │       │    │   │       │         │       │   │
    └───────┘     └───────┘    │   └───────┘         └───────┘   │
                               │                                 │
                               └─────────────────────────────────┘

can be created by

F = named_ss(ssrand(1, 1, 2, proper=true), x=:xF, u=:uF, y=:yF)
R = named_ss(ssrand(1, 1, 2, proper=true), x=:xR, u=:uR, y=:yR)
C = named_ss(ssrand(1, 1, 2, proper=true), x=:xC, u=:uC, y=:yC)
P = named_ss(ssrand(1, 1, 3, proper=true), x=:xP, u=:uP, y=:yP)

addP = sumblock("uP = yF + yC") # Sum node before P
addC = sumblock("uC = yR - yP") # Sum node before C

connections = [
    :yP => :yP # Output to input
    :uP => :uP
    :yC => :yC
    :yF => :yF
    :yF => :uR
    :uC => :uC
    :yR => :yR
]
external_inputs = [:uF] # External inputs

G = connect([F, R, C, P, addP, addC], connections; external_inputs)

If an external input is to be connected to multiple points, use a splitter to split up the signal into a set of unique names which are then used in the connections.

controller_reduction(P::ExtendedStateSpace, K, r, out=true; kwargs...)

Minimize ||(K-Kᵣ) W||∞ if out=false ||W (K-Kᵣ)||∞ if out=true See Robust and Optimal Control Ch 19.1 out indicates if the weight will be applied as output or input weight.

This function expects a *positive feedback controller K.

This method corresponds to the methods labelled SW1/SW2(SPA) in Andreas Varga, "Controller Reduction Using Accuracy-Enhancing Methods" SW1 is the default method, corresponding to out=true.

This method does not support unstable controllers. See the reference above for alternatives. See also stab_unstab and baltrunc_unstab.

controller_reduction_plot(G, K)

Plot the normalized-coprime margin (ncfmargin) as a function of controller order when baltrunc_coprime is used to reduce the controller. Red, orange and green bands correspond to rules of thumb for bad, okay and good coprime uncertainty margins. A value of 0 indicate an unstable closed loop.

If G is an ExtendedStateSpace system, a second plot will be shown indicating the $H_∞$ norm between inputs and performance outputs $||T_{zw}||_\infty$ when the function controller_reduction is used to reduce the controller.

The order of the controller can safely be reduced as long as the normalized coprime margin remains sufficiently large. If the controller contains integrators, it may be advicable to protect the integrators from the reduction, e.g., if the controller is obtained using glover_mcfarlane, perform the reduction on info.Gs, info.Ks rather than on K, and form Kr using the reduced Ks.

See glover_mcfarlane or the docs for an example.

controller_reduction_weight(P::ExtendedStateSpace, K)

Lemma 19.1 See Robust and Optimal Control Ch 19.1

dare3(P::AbstractStateSpace, Q1::AbstractMatrix, Q2::AbstractMatrix, Q3::AbstractMatrix; full=false)

Solve the discrete-time algebraic Riccati equation for a discrete LQR cost augmented with control differences

\[x^{T} Q_1 x + u^{T} Q_2 u + Δu^{T} Q_3 Δu, \quad Δu = u(k) - u(k-1)\]

If full, the returned matrix will include the state u(k-1), otherwise the returned matrix will be of the same size as Q1.

diskmargin(L, σ = 0)
diskmargin(L, σ::Real, ω)

Calculate the disk margin of LTI system L. L is supposed to be a loop-transfer function, i.e., it should be square. If L = PC the disk margin for output perturbations is computed, whereas if L = CP, input perturbations are considered. If the method diskmargin(P, C, args...) is used, both are computed. Note, if L is MIMO, a simultaneous margin is computed, see loop_diskmargin for single loop margins of MIMO systems.

The implementation and notation follows "An Introduction to Disk Margins", Peter Seiler, Andrew Packard, and Pascal Gahinet.

The margins are aviable as fields of the returned objects, see Diskmargin.

Arguments:

• L: A loop-transfer function.
• σ: If little is known about the distribution of gain variations then σ = 0 is a reasonable choice as it allows for a gain increase or decrease by the same relative amount. The choice σ < 0 is justified if the gain can decrease by a larger factor than it can increase. Similarly, the choice σ > 0 is justified when the gain can increase by a larger factor than it can decrease. If σ = −1 then the disk margin condition is αmax = inv(MT). This margin is related to the robust stability condition for models with multiplicative uncertainty of the form P (1 + δ). If σ = +1 then the disk margin condition is αmax = inv(MS)
• kwargs: Are sent to the hinfnorm calculation
• ω: If a vector of frequencies is supplied, the frequency-dependent disk margin will be computed, see example below.

Example:

L = tf(25, [1,10,10,10])
dm = diskmargin(L, 0)
plot(dm) # Plot the disk margin to illustrate maximum allowed simultaneous gain and phase variations.

nyquistplot(L)
plot!(dm, nyquist=true) # plot a nyquist exclusion disk. The Nyquist curve will be tangent to this disk at `dm.ω0`
nyquistplot!(dm.f0*L) # If we perturb the system with the worst-case perturbation `f0`, the curve will pass through the critical point -1.

## Frequency-dependent margin
w = exp10.(LinRange(-2, 2, 500))
dms = diskmargin(L, 0, w)
plot(dms; lower=true, phase=true)

Example: relation to Ms and Mt

Ms, wMs = hinfnorm(input_sensitivity(P, C)) # Input Ms
dm = diskmargin(C*P, 1) # Input diskmargin, skew = +1
isapprox(Ms/(Ms-1), dm.gainmargin[2], rtol=1e-2) # Guaranteed gain margin based on Ms
isapprox(inv(Ms), dm.margin, rtol=1e-2)
isapprox(dm.ω0, wMs, rtol=1e-1)


Mt, wMt = hinfnorm(input_comp_sensitivity(P, C)) # Input Mt
dm = diskmargin(C*P, -1) # Input diskmargin, skew = -1
isapprox(inv(Mt), dm.margin, rtol=1e-2)
isapprox(dm.ω0, wMt, rtol=1e-1)

See also ncfmargin and loop_diskmargin.

diskmargin(P::LTISystem, C::LTISystem, σ, w::AbstractVector, args...; kwargs...)

Simultaneuous diskmargin at outputs, inputs and input/output simultaneously of P. Returns a named tuple with the fields input, output, simultaneous_input, simultaneous_output, simultaneous where input and output represent loop-at-a-time margins, simultaneous_input is the margin for simultaneous perturbations on all inputs and simultaneous is the margin for perturbations on all inputs and outputs simultaneously.

Note: simultaneous margins are more conservative than single-loop margins and are likely to be much lower than the single-loop margins. Indeed, with several simultaneous perturbations, it's in general easier to make the system unstable. It's not uncommon for a simultaneous margin involving two signals to be on the order of half the size of the single-loop margins.

See also ncfmargin and loop_diskmargin.

diskmargin(L::LTISystem, σ::Real, ω)

Calculate the diskmargin at a particular frequency or vector of frequencies. If ω is a vector, you get a frequency-dependent diskmargin plot if you plot the returned value. See also ncfmargin.

expand_symbol(s::Symbol, n::Int)

Takes a symbol and an integer and returns a vector of symbols with increasing numbers appended to the end. E.g., (:x, 3) -> [:x1, :x2, :x3]

The short-hand syntax s^n is also available, e.g., :x^3 == expand_symbol(:x, 3).

Useful to create signal names for named systems.

extended_controller(l::LQGProblem, L = lqr(l), K = kalman(l); z = nothing)

Returns a statespace system representing the controller that is obtained when state-feedback u = L(xᵣ-x̂) is combined with a Kalman filter with gain K that produces state estimates x̂. The controller is an instance of ExtendedStateSpace where C2 = -L, D21 = L and B2 = K.

The returned system has inputs[xᵣ; y] and outputs the control signal u. If a reference model R is used to generate state references xᵣ, the controller from (ry, y) -> u where ry - y = e is given by

Ce = extended_controller(l)
Ce = named_ss(ss(Ce); x = :xC, y = :u, u = [R.y; :y^l.ny]) # Name the inputs of Ce the same as the outputs of `R`.
connect([R, Ce]; u1 = R.y, y1 = R.y, w1 = [R.u; :y^l.ny], z1=[:u])

Since the negative part of the feedback is built into the returned system, we have

C = observer_controller(l)
Ce = extended_controller(l)
system_mapping(Ce) == -C

Please note, without the reference pre-filter, the DC gain from references to controlled outputs may not be identity. If a vector of output indices is provided through the keyword argument z, the closed-loop system from state reference xᵣ to outputs z is returned as a second return argument. The inverse of the DC-gain of this closed-loop system may be useful to compensate for the DC-gain of the controller.

extended_controller(K::AbstractStateSpace)

Takes a controller and returns an ExtendedStateSpace version which has augmented input [r; y] and output y (z output is 0-dim).

G = feedback_control(P, K)

Return the (negative feedback) closed-loop system from input of K to output of P while outputing also the control signal (output of K), i.e., G maps references to [y; u]

Example:

The following are two equivalent ways of achieving the same thing

G = ssrand(3,4,2)
K = ssrand(4,3,2)

Gcl1 = feedback_control(G, K) # First option

# Second option using named systems and connect
G = named_ss(G, :G)
K = named_ss(K, :K)
S = sumblock("Ku = r - Gy", n=3) # Create a sumblock that computes r - Gy for vectors of length 3

z1 = [G.y; K.y] # Output both plant and controller outputs
w1 = :r^3       # Extenal inputs are the three references into the sum block
connections = [K.y .=> G.u; G.y .=> G.y; K.u .=> K.u] # Since the sumblock uses the same names as the IO signals of G,K, we can reuse these names here
Gcl2 = connect([G, K, S], connections; z1, w1)

@test linfnorm(minreal(Gcl1 - Gcl2.sys))[1] < 1e-10 # They are the same

To include also an input disturbance, use

Gcl = feedback(K, P, W2=:, Z2=:, Zperm=[(1:ny).+nu; 1:nu]) # y,u from r,d

See also extended_gangoffour.

ff_controller(l::LQGProblem, L = lqr(l), K = kalman(l))

Return the feedforward controller $C_{ff}$ that maps references to plant inputs: $u = C_{fb}y + C_{ff}r$

The following should hold

Cff = RobustAndOptimalControl.ff_controller(l)
Cfb = observer_controller(l)
Gcl = feedback(system_mapping(l), Cfb) * Cff # Note the comma in feedback, P/(I + PC) * Cff
dcgain(Gcl) ≈ I # Or some I-like non-square matrix 

Note, if extended_controller is used, the DC-gain compensation above cannot be used. The extended_controller assumes that the references enter like u = L(xᵣ - x̂).

See also observer_controller.

l, res = find_lft(sys::StateSpace{<:Any, <:StaticParticles{<:Any, N}}, δ) where N

NOTE: This function is experimental.

Given an systems sys with uncertain coefficients in the form of StaticParticles, search for a lower linear fractional transformation M such that lft(M, δ) ≈ sys.

δ can be either the source of uncertainty in sys, i.e., a vector of the unique uncertain parameters that were used to create sys. These should be constructed as uniform randomly distributed particles for most robust-control theory to be applicable. δ can also be an integer, in which case a numer of δ sources of uncertainty are automatically created. This could be used for order reduction if the number of uncertainty sources in sys is large.

Note, uncertainty in sys is only supported in A and B, C and D must be deterministic.

Returns l::LFT that internaly contains all four blocks of M as well as δ. Call ss(l,sys) do obtain lft(M, δ) ≈ sys.

Call Matrix(l) to obtain M = [M11 M12; M21 M22]

centers, radii = fit_complex_perturbations(P, w; relative=true, nominal=:mean)

For each frequency in w, fit a circle in the complex plane that contains all models in the model set P, represented as an LTISystem with Particles coefficients. Note, the resulting radii can be quite unstable if the number of particles is small, in particular if the particles are normally distributed instead of uniformly.

If realtive = true, circles encompassing |(P - Pn)/Pn| will be returned (multiplicative/relative uncertainty). If realtive = false, circles encompassing |P - Pn| will be returned (additive uncertainty).

If nominal = :mean, the mean of P will be used as nominal model. If nominal = :first, the first particle will be used. See MonteCarloMeasurements.with_nominal to set the nominal value in the first particle. If nominal = :center, the middle point (pmaximum(ri)+pminimum(ri))/2 will be used. This typically gives the smallest circles.

See also nyquistcircles to plot circles (only if relative=false).

frequency_separation(sys, ω)

Decomponse sys into sys = sys_slow + sys_fast, where sys_slow contain all modes with eigenvalues with absolute value less than ω and sys_fast contain all modes with eigenvalues with absolute value greater than or equal to ω.

sysr, hs = frequency_weighted_reduction(G, Wo, Wi, r=nothing; residual=true)

Find Gr such that $||Wₒ(G-Gr)Wᵢ||∞$ is minimized. For a realtive reduction, set Wo = inv(G) and Wi = I.

If residual = true, matched static gain is achieved through "residualization", i.e., setting

\[0 = A_{21}x_{1} + A_{22}x_{2} + B_{2}u\]

where indices 1/2 correspond to the remaining/truncated states respectively. This choice typically results in a better match in the low-frequency region and a smaller overall error.

Ref: Andras Varga and Brian D.O. Anderson, "Accuracy enhancing methods for the frequency-weighted balancing related model reduction"

Note: This function only handles exponentially stable models. To reduce unstable and marginally stable models, decompose the system into stable and unstable parts using stab_unstab, reduce the stable part and then add the unstable part back.

Example:

The following example performs reduction with a frequency focus between frequencies w1 and w2.

using DSP
w1 = 1e-4
w2 = 1e-1
fc = DSP.analogfilter(DSP.Bandpass(w1, w2), DSP.Butterworth(2))
tfc = DSP.PolynomialRatio(fc)
W = tf(DSP.coefb(tfc), DSP.coefa(tfc))
rsys, hs = frequency_weighted_reduction(sys, W, 1)

fudge_inv(s::AbstractStateSpace, ε = 0.001)

Allow inverting a proper statespace system by adding a tiny (ε) feedthrough term to the D matrix. The system must still be square.