# sensitivity

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

## Syntax

## Description

`[`

calculates the value `J`

,`sens`

] = sensitivity(`mpcobj`

,`PerfFcn`

,`PerfWeights`

,`Ns`

,`r`

,`v`

,`SimOptions`

,`utarget`

)`J`

and sensitivity `sens`

of a
predefined closed-loop, cumulative performance metric with respect to the diagonal weights
defined in the MPC controller object `mpcobj`

. You chose the shape of the
performance metric, among the available options, using `PerfFcn`

. The
optional arguments `PerfWeights`

, `Ns`

,
`r`

, `v`

, `SimOptions`

, and
`utarget`

specify the performance metric weights, number of simulation
points, reference and disturbance signals, simulation options, and manipulated variables
targets, respectively. If you omit any of these arguments, then default values are
used.

`[`

calculates the value `J`

,`sens`

] = sensitivity(`mpcobj`

,`customPerFcn`

,`Par1,...,ParN`

)`J`

and sensitivity `sens`

of the
performance metric defined in the custom function `customPerFcn`

, with
respect to the diagonal weights defined in the MPC controller object
`mpcobj`

. The remaining input arguments
`Par1,Par2,...,ParN`

specify the value of the parameters needed by
`customPerFnc`

.

## Examples

### Calculate Value of Predefined Performance Metric and Its Sensitivity to Controller Weights

Fix the random number generator seed for reproducibility.

rng(0)

Define a third-order plant model with three manipulated variables and two controlled outputs. Then create an MPC controller for the plant, with sample time of `1`

.

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

-->"PredictionHorizon" is empty. Assuming default 10. -->"ControlHorizon" is empty. Assuming default 2. -->"Weights.ManipulatedVariables" is empty. Assuming default 0.00000. -->"Weights.ManipulatedVariablesRate" is empty. Assuming default 0.10000. -->"Weights.OutputVariables" is empty. Assuming default 1.00000.

Specify an integral absolute error performance function and set the performance weights. The performance weights emphasize tracking the first output variable.

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

Define a `20`

second simulation scenario with a unit step as setpoint for the first output and zero as a setpoint for the second output.

Tstop = 20; r = [1 0];

Calculate the closed-loop performance metric, `J`

, and its sensitivities, `sens`

, to the weights defined in `mpcobj`

, for the specified simulation scenario. For this example, do not specify the last three input argument of `sensitivity`

. This means that no disturbance signal or simulation option is used and the nominal value of the manipulated variables is kept to its default value of zero.

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

-->Converting model to discrete time. -->Assuming output disturbance added to measured output #1 is integrated white noise. -->Assuming output disturbance added to measured output #2 is integrated white noise. -->"Model.Noise" is empty. Assuming white noise on each measured output.

J = 2.2977

`sens = `*struct with fields:*
OutputVariables: [-0.1897 -0.0894]
ManipulatedVariables: [0.0311 0.0826 0.0014]
ManipulatedVariablesRate: [0.4268 2.3482 0.0149]

The positive, and relatively higher, values of the sensitivities to the first and last manipulated variable rate suggest that decreasing the corresponding weights defined in `mpcobj`

would contribute the most to decrease the `IAE`

performance metric defined by `PerfWts`

. At the same time, since the sensitivity to the weight of the second manipulated variable is negative, increasing the corresponding weight would also contribute to decrease the performance metric.

Modify the manipulated variable rate weights in `mpcobj`

and recalculate the value of the performance metric.

mpcobj.Weights.ManipulatedVariablesRate = [1e-2 1 1e-2]; sensitivity(mpcobj,PerfFunc,PerfWts,Tstop,r)

-->Converting model to discrete time. -->Assuming output disturbance added to measured output #1 is integrated white noise. -->Assuming output disturbance added to measured output #2 is integrated white noise. -->"Model.Noise" is empty. Assuming white noise on each measured output.

ans = 2.0116

As expected the value of the performance metric decreased, indicating an improved tracking performance.

### Calculate Value of Custom Performance Metric and Its Sensitivity to Controller Weights

Define a third-order plant model with three manipulated variables and two controlled outputs. Then create an MPC controller for the plant, with sample time of `1`

.

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

