Compute optimal control action

`mv = mpcmove(MPCobj,x,ym,r,v)`

[mv,info] = mpcmove(MPCobj,x,ym,r,v)

[___] = mpcmove(___,options)

computes the optimal manipulated variable moves, `mv`

= mpcmove(`MPCobj`

,`x`

,`ym`

,`r`

,`v`

)*u*(*k*), at
the current time. *u*(*k*) is calculated given the current
estimated extended state, *x*(*k*), the measured plant outputs,
*y _{m}*(

`mpcmove`

repeatedly to simulate closed-loop model predictive control.`[`

returns additional information regarding the model predictive controller in the second output
argument `mv`

,`info`

] = mpcmove(`MPCobj`

,`x`

,`ym`

,`r`

,`v`

)`info`

.

`[___] = mpcmove(___,`

overrides default constraints and weights settings in `options`

)`MPCobj`

with the values
specified by `Options`

, an `mpcmoveopt`

object. Use `Options`

to provide run-time adjustment
of constraints and weights during the closed-loop simulation.

`MPCobj`

— Model predictive controllerMPC controller object

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

.

`x`

— Current controller state`mpcstate`

objectCurrent controller state, specified as an `mpcstate`

object.

Before you begin a simulation with `mpcmove`

, initialize the
controller state using `x = mpcstate(MPCobj)`

. Then, modify the default
properties of `x`

as appropriate. `mpcmove`

modifies the value of `x`

to reflect the current state of the
controller.

If you are using default state estimation, `mpcmove`

expects
`x`

to represent `x[n|n-1]`

. The
`mpcmove`

command updates the state values in the previous control
interval with that information. Therefore, you should not programmatically update
`x`

at all. The default state estimator employs a steady-state Kalman
filter.

If you are using custom state estimation, `mpcmove`

expects
`x`

to represent `x[n|n]`

. Therefore, prior to each
`mpcmove`

command, you must set `x.Plant`

,
`x.Disturbance`

, and `x.Noise`

to the best estimates of
these states (using the latest measurements) at the current control interval.

`ym`

— Current measured output valuescolumn vector of length

Current measured output values at time *k*, specified as a column vector
of length *N _{ym}*, where

If you are using custom state estimation, set `ym = []`

.

`r`

— Plant output reference valuesPlant output reference values, specified as a
*p*-by-*N _{y}* array, where

`MPCobj`

and
`r(i,:)`

defines the reference values at step `r`

must contain at least one row. If `r`

contains
fewer than *p* rows, `mpcmove`

duplicates the last row to
fill the *p*-by-*N _{y}* array. If you
supply exactly one row, therefore, a constant reference applies for the entire prediction
horizon.

To implement reference previewing, which can improve tracking when a reference varies in
a predictable manner, `r`

must contain the anticipated variations, ideally
for *p* steps.

`v`

