# mpc

Create MPC controller

## Syntax

• ``MPCobj = mpc(Plant)``
• ``MPCobj = mpc(Plant,Ts)``
• ``MPCobj = mpc(Plant,Ts,p,m,W,MV,OV,DV)``
• ``MPCobj = mpc(Models,Ts,p,m,W,MV,OV,DV)``

## Description

````MPCobj = mpc(Plant)` creates a Model Predictive Controller object based on a discrete-time prediction model. The prediction model `Plant` can be either an LTI model with a specified sample time, or a System Identification model (see Identify Plant from Data). The controller, `MPCobj`, inherits its control interval from `Plant.Ts`, and its time unit from `Plant.TimeUnit`. All other controller properties are default values. After you create the MPC controller, you can set its properties using ```MPCobj.PropertyName = PropertyValue```.`MPCobj = mpc(Plant,Ts)` specifies a control interval of `Ts`. If `Plant` is a discrete-time LTI model with an unspecified sample time (`Plant.Ts` = –1), it inherits sample time `Ts` when used for predictions.`MPCobj = mpc(Plant,Ts,p,m,W,MV,OV,DV)` specifies additional controller properties such as the prediction horizon (`p`), control horizon (`m`), and input, input increment, and output weights (`W`). You can also set the properties of manipulated variables (`MV`), output variables (`OV`), and input disturbance variables (`DV`). If any of these values are omitted or empty, the default values apply.```
````MPCobj = mpc(Models,Ts,p,m,W,MV,OV,DV)` creates a Model Predictive Controller object based on a prediction model set, `Models`. This set includes plant, input disturbance, and measurement noise models along with the nominal conditions at which the models were obtained.```

## Input Arguments

 `Plant` Plant model to be used in predictions, specified as an LTI model (`tf`, `ss`, or `zpk`) or a System Identification Toolbox™ model. If the `Ts` input argument is unspecified, `Plant` must be a discrete-time LTI object with a specified sample time, or a System Identification Toolbox model. Unless you specify otherwise, controller design assumes that all plant inputs are manipulated variables and all plant outputs are measured. Use the `setmpcsignals` command or the LTI `InputGroup` and `OutputGroup` properties to designate other signal types. `Ts` Controller sample time (control interval), specified as a positive scalar value. `p` Prediction horizon, specified as a positive integer. The control interval, `Ts`, determines the duration of each step. The default value is 10 + maximum intervals of delay (if any). `m` Control horizon, specified as a scalar integer, 1 ≤ `m` ≤ `p`, or as a vector of blocking factors such that `sum(m)` ≤ `p` (see Optimization Variables). The default value is 2. `W` Controller tuning weights, specified as a structure. For details about how to specify this structure, see Weights. `MV` Bounds and other properties of manipulated variables, specified as a 1-by-`nu` structure array, where `nu` is the number of manipulated variables defined in the plant model. For details about how to specify this structure, see ManipulatedVariables. `OV` Bounds and other properties of the output variables, specified as a 1-by-`ny` structure array, where `ny` is the number of output variables defined in the plant model. For details about how to specify this structure, see OutputVariables. `DV` Scale factors and other properties of the disturbance inputs, specified as a 1-by-`nd` structure array, where `nd` is the number of disturbance inputs (measured + unmeasured) defined in the plant model. For details about how to specify this structure, see DisturbanceVariables. `Models` Plant, input disturbance, and measurement noise models, along with the nominal conditions at which these models were obtained, specified as a structure. For details about how to specify this structure, see Model.

## Construction and Initialization

To minimize computational overhead, Model Predictive Controller creation occurs in two phases. The first happens at construction when you invoke the `mpc` command, or when you change a controller property. Construction involves simple validity and consistency checks, such as signal dimensions and non-negativity of weights.

The second phase is initialization, which occurs when you use the object for the first time in a simulation or analytical procedure. Initialization computes all constant properties required for efficient numerical performance, such as matrices defining the optimal control problem and state estimator gains. Additional, diagnostic checks occur during initialization, such as verification that the controller states are observable.

By default, both phases display informative messages in the command window. You can turn these messages on or off using the `mpcverbosity` command.

## Properties

All of the parameters defining the traditional (implicit) MPC control law are stored in an MPC object, whose properties are listed in the following table.

MPC Controller Object

Property

Description

`ManipulatedVariables` (or `MV` or `Manipulated` or `Input`)

Scale factors, input bounds, input-rate bounds, corresponding ECR values, target values, signal names, and units.

`OutputVariables` (or `OV` or `Controlled` or `Output`)

Scale factors, input bounds, input-rate bounds, corresponding ECR values, target values, signal names, and units.

