# sensitivity

Calculate the value of a performance metric and its sensitivity to the diagonal weights of an MPC controller

## Description

`[`

calculates the user-defined, closed-loop, cumulative scalar performance metric
`J`

,`sens`

] = sensitivity(`MPCobj`

,`PerfFunc`

,`PerfWeights`

,`Ns`

,`r`

,`v`

,`SimOptions`

,`utarget`

)`J`

, and its sensitivity `sens`

to the diagonal weights
defined in the MPC controller object `MPCobj`

.
`PerfFunc`

specifies the shape of the performance metric, while the
optional arguments `PerfWeights`

, `Ns`

,
`r`

, `v`

, `SimOptions`

, and
`utarget`

specify the performance metric weights, simulation steps,
reference and disturbance signals, simulation options, and manipulated variables targets,
respectively.

## Examples

### Calculate Value of Performance Metric and its Sensitivity to Controller Weights

Define a third-order plant model with three manipulated variables and two controlled outputs.

plant = rss(3,2,3); plant.D = 0;

Create an MPC controller for the plant.

mpcobj = mpc(plant,1);

-->The "PredictionHorizon" property of "mpc" object is empty. Trying PredictionHorizon = 10. -->The "ControlHorizon" property of the "mpc" object is empty. Assuming 2. -->The "Weights.ManipulatedVariables" property of "mpc" object is empty. Assuming default 0.00000. -->The "Weights.ManipulatedVariablesRate" property of "mpc" object is empty. Assuming default 0.10000. -->The "Weights.OutputVariables" property of "mpc" object is empty. Assuming default 1.00000.

Specify an integral absolute error performance function and set the performance weights.

```
PerfFunc = 'IAE';
PerfWts.OutputVariables = [1 0.5];
PerfWts.ManipulatedVariables = zeros(1,3);
PerfWts.ManipulatedVariablesRate = zeros(1,3);
```

Define a `20`

second simulation scenario with a unit step in the output 1 setpoint and a setpoint of zero for output 2.

Tstop = 20; r = [1 0];

Define the nominal values of the manipulated variables to be zeros.

utarget = zeros(1,3);

Calculate the closed-loop performance metric, `J`

, and its sensitivities, `sens`

, to the weight defined in `mpcobj`

, for the specified simulation scenario.

[J,sens] = sensitivity(mpcobj,PerfFunc,PerfWts,Tstop,r,[],[],utarget)

-->Converting model to discrete time. -->Assuming output disturbance added to measured output channel #1 is integrated white noise. -->Assuming output disturbance added to measured output channel #2 is integrated white noise. -->The "Model.Noise" property of the "mpc" object is empty. Assuming white noise on each measured output channel.

J = 1.1426

`sens = `*struct with fields:*
OutputVariables: [-0.0041 -0.1285]
ManipulatedVariables: [0.0378 -0.0465 0.0523]
ManipulatedVariablesRate: [0.4007 0.2433 0.6805]

The positive, and relatively higher, values of the sensitivities to the manipulated variable rates suggest that decreasing the weights that are defined in `mpcobj`

for the manipulated variable rates would contribute the most to decrease the `IAE`

performance metric defined by `PerfWts`

.

## Input Arguments

`MPCobj`

— Model predictive controller

MPC controller object

Model predictive controller, specified as an MPC controller
object. To create an MPC controller, use `mpc`

.

`PerfFunc`

— Performance metric function shape

`'ISE'`

| `'IAE'`

| `'ITSE'`

| `'ITAE'`

Performance metric function shape, specified as one of the following:

`'ISE'`

(integral squared error), for which the performance metric is$$J={\displaystyle \sum _{i=1}^{Ns}\left({\displaystyle \sum _{j=1}^{{n}_{y}}{({w}_{j}^{y}{e}_{yij})}^{2}+{\displaystyle \sum _{j=1}^{{n}_{u}}[{({w}_{j}^{u}{e}_{uij})}^{2}+{({w}_{j}^{\Delta u}\Delta {u}_{ij})}^{2}]}}\right)}$$

`'IAE'`

(integral absolute error), for which the performance metric is$$J={\displaystyle \sum _{i=1}^{Ns}\left({\displaystyle \sum _{j=1}^{{n}_{y}}\left|{w}_{j}^{y}{e}_{yij}\right|+{\displaystyle \sum _{j=1}^{{n}_{u}}(|{w}_{j}^{u}{e}_{uij}|+|{w}_{j}^{\Delta u}\Delta {u}_{ij}|)}}\right)}$$

`'ITSE'`

(integral of time-weighted squared error), for which the performance metric is$$J={\displaystyle \sum _{i=1}^{Ns}i\Delta t\left({\displaystyle \sum _{j=1}^{{n}_{y}}{({w}_{j}^{y}{e}_{yij})}^{2}+{\displaystyle \sum _{j=1}^{{n}_{u}}[{({w}_{j}^{u}{e}_{uij})}^{2}+{({w}_{j}^{\Delta u}\Delta {u}_{ij})}^{2}]}}\right)}$$