— Current and anticipated measured disturbances(

Current and anticipated measured disturbances, specified as a
(*p*+1)-by-*N _{md}* array, where

`MPCobj`

and
`v`

specifies the current measured disturbance values. Row
`v(i+1,:)`

defines the anticipated disturbance values at step
Modeling of measured disturbances provides feedforward control action. If your plant
model does not include measured disturbances, use `v`

=
`[]`

.

If your model includes measured disturbances, `v`

must contain at
least one row. If `v`

contains fewer than *p*+1 rows,
`mpcmove`

duplicates the last row to fill the
(*p*+1)-by-*N _{md}* array. If you
supply exactly one row, a constant measured disturbance applies for the entire prediction
horizon.

To implement disturbance previewing, which can improve tracking when a disturbance varies
in a predictable manner, `v`

must contain the anticipated variations,
ideally for *p* steps.

`options`

— Run-time options`mpcmoveopt`

objectRun-time options, specified as an `mpcmoveopt`

object. Use `options`

to override selected
properties of `MPCobj`

during simulation. These options apply to the
current `mpcmove`

time instant only. Using
`options`

yields the same result as redefining or modifying
`MPCobj`

before each call to `mpcmove`

, but
involves considerably less overhead. Using `options`

is equivalent to
using an MPC Controller
Simulink^{®} block in combination with optional input signals that modify controller
settings, such as MV and OV constraints.

`mv`

— Optimal manipulated variable movescolumn vector

Optimal manipulated variable moves, returned as a column vector of length
*N _{mv}*, where

If the controller detects an infeasible optimization problem or encounters numerical
difficulties in solving an ill-conditioned optimization problem, `mv`

remains at its most recent successful solution, `x.LastMove`

.

Otherwise, if the optimization problem is feasible and the solver reaches the
specified maximum number of iterations without finding an optimal solution,
`mv`

:

Remains at its most recent successful solution if the

`Optimizer.UseSuboptimalSolution`

property of the controller is`false`

.Is the suboptimal solution reached after the final iteration if the

`Optimizer.UseSuboptimalSolution`

property of the controller is`true`

. For more information, see Suboptimal QP Solution.

`info`

— Solution detailsstructure

Solution details, returned as a structure with the following fields.

`Uopt`

— Optimal manipulated variable sequence(

Predicted optimal manipulated variable adjustments (moves), returned as a
(*p*+1)-by-*N _{mv}*
array, where

`Uopt(i,:)`

contains the calculated optimal values at
time `k+i-1`

, for `i = 1,...,p`

, where
`k`

is the current time. The first row of
`Info.Uopt`

contains the same manipulated variable
values as output argument `mv`

. Since the controller does
not calculate optimal control moves at time `k+p`

,
`Uopt(p+1,:)`

is equal to
`Uopt(p,:)`

.

`Yopt`

— Optimal output variable sequence(

Optimal output variable sequence, returned as a
(*p*+1)-by-*N _{y}*
array, where

The first row of `Info.Yopt`

contains the calculated
outputs at time `k`

based on the estimated states and
measured disturbances; it is not the measured output at time
`k`

. `Yopt(i,:)`

contains the
predicted output values at time `k+i-1`

, for ```
i =
1,...,p+1
```

.

`Yopt(i,:)`

contains the calculated output values at time
`k+i-1`

, for `i = 2,...,p+1`

, where
`k`

is the current time. `Yopt(1,:)`

is computed based on the estimated states and measured disturbances.

`Xopt`

— Optimal prediction model state sequence(

Optimal prediction model state sequence, returned as a
(*p*+1)-by-*N _{x}*
array, where

`Xopt(i,:)`

contains the calculated state values at time
`k+i-1`

, for `i = 2,...,p+1`

, where
`k`

is the current time. `Xopt(1,:)`

is the same as the current states state values.

`Topt`

— Time intervalscolumn vector of length

Time intervals, returned as a column vector of length
*p*+1. `Topt(1)`

= 0, representing the
current time. Subsequent time steps `Topt(i)`

are given by
`Ts*(i-1)`

, where `Ts = MPCobj.Ts`

is
the controller sample time.

Use `Topt`

when plotting `Uopt`

,
`Xopt`

, or `Yopt`

sequences.

`Slack`

— Slack variablenonnegative scalar

Slack variable, ε, used in constraint softening, returned as
`0`

or a positive scalar value.

ε = 0 — All constraints were satisfied for the entire prediction horizon.

ε > 0 — At least one soft constraint is violated. When more than one constraint is violated, ε represents the worst-case soft constraint violation (scaled by your ECR values for each constraint).

See Optimization Problem for more information.

`Iterations`

— Number of solver iterationspositive integer |

`0`

| `-1`

| `-2`

Number of solver iterations, returned as one of the following:

Positive integer — Number of iterations needed to solve the optimization problem that determines the optimal sequences.

`0`

— Optimization problem could not be solved in the specified maximum number of iterations.`–1`

— Optimization problem was infeasible. An optimization problem is infeasible if no solution can satisfy all the hard constraints.`–2`

— Numerical error occurred when solving the optimization problem.

`QPCode`

— Optimization solution status`'feasible'`

| `'infeasible'`

| `'unrealiable'`

Optimization solution status, returned as one of the following:

`'feasible'`

— Optimal solution was obtained (`Iterations`

> 0)`'infeasible'`

— Solver detected a problem with no feasible solution (`Iterations`

= –1) or a numerical error occurred (`Iterations`

= –2)`'unreliable'`

— Solver failed to converge (`Iterations`

= 0). In this case, if`MPCobj.Optimizer.UseSuboptimalSolution`

is`false`

,`u`

freezes at the most recent successful solution. Otherwise, it uses the suboptimal solution found during the last solver iteration.

`Cost`

— Objective function costnonnegative scalar

Objective function cost, returned as a nonnegative scalar value. The cost quantifies the degree to which the controller has achieved its objectives. For more information, see Optimization Problem.

The cost value is only meaningful when ```
QPCode =
'feasible'
```

, or when `QPCode = 'feasible'`

and
`MPCobj.Optimizer.UseSuboptimalSolution`

is
`true`

.

Perform closed-loop simulation of a plant with one MV and one measured OV.

Define a plant model and create a model predictive controller with MV constraints.

ts = 2; Plant = ss(0.8,0.5,0.25,0,ts); MPCobj = mpc(Plant);

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

MPCobj.MV(1).Min = -2; MPCobj.MV(1).Max = 2;

Initialize an `mpcstate`

object for simulation. Use the default state properties.

x = mpcstate(MPCobj);

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

Set the reference signal. There is no measured disturbance.

r = 1;

Simulate the closed-loop response by calling `mpcmove`

iteratively.

t = [0:ts:40]; N = length(t); y = zeros(N,1); u = zeros(N,1); for i = 1:N % simulated plant and predictive model are identical y(i) = 0.25*x.Plant; u(i) = mpcmove(MPCobj,x,y(i),r); end

`y`

and `u`

store the OV and MV values.

Analyze the result.

[ts,us] = stairs(t,u); plot(ts,us,'r-',t,y,'b--') legend('MV','OV')

Modify the MV upper bound as the simulation proceeds using an `mpcmoveopt`

object.

MPCopt = mpcmoveopt; MPCopt.MVMin = -2; MPCopt.MVMax = 2;

Simulate the closed-loop response and introduce the real-time upper limit change at eight seconds (the fifth iteration step).

x = mpcstate(MPCobj); y = zeros(N,1); u = zeros(N,1); for i = 1:N % simulated plant and predictive model are identical y(i) = 0.25*x.Plant; if i == 5 MPCopt.MVMax = 1; end u(i) = mpcmove(MPCobj,x,y(i),r,[],MPCopt); end

Analyze the result.

[ts,us] = stairs(t,u); plot(ts,us,'r-',t,y,'b--') legend('MV','OV')

Define a plant model.

ts = 2; Plant = ss(0.8,0.5,0.25,0,ts);

Create a model predictive controller with constraints on both the manipulated variable and the rate of change of the manipulated variable. The prediction horizon is `10`

intervals, and the control horizon is blocked.

MPCobj = mpc(Plant,ts,10,[2 3 5]);

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

MPCobj.MV(1).Min = -2; MPCobj.MV(1).Max = 2; MPCobj.MV(1).RateMin = -1; MPCobj.MV(1).RateMax = 1;

Initialize an `mpcstate`

object for simulation from a particular state.

x = mpcstate(MPCobj);

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

x.Plant = 2.8; x.LastMove = 0.85;

Compute the optimal control at current time.

y = 0.25*x.Plant; r = 1; [u,Info] = mpcmove(MPCobj,x,y,r);

Analyze the predicted optimal sequences.

[ts,us] = stairs(Info.Topt,Info.Uopt); plot(ts,us,'r-',Info.Topt,Info.Yopt,'b--') legend('MV','OV')

`plot`

ignores `Info.Uopt(end)`

as it is `NaN`

.

Examine the optimal cost.

Info.Cost

ans = 0.0793

`mpcmove`

updates`x`

.If

`ym`

,`r`

or`v`

is specified as`[]`

,`mpcmove`

uses the appropriate`MPCobj.Model.Nominal`

value instead.To view the predicted optimal behavior for the entire prediction horizon, plot the appropriate sequences provided in

`Info`

.To determine the optimization status, check

`Info.Iterations`

and`Info.QPCode`

.

Use

`sim`

for plant mismatch and noise simulation when not using run-time constraints or weight changes.Use the

**MPC Designer**app to interactively design and simulate model predictive controllers.Use the MPC Controller block in Simulink and for code generation.

Use

`mpcmoveCodeGeneration`

for code generation.

`getEstimator`

| `mpc`

| `mpcmoveopt`

| `mpcstate`

| `review`

| `setEstimator`

| `sim`

A modified version of this example exists on your system. Do you want to open this version instead?

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.

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

Select web siteYou can also select a web site from the following list:

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

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

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