`DisturbanceVariables` (or `DV` or `Disturbance`)

Disturbance scale factors, names, and units

`Weights`

Weights used in computing the performance (cost) function

`Model`

Plant, input disturbance, and output noise models, and nominal conditions.

`Ts`

Controller sample time

`Optimizer`

Parameters controlling the QP solver

`PredictionHorizon`

Prediction horizon

`ControlHorizon`

Number of free control moves or vector of blocking moves

`History`

Creation time

`Notes`

`UserData`

### ManipulatedVariables

`ManipulatedVariables` (or `MV` or `Manipulated` or `Input`) is an nu-dimensional array of structures (nu = number of manipulated variables), one per manipulated variable. Each structure has the fields described in the following table, where p denotes the prediction horizon. Unless indicated otherwise, numerical values are in engineering units.

Manipulated Variable Structure

Field Name

Content

Default

`ScaleFactor`

Nonnegative scale factor for this MV

1

`Min`

1 to p length vector of lower bounds on this MV

`-Inf`

`Max`

1 to p length vector of upper bounds on this MV

`Inf`

`MinECR`

1 to p length vector of nonnegative parameters specifying the `Min` bound softness (0 = hard).

`0` (dimensionless)

`MaxECR`

1 to p length vector of nonnegative parameters specifying the `Max` bound softness (0 = hard).

`0` (dimensionless)

`Target`

1 to p length vector of target values for this MV

`'nominal'`

`RateMin`

1 to p length vector of lower bounds on the interval-to-interval change for this MV

`-Inf`

`RateMax`

1 to p length vector of upper bounds on the interval-to-interval change for this MV

`Inf`

`RateMinECR`

1 to p length vector of nonnegative parameters specifying the `RateMin` bound softness (0 = hard).

`0` (dimensionless)

`RateMaxECR`

1 to p length vector of nonnegative parameters specifying the `RateMax` bound softness (0 = hard).

`0` (dimensionless)

`Name`

Read-only MV signal name (character string)

`InputName` of LTI plant model

`Units`

Read-only MV signal units (character string)

`InputUnit` of LTI plant model

 Note   Rates refer to the difference Δu(k)=u(k)-u(k-1). Constraints and weights based on derivatives du/dt of continuous-time input signals must be properly reformulated for the discrete-time difference Δu(k), using the approximation du/dt ≅ Δu(k)/Ts.

### OutputVariables

`OutputVariables `(or` OV` or `Controlled` or `Output`) is an ny-dimensional array of structures (ny = number of outputs), one per output signal. Each structure has the fields described in the following table. p denotes the prediction horizon. Unless specified otherwise, values are in engineering units.

Output Variable Structure

Field Name

Content

Default

`ScaleFactor`

Nonnegative scale factor for this OV

1

`Min`

1 to p length vector of lower bounds on this OV

`-Inf`

`Max`

1 to p length vector of upper bounds on this OV

`Inf`

`MinECR`

1 to p length vector of nonnegative parameters specifying the `Min` bound softness (0 = hard).

`1` (dimensionless)

`MaxECR`

1 to p length vector of nonnegative parameters specifying the `Max` bound softness (0 = hard).

`1` (dimensionless)

`Name`

Read-only OV signal name (character string)

`OutputName` of LTI plant model

`Units`

Read-only OV signal units (character string)

`OutputUnit` of LTI plant model

In order to reject constant disturbances due, for instance, to gain nonlinearities, the default measured output disturbance model used in Model Predictive Control Toolbox™ software is integrated white noise (see Output Disturbance Model).

### DisturbanceVariables

`DisturbanceVariables` (or `DV` or `Disturbance`) is an (nv+nd)-dimensional array of structures (nv = number of measured input disturbances, nd = number of unmeasured input disturbances). Each structure has the fields described in the following table.

Disturbance Variable Structure

Field Name

Content

Default

`ScaleFactor`

Nonnegative scale factor for this DV

1

`Name`

Read-only DV signal name (character string)

`InputName` of LTI plant model

`Units`

Read-only DV signal units (character string)

`InputUnit` of LTI plant model

The order of the disturbance signals within the array `DV` is the following: the first nv entries relate to measured input disturbances, the last nd entries relate to unmeasured input disturbances.

### Weights

`Weights` is the structure defining the QP weighting matrices. It contains four fields. The values of these fields depend on whether you are using the standard quadratic cost function (see Standard Cost Function) or the alternative cost function (see Alternative Cost Function).

#### Standard Cost Function

The following table lists the content of the four structure fields. In the table, p denotes the prediction horizon, nu the number of manipulated variables, and ny the number of output variables.

For the `MV`, `MVRate` and `OV` weights, if you specify fewer than p rows, the last row repeats automatically to form a matrix containing p rows.