-->"PredictionHorizon" is empty. Assuming default 10. -->"ControlHorizon" is empty. Assuming default 2. -->"Weights.ManipulatedVariables" is empty. Assuming default 0.00000. -->"Weights.ManipulatedVariablesRate" is empty. Assuming default 0.10000. -->"Weights.OutputVariables" is empty. Assuming default 1.00000.

Define a custom performance function and write it to a file. The function must take an MPC object as a first input argument. The simulation time and the output set point are the second and third input arguments, respectively. Internally, the function performs a closed loop simulation using the given MPC object, simulation time and set point. The norm of the difference between the set point and the output signal is then returned as the value of the performance metric (note that this norm depends on the number of simulation steps).

% write a function to the char vector "str" str = ['function J = mypfun(mpcobj,T,ySetPnt)', ... newline, ... 'y = sim(mpcobj,T,ySetPnt); J = norm(ySetPnt-y);', ... newline, ... 'end']; % create the function file fid=fopen('mypfun.m','w'); % open a file for writing fwrite(fid,str,'char'); % write "str" to the file fclose(fid); % close the file

Calculate the custom performance metric, `J`

, and its sensitivities, `sens`

, to the weights defined in `mpcobj`

, using a simulation time of `10`

seconds and an output setpoint of [`1`

`1`

].

`[J,sens] = sensitivity(mpcobj,'mypfun',10,[1 1])`

-->Converting model to discrete time. -->Assuming output disturbance added to measured output #1 is integrated white noise. -->Assuming output disturbance added to measured output #2 is integrated white noise. -->"Model.Noise" is empty. Assuming white noise on each measured output.

J = 1.5145

`sens = `*struct with fields:*
OutputVariables: [-0.0507 -0.0888]
ManipulatedVariables: [0.0013 0.0055 3.7533e-05]
ManipulatedVariablesRate: [0.1918 1.2004 0.0034]

The comparatively higher values of the sensitivities to the manipulated variable rates suggest that decreasing the corresponding weights defined in `mpcobj`

would contribute the most to decrease the custom performance metric calculated in the function `mypfun`

.

## Input Arguments

`mpcobj`

— Model predictive controller

`mpc`

object

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

.

`PerfFcn`

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

.

**Note**

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 running 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 points, including zero

positive integer

Number of simulation points, including zero, specified as a positive integer. The
simulation runs for `Ns-1`

steps, between `0`

and
`Ts*(Ns-1)`

.

If you omit `Ns`

, the default value is the number of rows of
whichever of the following arrays has the largest number of rows:

**Example: **`20`

`r`

— Reference signal

`mpcobj.Model.Nominal.Y`

(default) | `double`

array

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

columns, where `ny`

is the number of total (measured and unmeasured)
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 Ns is empty or unspecified, it defaults to the nominal output vector
`mpcobj.Model.Nominal.Y`

.

**Example: **`ones(20,3)`

`v`

— Measured input disturbance signal

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

(default) | `double`

array

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

`customPerFcn`

— Name of the custom performance function

character vector

Name of the custom performance function, specified as a character vector. The
character vector must be different than `'ISE'`

,
`'IAE'`

, `'ITSE'`

, or `'ITAE'`

, and
specify the name of a file in the MATLAB^{®} path containing a custom function.

The custom function must have the following signature:

`J`

=
customPerFcn(`mpcobj`

,`Par1,...,ParN`

)

where `J`

is a scalar indicating the value of the performance
index `mpcobj`

is an `mpc`

object. The remaining arguments `Par1,...,ParN`

are
parameters that, if needed by `customPerFcn`

, you must pass to
`sensitivity`

after the `customPerFcn`

argument.

For example, inside `customPerFcn`

, you can use
`mpcobj`

and, if needed, `Par1,...,ParN`

, to
perform a simulation and calculate `J`

based on the simulation
results.

**Example: **`'myPerfFcn(mpcobj,Ts,Setpoint)'`

`Par1,...,ParN`

— Values of the parameters used by the custom performance function

values of any needed parameter

Values of the parameters used by the custom performance function
`customPerFcn`

, specified as needed.

**Example: **`10,[1 1]`

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

.

## Version History

**Introduced in R2009a**

## See Also

### Functions

### Objects

### Blocks

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