# 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

example

````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

example

````[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. ```

example

````[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)`.```

example

````[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)```

example

````[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

collapse all

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.

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.

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 ```

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

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 ```

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}& Column\phantom{\rule{0.5em}{0ex}}1& Column\phantom{\rule{0.5em}{0ex}}2& Column\phantom{\rule{0.5em}{0ex}}3\\ Row\phantom{\rule{0.5em}{0ex}}1& 100g,3m& 100g,2m& 100g,1m\\ Row\phantom{\rule{0.5em}{0ex}}2& 200g,3m& 200g,2m& 200g,1m\\ Row\phantom{\rule{0.5em}{0ex}}3& 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

collapse all

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.

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);`

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]`

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 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.

Frequencies at which the magnitude and phase values of system response are obtained, specified as a column vector.

## Output Arguments

collapse all

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) ```

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.

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`.

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

expand all