Weights for the Standard Cost Function

Field Name (Abbreviations)

Content

Default (dimensionless)

`ManipulatedVariables` (or `MV` or `Manipulated` or `Input`)

(1 to p)-by-nu dimensional array of nonnegative MV weights

`zeros(1,nu)`

`ManipulatedVariablesRate` (or `MVRate` or `ManipulatedRate` or `InputRate`)

(1 to p)-by-nu dimensional array of MV-increment weights

`0.1*ones(1,nu)`

`OutputVariables `(or` OV` or `Controlled` or `Output`)

(1 to p)-by-ny dimensional array of OV weights

`1` (The default for output weights is the following: if nuny, all outputs are weighted with unit weight; if nu<ny, nu outputs default to 1, with preference given to measured outputs, and the rest default to 0.)

`ECR`

Scalar weight on the slack variable ɛ used for constraint softening

`1e5*(max weight)`

 Note   If all `MVRate` weights are strictly positive, the resulting QP problem is strictly convex. If some `MVRate` weights are zero, the QP Hessian could be positive semidefinite. In order to keep the QP problem strictly convex, when the condition number of the Hessian matrix KΔU is larger than 1012, the quantity `10*sqrt(eps)` is added to each diagonal term. See Cost Function.

#### Alternative Cost Function

You can specify off-diagonal Q and R weight matrices in the cost function. To do so, define the fields `ManipulatedVariables`, `ManipulatedVariablesRate`, and `OutputVariables` as cell arrays, each containing a single positive-semi-definite matrix of the appropriate size. Specifically, `OutputVariables` must be a cell array containing the ny-by-ny Q matrix, `ManipulatedVariables` must be a cell array containing the nu-by-nu Ru matrix, and `ManipulatedVariablesRate` must be a cell array containing the nu-by-nu RΔu matrix (see Alternative Cost Function and the `mpcweightsdemo` example). You can use diagonal weight matrices for one or more of these fields. If you omit a field, the MPC controller uses the defaults shown in the table above.

For example, you can specify off-diagonal weights, as follows

```MPCobj.Weights.OutputVariables = {Q}; MPCobj.Weights.ManipulatedVariables = {Ru}; MPCobj.Weights.ManipulatedVariablesRate = {Rdu}; ```

where `Q` = Q. `Ru` = Ru, and `Rdu` = RΔu are positive semidefinite matrices.

 Note   You cannot specify non-diagonal weights that vary at each prediction horizon step. The same `Q`, `Ru`, and `Rdu` weights apply at each step.

### Model

The property `Model` specifies plant, input disturbance, and output noise models, and nominal conditions, according to the model setup described in Controller State Estimation. It is a 1-D structure containing the following fields.

Models Used by MPC

Field Name

Content

Default

`Plant`

LTI model or identified linear model of the plant

No default

`Disturbance`

LTI model describing expected unmeasured input disturbances

[ ] (By default, input disturbances are expected to be integrated white noise. To model the signal, an integrator with dimensionless unity gain is added for each unmeasured input disturbance, unless the addition causes the controller to lose state observability. In that case, the disturbance is expected to be white noise, and so, a dimensionless unity gain is added to that channel instead.)

`Noise`

LTI model describing expected noise for output measurements

[ ] (By default, measurement noise is expected to be white noise with unit variance. To model the signal, a dimensionless unity gain is added for each measured channel.)

`Nominal`

Structure containing the state, input, and output values where `Model.Plant` is linearized

The default values of the fields are shown in the following table:

Field

Description

Default

`X`

Plant state at operating point

`[]`

`U`

Plant input at operating point, including manipulated variables and measured and unmeasured disturbances

`[]`

`Y`

Plant output at operating point

`[]`

`DX`

For continuous-time models, `DX` is the state derivative at operating point: `DX`=f(`X`,`U`). For discrete-time models, `DX`=x(k+1)-x(k)=f(`X`,`U`)-`X`.

`[]`

 Note   Direct feedthrough from manipulated variables to any output in `Model.Plant` is not allowed. See MPC Modeling.

Specify input and output signal types via the `InputGroup` and `OutputGroup` properties of `Model.Plant`, or, more conveniently, use the `setmpcsignals` command. Valid signal types are listed in the following tables.

Input Groups in Plant Model

Name (Abbreviations)

Value

`ManipulatedVariables` (or `MV` or `Manipulated` or `Input`)

Indices of manipulated variables in `Model.Plant`

`MeasuredDisturbances `(or `MD` or `Measured`)

Indices of measured disturbances in `Model.Plant`

`UnmeasuredDisturbances` (or `UD` or `Unmeasured`)

