allmargin

Gain margin, phase margin, delay margin, and crossover frequencies

Syntax

S = allmargin(L)

S = allmargin(L,Focus=[fmin,fmax])

S = allmargin(mag,phase,w,ts)

Description

S = allmargin(L) computes the gain margin, phase margin, delay margin, and the corresponding crossover frequencies for the SISO or MIMO negative feedback loop with open-loop response L. The negative feedback loop is computed as feedback(L,eye(M)), where M is the number of inputs and outputs in L.

For a MIMO system, allmargin returns loop-at-a-time stability margins for the negative-feedback closed loop system. Use allmargin to find classical margins of any SISO or MIMO model, including models with delays.

S = allmargin(L,Focus=[fmin,fmax]) computes the gain and phase margins in the frequency range [fmin,fmax], ignoring stability issues outside this range. For instance, use this syntax to ignore very low frequency dynamics for the purpose of computing stability margins. (since R2024a)

S = allmargin(mag,phase,w,ts) computes the stability margins from the frequency response data mag, phase, w, and the sample time, ts.

Examples

Stability Margins of a Transfer Function

For this example, consider a SISO open-loop transfer function L given by,

$$L=\frac{25}{s^3+10s^2+10s+10}$$

L = tf(25,[1 10 10 10]);

Find the stability margins of L.

S = allmargin(L)

S = struct with fields:
     GainMargin: 3.6000
    GMFrequency: 3.1623
    PhaseMargin: 29.1104
    PMFrequency: 1.7844
    DelayMargin: 0.2847
    DMFrequency: 1.7844
         Stable: 1

The output S is a structure with the classical margins and their respective crossover frequencies of the negative feedback loop of L.

Stability Margins of a MIMO System

For this example, consider a MIMO state-space model L with 2 inputs and 2 outputs.

Load the data.

load('mimoStateSpaceModel.mat','L')

Find the classical margins for the MIMO system.

S = allmargin(L)

S=2×1 struct array with fields:
    GainMargin
    GMFrequency
    PhaseMargin
    PMFrequency
    DelayMargin
    DMFrequency
    Stable

The output S is a 2-by-1 structure array of classical margins and their respective crossover frequencies. For instance, S(1) refers to the stability margins of the first I/O feedback channel with all other loops closed.

Stability Margins of Models in an Array

For this example, load invertedPendulumArray.mat, which contains a 3-by-3 array of inverted pendulum SISO models. The mass of the pendulum varies as you move from model to model along a single column of sys, and the length of the pendulum varies as you move along a single row. The mass values used are 100g, 200g and 300g, and the pendulum lengths used are 3m, 2m and 1m respectively.

$$\begin{array}{cccc}& Column1& Column2& Column3\\ Row1& 100g,3m& 100g,2m& 100g,1m\\ Row2& 200g,3m& 200g,2m& 200g,1m\\ Row3& 300g,3m& 300g,2m& 300g,1m\end{array}$$

load('invertedPendulumArray.mat','sys');
size(sys)

3x3 array of transfer functions.
Each model has 1 outputs and 1 inputs.

Find stability margins for all models in the array.

S = allmargin(sys)

S=3×3 struct array with fields:
    GainMargin
    GMFrequency
    PhaseMargin
    PMFrequency
    DelayMargin
    DMFrequency
    Stable

allmargin returns a 3-by-3 structure array S, in which each entry is a structure containing the stability margins of the corresponding entry in sys. For instance, the stability margins of the model with 100g pendulum weight and 2m length is contained in S(1,2).

Analyze Stability in Specified Frequency Range

Since R2024a

In some applications, you might want to compute stability margins within a certain frequency range, neglecting dynamics outside this range. For instance, consider the following open-loop system.

L = tf([1 -1e-3],[1 2 0 0]);

Stability analysis of this system shows that the closed-loop system is unstable.

S1 = allmargin(L)

S1 = struct with fields:
     GainMargin: Inf
    GMFrequency: Inf
    PhaseMargin: 76.4633
    PMFrequency: 0.4859
    DelayMargin: 2.7467
    DMFrequency: 0.4859
         Stable: 0

This result occurs because the closed-loop system CL = feedback(L,1) has an unstable pole at a relatively low frequency.

CL = feedback(L,1);
damp(CL)

                                                                       
         Pole              Damping       Frequency      Time Constant  
                                       (rad/seconds)      (seconds)    
                                                                       
  9.98e-04                -1.00e+00       9.98e-04        -1.00e+03    
 -1.00e+00 + 3.16e-02i     1.00e+00       1.00e+00         1.00e+00    
 -1.00e+00 - 3.16e-02i     1.00e+00       1.00e+00         1.00e+00    

To exclude the low-frequency dynamics from stability analysis, use the Focus option.

S2 = allmargin(L,Focus=[1e-3,Inf])

S2 = struct with fields:
     GainMargin: Inf
    GMFrequency: Inf
    PhaseMargin: 76.4633
    PMFrequency: 0.4859
    DelayMargin: 2.7467
    DMFrequency: 0.4859
         Stable: 1

For variations faster than 1e-3 rad/s, the closed-loop system is stable.

Stability Margins from Frequency Response Data

For this example, load the frequency response data of an open loop system, consisting of magnitudes m and phase values p measured at the frequencies in w.

load('openLoopFRData.mat','m','p','w','ts');

Compute stability margins using the frequency response data.

S = allmargin(m,p,w,ts)

