margin

Gain margin, phase margin, and crossover frequencies

Syntax

margin(sys)

margin(sys,w)

[Gm,Pm,Wcg,Wcp] = margin(sys)

[Gm,Pm] = margin(sys,J1,...,JN)

[Gm,Pm,Wcg,Wcp] = margin(sys,Focus=[fmin,fmax])

[Gm,Pm,Wcg,Wcp] = margin(mag,phase,w)

Description

Margin Plots

margin(sys) plots the Bode response of sys on the screen and indicates the gain and phase margins on the plot. Gain margins are expressed in dB on the plot.

Solid vertical lines mark the gain margin and phase margin. The dashed vertical lines indicate the locations of Wcp, the frequency where the phase margin is measured, and Wcg, the frequency where the gain margin is measured. The plot title includes the magnitude and location of the gain and phase margin.

Gm and Pm of a system indicate the relative stability of the closed-loop system formed by applying unit negative feedback to sys, as shown in the following figure.

Gm is the amount of gain variance required to make the loop gain unity at the frequency Wcg where the phase angle is –180° (modulo 360°). In other words, the gain margin is 1/g if g is the gain at the –180° phase frequency. Similarly, the phase margin is the difference between the phase of the response and –180° when the loop gain is 1.0. The frequency Wcp at which the magnitude is 1.0 is called the unity-gain frequency or gain crossover frequency. When sys has more than one crossover, margin indicates the frequencies with gain margin closest to 0 dB and phase margin closest to 0°.

Usually, gain margins of 3 or more combined with phase margins between 30° and 60° result in reasonable tradeoffs between bandwidth and stability. However, in some multivariable systems, stability can be lost at a different frequency for much smaller gain and phase variations. For such systems, the notion of disk margins provides more reliable estimates of the true gain and phase margins. For more information on disk margins, see diskmargin (Robust Control Toolbox).

margin(sys,w) plots the Bode response of sys using the vector of frequencies w in rad/TimeUnit. Use this syntax when you have sparse models like sparss or mechss model objects.

Margin Values

[Gm,Pm,Wcg,Wcp] = margin(sys) returns the gain margin Gm in absolute units, the phase margin Pm, and the corresponding frequencies Wcg and Wcp, of sys. Wcg is the frequency where the gain margin is measured, which is a –180° phase crossing frequency. Wcp is the frequency where the phase margin is measured, which is a 0-dB gain crossing frequency. These frequencies are expressed in radians/TimeUnit, where TimeUnit is the unit specified in the TimeUnit property of sys. When sys has several crossovers, margin returns the smallest gain and phase margins and corresponding frequencies.

margin returns a warning if your system is not internally stable, that is, if your system is not closed-loop stable or contains pole-zero cancellations outside of the open left-half plane.

[Gm,Pm] = margin(sys,J1,...,JN) returns the gain margin Gm and phase margin Pm of the entries in model array sys with subscripts (J1,...,JN).

[Gm,Pm,Wcg,Wcp] = margin(sys,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)

[Gm,Pm,Wcg,Wcp] = margin(mag,phase,w) derives the gain and phase margins from frequency response data. Provide the gain data mag in absolute units, and phase data phase in degrees. You can provide the frequency vector w in any units and margin returns Wcg and Wcp in the same units.

Examples

Plot Gain and Phase Margins of Transfer Function

For this example, create a continuous transfer function.

sys = tf(1,[1 2 1 0])

sys =
 
         1
  ---------------
  s^3 + 2 s^2 + s
 
Continuous-time transfer function.

Display the gain and phase margins graphically.

margin(sys)

The gain margin (6.02 dB) and phase margin (21.4 deg), displayed in the title, are marked with solid vertical lines. The dashed vertical lines indicate the locations of Wcg, the frequency where the gain margin is measured, and Wcp, the frequency where the phase margin is measured.

Gain and Phase Margins of Transfer Function

For this example, create a discrete-time transfer function.

sys = tf([0.04798 0.0464],[1 -1.81 0.9048],0.1)

sys =
 
   0.04798 z + 0.0464
  ---------------------
  z^2 - 1.81 z + 0.9048
 
Sample time: 0.1 seconds
Discrete-time transfer function.

Compute the gain margin, phase margin and frequencies.

[Gm,Pm,Wcg,Wcp] = margin(sys)

Gm = 
2.0519

Pm = 
13.5711

Wcg = 
5.4376

Wcp = 
4.3544

The results indicate that a gain variation of over 2.05 (6.24 dB) at the phase crossover frequency of 5.43 rad/s would cause the system to be unstable. Similarly a phase variation of over 13.57 degrees at the gain crossover frequency of 4.35 rad/s will cause the system to lose stability.

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 system, with dynamics at both relatively low frequencies and relatively high frequencies.

sys = tf(5,[1 1 10]) + tf(5e3,[1 20 1e4]);
damp(sys)

                                                                       
         Pole              Damping       Frequency      Time Constant  
                                       (rad/seconds)      (seconds)    
                                                                       
 -5.00e-01 + 3.12e+00i     1.58e-01       3.16e+00         2.00e+00    
 -5.00e-01 - 3.12e+00i     1.58e-01       3.16e+00         2.00e+00    
 -1.00e+01 + 9.95e+01i     1.00e-01       1.00e+02         1.00e-01    
 -1.00e+01 - 9.95e+01i     1.00e-01       1.00e+02         1.00e-01    