Indices of unmeasured disturbances in `Model.Plant`

Output Groups in Plant Model

Name (Abbreviations)

Value

`MeasuredOutputs `(or `MO` or `Measured`)

Indices of measured outputs in `Model.Plant`

`UnmeasuredOutputs `(or `UO` or `Unmeasured`)

Indices of unmeasured outputs in `Model.Plant`

By default, all `Model.Plant` inputs are manipulated variables, and all outputs are measured.

The structure `Nominal` contains the values (in engineering units) for states, inputs, outputs, and state derivatives/differences at the operating point where `Model.Plant` applies. This point is typically a linearization point. The fields are reported in the following table (see also MPC Modeling).

Nominal Values at Operating Point

Field

Description

Default

`X`

Plant state at operating point

`[]`

`U`

Plant input at operating point, including manipulated variables and measured and unmeasured disturbances

`[]`

`Y`

Plant output at operating point

`[]`

`DX`

For continuous-time models, `DX` is the state derivative at operating point: `DX`=f(`X`,`U`). For discrete-time models, `DX`=x(k+1)-x(k)=f(`X`,`U`)-`X`.

`[]`

### Ts

Sample time of the MPC controller. By default, if `Model.Plant` is a discrete-time model, `Ts = Model.Plant.ts`. For continuous-time plant models, specify a controller `Ts`. The `Ts` measurement unit is inherited from `Model.Plant.TimeUnit`.

### Optimizer

Parameters for the QP optimization.`Optimizer` is a structure with the following fields:

Optimizer Properties

Field

Description

Default

`MaxIter`

Maximum number of iterations allowed in the QP solver, specified as one of the following:

• `'Default'` — The MPC controller automatically computes the maximum number of QP solver iterations as:

`$\text{MaxIter}=4\left(p\cdot {n}_{cy}+c\left({n}_{cu}+{n}_{cr}+{n}_{u}\right)+{n}_{sv}\right)$`

where

• p is the prediction horizon.

• c is the control horizon.

• ncy is the number of OV constraints.

• ncu is the number of MV constraints.

• ncr is the number of MV rate constraints.

• nu is the number of MVs.

• nsv is the number of slack variables.

• Positive integer — The QP solver stops after `MaxIter` iterations.

`'Default'`

`MinOutputECR`

Minimum value allowed for `OutputMinECR` and `OutputMaxECR`, specified as a nonnegative scalar. A value of 0 indicates that hard output constraints are allowed. If either of the `OutputVariables.MinECR` or `OutputVariables.MaxECR` properties of an MPC controller are less than `MinOutputECR`, a warning is displayed and the value is raised to `MinOutputECR` during computation.

`0`

`CustomSolver`

Flag indicating whether to use a custom QP solver, specified as a logical value. If `CustomSolver` is `true`, the user must provide an `mpcCustomSolver` function on the MATLAB® path. For information on how to define the `mpcCustomSolver` function, see Custom QP Solver.

`false`

 Note:   The default `MaxIter` value can be very large for some controller configurations, such as those with large prediction and control horizons. When simulating such controllers, if the QP solver cannot find a feasible solution, the simulation can appear to stop responding, since the solver continues searching for `MaxIter` iterations.

### PredictionHorizon

`PredictionHorizon` is the integer number of prediction horizon steps. The control interval, `Ts`, determines the duration of each step. The default value is 10 + maximum intervals of delay (if any).

### ControlHorizon

`ControlHorizon` is either a number of free control moves, or a vector of blocking moves (see Optimization Variables). The default value is 2.

### History

`History` stores the time the MPC controller was created (read only).

### Notes

`Notes` stores text or comments as a cell array of strings.

### UserData

Any additional data stored within the MPC controller object.

## Examples

collapse all

### Create MPC Controller with Specified Prediction and Control Horizons

Create a plant model with the transfer function .

```Plant = tf([1 1],[1 2 0]); ```

The plant is SISO, so its input must be a manipulated variable and its output must be measured. In general, it is good practice to designate all plant signal types using either the `setmpcsignals` command, or the LTI `InputGroup` and `OutputGroup` properties.

Specify a sample time for the controller.

```Ts = 0.1; ```

Define bounds on the manipulated variable, , such that .

```MV = struct('Min',-1,'Max',1); ```

`MV` contains only the upper and lower bounds on the manipulated variable. In general, you can specify additional MV properties. When you do not specify other properties, their default values apply.

Specify a 20-interval prediction horizon, and a 3-interval control horizon.

```p = 20; m = 3; ```

Create an MPC controller using the specifed values. The fifth input argument is empty, so default tuning weights apply.

```MPCobj = mpc(Plant,Ts,p,m,[],MV); ```
```-->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. ```