S = struct with fields:
     GainMargin: 0.6249
    GMFrequency: 1.2732
    PhaseMargin: [-90.0000 48.9853]
    PMFrequency: [1.0000 1.5197]
    DelayMargin: [4.7124 0.5626]
    DMFrequency: [1.0000 1.5197]
         Stable: NaN

The output S is a structure with the classical margins and their respective crossover frequencies. Since allmargin cannot assess the stability for frequency response data models, S.Stable = NaN.

Input Arguments

L — Open-loop response

dynamic system model | model array

Open-loop response, specified as a dynamic system model. L can be SISO or MIMO, as long as it has the same number of inputs and outputs. allmargin computes the classical stability margins for the negative-feedback closed-loop system feedback(L,eye(M)):

To compute the stability margins of the positive feedback system feedback(L,eye(M),+1), use allmargin(-L).

When you have a controller P and a plant C, you can compute the stability margins for gain and phase variations at the plant inputs or outputs. From the following diagram:

• To compute margins at the plant outputs, set L = P*C.

• To compute margins at the plant inputs, set L = C*P.

L can be continuous time or discrete time. If L is a generalized state-space model (genss or uss), then allmargin uses the current or nominal value of all control design blocks in L.

If L is a frequency-response data model (such as frd), then allmargin computes the margins at each frequency represented in the model. The function returns the margins at the frequency with the smallest stability margin.

If L is a model array, then allmargin computes margins for each model in the array.

[fmin,fmax] — Frequency range

[0,Inf] (default) | two-element vector

Since R2024a

Frequency range to consider in stability analysis, specified as a two-element vector containing the lower and upper limits of the range. The margin computation ignores dynamics outside this range. Specify frequencies in rad/TimeUnit, where TimeUnit is the TimeUnit property of the input dynamic system.

Example: [1e-3,1e6]

mag — Magnitude of system response

3-D array

Magnitude of the system response in absolute units, specified as a 3-D array. mag is an M-by-M-by-N array, where M is the number of inputs or outputs, and N is the number of frequency points. For more information on obtaining mag, see Obtain Magnitude and Phase Data and Magnitude and Phase of MIMO System.

phase — Phase of system response

3-D array

Phase of the system response in degrees, specified as a 3-D array. phase is an M-by-M-by-N array, where M is the number of inputs or outputs, and N is the number of frequency points. For more information on obtaining phase, see Obtain Magnitude and Phase Data and Magnitude and Phase of MIMO System.

w — Frequencies at which the magnitude and phase values of system response are obtained

column vector

Frequencies at which the magnitude and phase values of system response are obtained, specified as a column vector. You can provide the frequency vector w in any units; allmargin returns frequencies in the same units. allmargin interpolates between frequency points to approximate the true stability margins.

ts — Sample time

integer

Sample time, specified as an integer. allmargin uses ts to find the stability margins from frequency response data.

• For continuous-time models, set ts = 0.

• For discrete-time models, ts is a positive integer representing the sampling period. To denote a discrete-time model with unspecified sample time, set ts = -1.

Output Arguments

S — Gain, phase, and delay margins

structure | structure array

Gain, phase, and delay margins, returned as a structure array.

The output S is a structure with the following fields:

• GMFrequency: All -180° (modulo 360°) crossover frequencies in rad/TimeUnit, where TimeUnit is the time units, specified in the TimeUnit property of L.

• GainMargin: Corresponding gain margins, defined as 1/G, where G is the gain at the -180° crossover frequency. Gain margins are in absolute units.

• PMFrequency: All 0-dB crossover frequencies in rad/TimeUnit, where TimeUnit is the time units, specified in the TimeUnit property of L.

• PhaseMargin: Corresponding phase margins in degrees.

• DelayMargin: The amount of delay needed to destabilize the closed-loop system. When the closed-loop system has multiple gain crossover frequencies, DelayMargin contains the delay margin at each crossover. The smallest entry in DelayMargin is the smallest delay needed to destabilize the closed-loop system. Delay margins are expressed in the time units of the system for continuous-time systems and in multiples of the sample time for discrete-time systems.

• DMFrequency: Gain crossover frequencies corresponding to the delay margins in DelayMargin. For each DelayMargin value, the corresponding DMFrequency value gives the frequency of oscillations resulting from applying this amount of delay.

• Stable: 1 if the nominal closed-loop system is stable, 0 if unstable, and NaN if stability cannot be assessed. In general, allmargin cannot assess the stability of an frd system.

When L is an M-by-M MIMO system, S is an M-by-1 structure array. For instance, S(j) gives the stability margins for the j-th feedback channel with all other loops closed (one-loop-at-a-time margins).

Tips

• allmargin assumes that the system with open-loop response L is a negative-feedback system. To compute the classical stability margins of the positive feedback system feedback(L,eye(M),+1), use allmargin(-L).

• To compute classical margins for a system modeled in Simulink^®, first linearize the model to obtain the open-loop response at a particular operating point. Then, use allmargin to compute classical stability margins for the linearized system. For more information, see Stability Margins of a Simulink Model (Robust Control Toolbox).

• If you have Robust Control Toolbox™ software, you can use diskmargin (Robust Control Toolbox) to compute disk-based margins that define a range of "safe" gain and phase variations for which the feedback loop remains stable.

Version History

Introduced before R2006a

R2024a: Specify frequency range for stability analysis

Use Focus=[fmin,fmax] to specify a frequency range for stability analysis. allmargin ignores stability issues outside the range you specify.

R2018b: Compute loop-at-a-time stability margins for MIMO system

S = allmargin(L) now computes the loop-at-a-time stability margins for MIMO L. Before R2018b, allmargin supported SISO systems only.