# mpcmoveMultiple

Compute gain-scheduling MPC control action at a single time instant

## Syntax

## Description

computes the optimal manipulated variable moves at the current time using a model predictive
controller selected by index from an array of MPC controllers. This results depends upon the
properties contained in the MPC controller and the controller states. The result also depends on
the measured plant outputs, the output references (setpoints), and the measured disturbance
inputs. `mv`

= mpcmoveMultiple(`MPCArray`

,`states`

,`index`

,`ym`

,`r`

,`v`

)`mpcmoveMultiple`

updates the controller state when default state
estimation is used. Call `mpcmoveMultiple`

repeatedly to simulate closed-loop
model predictive control.

`[___] = mpcmoveMultiple(___,`

alters selected controller settings using options you specify with `options`

)`mpcmoveopt`

. These changes apply for the current time instant only, allowing a
command-line simulation using `mpcmoveMultiple`

to mimic the Multiple
MPC Controllers block in Simulink^{®} in a computationally efficient manner.

## Input Arguments

`MPCArray`

— MPC controllers

cell array of MPC controller objects

MPC controllers to simulate, specified as a cell array of traditional (implicit) MPC
controller objects. Use the `mpc`

command to create the MPC controllers.

All the controllers in `MPCArray`

must use either default state
estimation or custom state estimation. Mismatch is not permitted.

`states`

— Current MPC controller states

cell array of `mpcstate`

objects

Current controller states for each MPC controller in `MPCArray`

,
specified as a cell array of `mpcstate`

objects.

Before you begin a simulation with `mpcmoveMultiple`

, initialize each
controller state using `x = mpcstate(mpcobj)`

. Then, modify the default
properties of each state as appropriate.

If you are using default state estimation, `mpcmoveMultiple`

expects
`x`

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

(where `x`

is
one entry in `states`

, the current state of one MPC controller in
`MPCArray`

). The `mpcmoveMultiple`

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, `mpcmoveMultiple`

expects
`x`

to represent `x[n|n]`

. Therefore, prior to each
`mpcmoveMultiple`

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.

`index`

— Index of selected controller

positive integer

Index of selected controller in the cell array `MPCArray`

, specified
as a positive integer.

`ym`

— Current measured outputs

row vector

Current measured outputs, specified as a row vector of length
*N _{ym}*, where

*N*is the number of measured outputs. If you are using custom state estimation,

_{ym}`ym`

is ignored. If you set
`ym`

= `[]`

, then `mpcmoveMultiple`

uses the appropriate nominal value.`r`

— Plant output reference values

array

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

*p*is the prediction horizon of the selected controller and

*N*is the number of outputs. Row

_{y}`r(i,:)`

defines the reference values at step *i*of the prediction horizon.

`r`

must contain at least one row. If `r`

contains
fewer than *p* rows, `mpcmoveMultiple`

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.

If you set `r`

= `[]`

, then
`mpcmoveMultiple`

uses the appropriate nominal value.

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

array

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

*p*is the prediction horizon of the selected controller and

*N*is the number of measured disturbances. Row

_{md}`v(i,:)`

defines the expected measured disturbance values at step
*i*of the prediction horizon.

Modeling of measured disturbances provides feedforward control action. If your plant
model does not include measured disturbances, use `v`

=
`[]`

.

`v`

must contain at least one row. If `v`

contains
fewer than *p* rows, `mpcmoveMultiple`

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

If you set `v`

= `[]`

, then
`mpcmoveMultiple`

uses the appropriate nominal value.

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`

— Override values for selected controller properties

`mpcmoveopt`

object

Override values for selected properties of the selected MPC controller, specified as an
options object you create with `mpcmoveopt`

. These options apply to the current
`mpcmoveMultiple`

time instant only. Using `options`

yields the same result as redefining or modifying the selected controller before each call to
`mpcmoveMultiple`

, but involves considerably less overhead. Using
`options`

is equivalent to using a Multiple MPC Controllers
Simulink block in combination with optional input signals that modify controller
settings, such as MV and OV constraints.

## Output Arguments

`mv`

— Optimal manipulated variable moves

column vector

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

*N*is the number of manipulated variables.

_{mv}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, `xc.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 details

structure

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

`Uopt`

— Optimal manipulated variable sequence

(*p*+1)-by-*N*_{mv}
array

_{mv}

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

*p*is the prediction horizon and

*N*is the number of manipulated variables.

_{mv}`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

(*p*+1)-by-*N*_{y}
array

_{y}

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

*p*is the prediction horizon and

*N*is the number of outputs.

_{y}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

(*p*+1)-by-*N*_{x}
array

_{x}

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

*p*is the prediction horizon and

*N*is the number of states in the plant and unmeasured disturbance models (states from noise models are not included).

_{x}`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 intervals

column vector of length *p*+1

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 the `Uopt`

,
`Xopt`

, or `Yopt`

sequences.

`Slack`

— Slack variable

nonnegative 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 iterations

positive 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 cost

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

.

## Tips

Use the Multiple MPC Controllers Simulink block for simulations and code generation.

## Version History

**Introduced in R2014b**

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