The stability of the closed-loop system CL = feedback(sys,1) against perturbations at low frequency can be different from that at higher frequencies. To see the difference, use the Focus option. First, examine the margins below 10 rad/s.

[GmL,PmL,WcgL,WcpL] = margin(sys,Focus=[0 10])

GmL = 
Inf

PmL = 
80.9920

WcgL = 
NaN

WcpL = 
3.5137

Examine the margins about 10 rad/s.

[GmH,PmH,WcgH,WcpH] = margin(sys,Focus=[10 Inf])

GmH = 
Inf

PmH = 
28.6437

WcgH = 
Inf

WcpH = 
119.9618

Gain and Phase Margins Using 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('openLoopFRD.mat','p','m','w');

Compute the gain and phase margins.

[Gm,Pm,Wcg,Wcp] = margin(m,p,w)

Gm = 
0.6249

Pm = 
48.9853

Wcg = 
1.2732

Wcp = 
1.5197

Gain and Phase Margins of Models in an Array

For this example, load invertedPendulumArray.mat, which contains a 3-by-3 array of inverted pendulum 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 gain and phase margin for all models in the array.

[Gm,Pm] = margin(sys)

Gm = 3×3

    0.9800    0.9800    0.9800
    0.9800    0.9800    0.9800
    0.9800    0.9800    0.9800

Pm = 3×3

  -11.3798  -11.4118  -11.4433
  -11.4059  -11.4296  -11.4532
  -11.4228  -11.4410  -11.4592

margin returns two arrays, Gm and Pm, in which each entry is the gain and phase margin values of the corresponding entry in sys. For instance, the gain and phase margin of the model with 100g pendulum weight and 2m length is Gm(1,2) and Pm(1,2), respectively.

Input Arguments

sys — Dynamic system

dynamic system model | model array

Dynamic system, specified as a SISO dynamic system model, or an array of SISO dynamic system models. Dynamic systems that you can use include continuous-time or discrete-time numeric LTI models such as tf, zpk, ss, sparss or mechss models.

If sys is a generalized state-space model genss or an uncertain state-space model uss, margin returns the gain margin and phase margin of the current or nominal value of sys. If sys is an array of models, margin returns the Gm and Pm of the model corresponding to its subscript J1,...,JN in sys. For more information on model arrays, see Model Arrays.

J — Indices of models in array whose gain and phase margins you want to extract

positive integer

Indices of models in array whose gain and phase margins you want to extract, specified as positive integers. You can provide as many indices as there are array dimensions in sys. For example, if sys is a 4-by-5 array of dynamic system models, the following command extracts Gm and Pm for entry (2,3) in the array.

[Gm,Pm] = margin(sys,2,3);

[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. Since margin only accepts SISO systems, mag is a 1-by-1-by-N array, where N is the number of frequency points. For an example, see Obtain Magnitude and Phase Data.

phase — Phase of system response

3-D array

Phase of the system response in degrees, specified as a 3-D array. Since margin only accepts SISO systems, phase is a 1-by-1-by-N array, where N is the number of frequency points. For an example, see Obtain Magnitude and Phase Data.

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.

Output Arguments

Gm — Gain margin

scalar | array

Gain margin, returned as a scalar or an array. If sys is:

• A single model, then Gm is returned as a scalar.

• A model array, then Gm is an array of gain margins of each model in sys.

Gm is the amount of gain variance required to make the loop gain unity at the frequency Wcg where the phase angle is –180° (modulo 360°). In other words, the gain margin is 1/g if g is the gain at the –180° phase frequency. When sys has several crossovers, margin returns the gain margin closest to 0 dB. Negative gain margins indicate that stability is lost by decreasing the gain, while positive gain margins indicate that stability is lost by increasing the gain.

The gain margin Gm is computed in absolute units. You can compute the gain margin in dB by,

Gm_dB = 20*log10(Gm)

Pm — Phase margin

scalar | array

Phase margin, returned as a scalar or an array. If sys is:

• A single model, then Pm is returned as a scalar.

• A model array, then Pm is an array of phase margins of each model in sys.

The phase margin is the difference between the phase of the response and –180° when the loop gain is 1.0. When sys has several crossovers, margin returns the phase margin closest to 0°.

The phase margin Pm is expressed in degrees.

Wcg — Phase crossover frequency

scalar

Phase crossover frequency, returned as a scalar. Wcg is the frequency where the gain margin is measured, which is a –180° phase crossing frequency.

Wcg is expressed in radians/TimeUnit, where TimeUnit is the unit specified in the TimeUnit property of sys.

Wcp — Gain crossover frequency

scalar

Gain crossover frequency, returned as a scalar. Wcp is the frequency where the phase margin is measured, which is a 0-dB gain crossing frequency.

Wcp is expressed in radians/TimeUnit, where TimeUnit is the unit specified in the TimeUnit property of sys.

Tips

• When you use margin(mag,phase,w), margin relies on interpolation to approximate the margins, which generally produce less accurate results. For example, if there is no 0-dB crossing within the w range, margin returns a phase margin of Inf. Therefore, if you have an analytical model sys, using [Gm,Pm,Wcg,Wcp] = margin(sys) is a more robust way to obtain the margins.

• 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. margin ignores stability issues outside the range you specify.

R2021b: Support for systems with complex coefficients

Visualize and analyze stability margins of systems with complex coefficients.

R2021a: Support for sparse models

Plot the frequency response of sparss and mechss models using margin. You must provide a frequency vector or frequency range with the argument w.