`'ITAE'`

(integral of time-weighted absolute error), for which the performance metric is$$J={\displaystyle \sum _{i=1}^{Ns}i\Delta t}\left({\displaystyle \sum _{j=1}^{{n}_{y}}\left|{w}_{j}^{y}{e}_{yij}\right|+{\displaystyle \sum _{j=1}^{{n}_{u}}(|{w}_{j}^{u}{e}_{uij}|+|{w}_{j}^{\Delta u}\Delta {u}_{ij}|)}}\right)$$

In these expressions, *n _{y}* is the number of
controlled outputs and

*n*is the number of manipulated variables,

_{u}*e*is the difference between output

_{yij}*j*and its setpoint (or reference) value at time interval

*i*,

*e*is the difference between the manipulated variable

_{uij}*j*and its target at time interval

*i*.

The *w* parameters are nonnegative performance weights defined by
the structure `PerfWeights`

.

**Example: **`'ITAE'`

`PerfWeights`

— Performance function weights

`MPCobj.Weights`

(default) | structure

Performance function weights *w*, specified as a structure with
the following fields:

`OutputVariables`

—*n*-element row vector that contains the $${w}_{j}^{y}$$ values_{y}`ManipulatedVariables`

—*n*-element row vector that contains the $${w}_{j}^{u}$$ values_{u}`ManipulatedVariablesRate`

—*n*-element row vector that contains the $${w}_{j}^{\Delta u}$$ values_{u}

If `PerfWeights`

is empty or unspecified, it defaults to the
corresponding weights in `MPCobj`

. In general, however, the performance
index is not related to the quadratic cost function that the MPC controller tries to
minimize by choosing the values of the manipulated variables. One clear difference is
that the performance index is based on a *closed loop* simulation
until a time that is generally different than the prediction horizon, while the MPC
controller calculates the moves which minimize its internal cost function up to the
prediction horizon and in *open loop* fashion. Furthermore, even when
the performance index is chosen to be of ISE type, its weights should be squared to
match the weights defined in the MPC cost function.

Therefore, the performance weights and those used in the controller have different purposes; define these weights accordingly.

`Ns`

— Number of simulation steps

positive integer

Number of simulation steps, specified as a positive integer.

If you omit `Ns`

, the default value is the row size of whichever
of the following arrays has the largest row size:

**Example: **`100`

`r`

— Reference signal

`MPCobj.Model.Nominal.Y`

(default) | matrix

Reference signal, specified as an array. This array has `ny`

columns, where `ny`

is the number of plant outputs.
`r`

can have anywhere from 1 to `Ns`

rows. If
the number of rows is less than `Ns`

, the missing rows are set equal
to the last row.

If `r`

is empty or unspecified, it defaults to the nominal value of
the plant output, `MPCobj.Model.Nominal.Y`

.

**Example: **`ones(100,1)`

`v`

— Measured disturbance signal

`MPCobj.Model.Nominal.U(md)`

(default) | matrix

Measured disturbance signal, specified as an array. This array has
`nv`

columns, where `nv`

is the number of measured
input disturbances. `v`

can have anywhere from 1 to
`Ns`

rows. If the number of rows is less than
`Ns`

, the missing rows are set equal to the last row.

If `v`

is empty or unspecified, it defaults to the nominal value of
the measured input disturbance, `MPCobj.Model.Nominal.U(md)`

, where
`md`

is the vector containing the indices of the measured disturbance
signals, as defined by `setmpcsignals`

.

**Example: **`[zeros(50,1);ones(50,1)]`

`SimOptions`

— Simulation options object

`[]`

(default) | `mpcsimopt`

object

Use a simulation options objects to specify options such as noise and disturbance
signals that feed into the plant but are unknown to the controller. You can also use
this object to specify an open loop scenario, or a plant model in the loop that is
different from the one in `MPCobj.Model.Plant`

.

For more information, see `mpcsimopt`

.

`utarget`

— Target for manipulated variables

`MPCobj.Model.Nominal.U`

(default) | vector

The optional input `utarget`

is a vector of
*n _{u}* manipulated variable targets. Their
defaults are the nominal values of the manipulated variables.

**Example: **`[0.1;0;-0.2]`

## Output Arguments

`sens`

— Sensitivity of the performance metric

structure

This structure contains and the numerical partial derivatives of the performance
measure `J`

with respect to its diagonal weights. These partial
derivatives, also called *sensitivities*, suggest weight adjustments
that should improve performance; that is, reduce `J`

.

**Introduced in R2009a**

## Open Example

You have a modified version of this example. Do you want to open this example with your edits?

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

# Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

## How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)