# umargin

## Description

Use the `umargin`

control design block to model gain and phase
variations in feedback loops. Modeling gain and phase variations in your system lets you
verify stability margins during robustness analysis or enforce them during robust controller
design.

To add gain and phase uncertainty to a feedback loop, you incorporate
`umargin`

blocks into an uncertain state-space (`uss`

) model
of the closed-loop system. `umargin`

is a SISO control design block,
representing gain and phase variation at a single location in a single feedback loop. To model
gain and phase uncertainty in MIMO feedback systems, insert a separate
`umargin`

object at each location in the system at which you want to
introduce gain and phase uncertainty.

`umargin`

models gain and phase variations as a factor *F*
multiplying the open-loop response *L*. This factor takes values in a disk
centered on the real axis and containing *F* = 1. You specify this disk by
its intersection `DGM = [gmin,gmax]`

with the real axis, which represents the
relative amount of gain variation around the nominal value *F* = 1. To
specify both gain and phase uncertainty, first use `getDGM`

to obtain
a `DGM`

value that describes a disk that captures both your specified gain
and phase ranges. For more information about the disk-based uncertainty model, see Algorithms.

When you have a `uss`

model containing `umargin`

control
design blocks, you can perform robustness and worst-case analysis to examine how gain and
phase variation affects the response of the system. For instance, use `robstab`

and `robgain`

to analyze the robust stability and
robust performance of a system with gain and phase uncertainty. Use `wcgain`

and `wcsigmaplot`

to
examine the worst-case responses of the system.

Requiring robust stability for a closed-loop system with `umargin`

gain and
phase uncertainty is equivalent to enforcing a disk-based gain margin
`[gmin,gmax]`

and corresponding phase margin. Therefore, you can use
`umargin`

blocks to enforce suitable disk margins when designing robust
controllers with `musyn`

.

## Creation

### Description

models relative gain uncertainty in the range `F`

= umargin(`name`

,`DGM`

)`DGM = [gmin,gmax]`

with
`gmin`

< 1 and `gmax`

> 1. The gain modeled by
`F`

varies in this range for phase held at its nominal value. When
you have both gain and phase uncertainty, use `getDGM`

to
find the corresponding `DGM`

. This syntax also sets the
`Name`

property of `F`

.

is the same as `F`

= umargin(`name`

,`GM`

)`umargin(name,[1/GM,GM])`

. This syntax specifies a gain
that can increase or decrease by a factor `GM`

in the absence of phase
uncertainty. The corresponding amount of phase uncertainty is determined by the disk-based
uncertainty model that `umargin`

uses (see Algorithms).

sets additional properties of
`F`

= umargin(___,`Name,Value`

)`F`

using name-value pairs. For example, ```
F =
umargin('F',[0.8,1.4],'InputName','u0','OutputName','u')
```

creates a
`umargin`

block and sets the input and output names for use with
`connect`

. Enclose each property name in quotes.

### Input Arguments

## Properties

## Object Functions

Many functions that work on numeric LTI models also work on uncertain control design
blocks such as `umargin`

. These include model interconnection functions such as
`connect`

and `feedback`

, and linear analysis
functions such as `bode`

and `stepinfo`

. Some functions
that generate plots, such as `bode`

and `step`

, plot
random samples of the uncertain model to give you a sense of the distribution of uncertain
dynamics. When you use these commands to return data, however, they operate on the nominal
value of the system only. The following lists contain a representative subset of the functions
you can use with `umargin`

models.

## Examples

## Algorithms

`umargin`

models gain and phase variations in an individual feedback channel as
a frequency-dependent multiplicative factor *F*(*s*)
multiplying the nominal open-loop response *L*(*s*), such
that the perturbed response is
*L*(*s*)*F*(*s*).
The factor *F*(*s*) is parameterized by:

$$F\left(s\right)=\frac{1+\alpha \left[\left(1-\sigma \right)/2\right]\delta \left(s\right)}{1-\alpha \left[\left(1+\sigma \right)/2\right]\delta \left(s\right)}.$$

In this model,

*δ*(*s*) is a gain-bounded dynamic uncertainty, normalized so that it always varies within the unit disk (||*δ*||_{∞}< 1).*ɑ*sets the amount of gain and phase variation modeled by*F*. For fixed*σ*, the parameter*ɑ*controls the size of the disk. For*ɑ*= 0, the multiplicative factor is 1, corresponding to the nominal*L*.*σ*, called the*skew*, biases the modeled uncertainty toward gain increase or gain decrease.

The factor *F* takes values in a disk centered on the real axis and
containing the nominal value *F* = 1. The disk is characterized by its
intercept `DGM = [gmin,gmax]`

with the real axis. `gmin`

< 1 and `gmin`

> 1 are the minimum and maximum relative changes in gain
modeled by *F*, at nominal phase. The phase uncertainty modeled by
*F* is the range `DPM = [pmin,pmax]`

of phase values
at the nominal gain (|*F*| = 1). For instance, in the following plot, the
right side shows the disk *F* that intersects the real axis in the interval
[0.71,1.4]. The left side shows that this disk models a gain variation of ±3 dB and a phase
variation of ±19°.

```
F = umargin('F',1.4125)
plot(F)
```

When you create a `umargin`

block, you specify the amount of uncertainty by
specifying `DGM`

. Use `getDGM`

to
translate specific amounts of gain and phase variations in to a suitable
`DGM`

range that captures these variations. For more information about
the uncertainty model used by `umargin`

, see Stability Analysis Using Disk Margins.

## Version History

**Introduced in R2020a**