# Multistage Nonlinear MPC Controller

Simulate multistage nonlinear model predictive controllers

**Library:**Model Predictive Control Toolbox

## Description

The Multistage Nonlinear MPC Controller block simulates a multistage nonlinear model predictive controller. At each control interval, the block computes optimal control moves by solving a nonlinear programming problem in which different cost functions and constraints are defined for different prediction steps (stages). For more information on nonlinear MPC, see Nonlinear MPC.

To use this block, you must first create an `nlmpcMultistage`

object
in the MATLAB^{®} workspace.

## Limitations

None of the Multistage Nonlinear MPC Controller block parameters are tunable.

## Ports

### Input

**Required Inputs**

`x`

— input

vector

Current prediction model states, specified as a vector signal of length
*N _{x}*, where

*N*is the number of prediction model states. Since the nonlinear MPC controller does not perform state estimation, you must either measure or estimate the current prediction model states at each control interval.

_{x}`last_mv`

— Control signals used in the plant at the previous control interval

vector

Control signals used in plant at previous control interval, specified as a vector
signal of length *N _{mv}*, where

*N*is the number of manipulated variables.

_{mv}**Note**

Connect **last_mv** to the MV signals actually applied to the
plant in the previous control interval. Typically, these MV signals are the values
generated by the controller, though sometimes they can come from a different source.
For example, if your controller is offline and running in tracking mode, (that is,
the controller output is not driving the plant), then feeding the actual plant input
to **last_mv** can help achieve bumpless transfer when the
controller is switched back online.

**Additional Inputs**

`md`

— input

row vector | matrix

If your controller prediction model has measured disturbances you must enable this port and connect to it a row vector or matrix signal.

To use the same measured disturbance values across the prediction horizon, connect **md** to a row vector signal with *N _{md}* elements, where

*N*is the number of manipulated variables. Each element specifies the value for a measured disturbance.

_{md}To vary the disturbances over the prediction horizon (previewing) from time
*k* to time *k*+*p*, connect
**md** to a matrix signal with
*N _{md}* columns and up to

*p*+1 rows. Here,

*k*is the current time and

*p*is the prediction horizon. Each row contains the disturbances for one prediction horizon step. If you specify fewer than

*p*+1 rows, the final disturbances are used for the remaining steps of the prediction horizon.

#### Dependencies

To enable this port, select the **Measured disturbances**
parameter.

`state.param`

— Optional parameters

vector

If your controller uses optional parameters in its prediction model, enable this
input port, and connect a vector signal with
*N _{pm}* elements, where

*N*is the number of state parameters (equal to the

_{pm}`Model.ParameterLength`

property of the
`nlmpcMultistage`

controller object). The controller passes these
parameters to its model state transition and state Jacobian functions.If your controller does not use optional parameters, you must disable the
**state.param** port.

#### Dependencies

To enable this port, select the **StateFcn parameters**
parameter.

`stage.param`

— Optional parameters

vector

If your controller uses optional parameters in any stage cost or constraint
function, enable this input port, and connect a vector signal with
*N _{pv}* elements, where

*N*is the total number of parameters for all stage functions, and is equal to

_{pv}`sum(Stages.ParameterLength)`

. The parameters for all stages are
stacked in the parameter vector as
follows.[parameter vector for stage 1; parameter vector for stage 2; ... parameter vector for stage p+1; ]

At each stage, the controller passes the relevant parameter vector to the stage cost and constraint functions active at that stage.

If your controller does not use optional parameters, you must disable the
**stage.param** port. For more information, see `nlmpcMultistage`

and `nlmpcmove`

.

#### Dependencies

To enable this port, select the **Stacked stage parameters**
parameter.

**Online Constraints**

`mv.min`

— Minimum manipulated variable constraints

vector | matrix

To specify run-time minimum manipulated variable constraints, enable this input
port. If this port is disabled, the block uses the lower bounds specified in the
`ManipulatedVariables.Min`

property of its controller
object.

To use the same bounds over the prediction horizon, connect
**mv.min** to a row vector signal with
*N _{mv}* elements, where

*N*is the number of outputs. Each element specifies the lower bound for a manipulated variable.

_{mv}To vary the bounds over the prediction horizon from time *k* to
time *k*+*p*–1, connect **mv.min**
to a matrix signal with *N _{y}* columns and up to

*p*rows. Here,

*k*is the current time and

*p*is the prediction horizon. Each row contains the bounds for one prediction horizon step. If you specify fewer than

*p*rows, the bounds in the final row apply for the remainder of the prediction horizon.

#### Dependencies

To enable this port, select the **Lower MV limits**
parameter.

`mv.max`

— Maximum manipulated variable constraints

vector | matrix

To specify run-time maximum manipulated variable constraints, enable this input
port. If this port is disabled, the block uses the upper bounds specified in the
`ManipulatedVariables.Max`

property of its controller
object.

To use the same bounds over the prediction horizon, connect
**mv.max** to a row vector signal with
*N _{mv}* elements, where

*N*is the number of outputs. Each element specifies the upper bound for a manipulated variable.

_{mv}To vary the bounds over the prediction horizon from time *k* to
time *k*+*p*–1, connect **mv.max**
to a matrix signal with *N _{y}* columns and up to

*p*rows. Here,

*k*is the current time and

*p*is the prediction horizon. Each row contains the bounds for one prediction horizon step. If you specify fewer than

*p*rows, the bounds in the final row apply for the remainder of the prediction horizon.

#### Dependencies

To enable this port, select the **Upper MV limits**
parameter.

`dmv.min`

— Minimum manipulated variable rate constraints

vector | matrix

To specify run-time minimum manipulated variable rate constraints, enable this
input port. If this port is disabled, the block uses the lower bounds specified in the
`ManipulatedVariable.RateMin`

property of its controller object.
**dmv.min** bounds must be nonpositive.

To use the same bounds over the prediction horizon, connect
**dmv.min** to a row vector signal with
*N _{mv}* elements, where

*N*is the number of outputs. Each element specifies the lower bound for a manipulated variable rate of change.

_{mv}To vary the bounds over the prediction horizon from time *k* to
time *k*+*p*–1, connect **dmv.min**
to a matrix signal with *N _{y}* columns and up to

*p*rows. Here,

*k*is the current time and

*p*is the prediction horizon. Each row contains the bounds for one prediction horizon step. If you specify fewer than

*p*rows, the bounds in the final row apply for the remainder of the prediction horizon.

#### Dependencies

To enable this port, select the **Lower MVRate limits**
parameter.

`dmv.max`

— Maximum manipulated variable rate constraints

vector | matrix

To specify run-time maximum manipulated variable rate constraints, enable this
input port. If this port is disabled, the block uses the upper bounds specified in the
`ManipulatedVariables.RateMax`

property of its controller object.
**dmv.max** bounds must be nonnegative.

To use the same bounds over the prediction horizon, connect
**dmv.max** to a row vector signal with
*N _{mv}* elements, where

*N*is the number of outputs. Each element specifies the upper bound for a manipulated variable rate of change.

_{mv}To vary the bounds over the prediction horizon from time *k* to
time *k*+*p*–1, connect **dmv.max**
to a matrix signal with *N _{y}* columns and up to

*p*rows. Here,

*k*is the current time and

*p*is the prediction horizon. Each row contains the bounds for one prediction horizon step. If you specify fewer than

*p*rows, the bounds in the final row apply for the remainder of the prediction horizon.

#### Dependencies

To enable this port, select the **Upper MVRate limits**
parameter.

`x.min`

— Minimum state constraints

vector | matrix

To specify run-time minimum state constraints, enable this input port. If this
port is disabled, the block uses the lower bounds specified in the
`States.Min`

property of its controller object.

To use the same bounds over the prediction horizon, connect
**x.min** to a row vector signal with
*N _{x}* elements, where

*N*is the number of outputs. Each element specifies the lower bound for a state.

_{x}To vary the bounds over the prediction horizon from time *k*+1 to
time *k*+*p*, connect **x.min** to
a matrix signal with *N _{y}* columns and up to

*p*rows. Here,

*k*is the current time and

*p*is the prediction horizon. Each row contains the bounds for one prediction horizon step. If you specify fewer than

*p*rows, the bounds in the final row apply for the remainder of the prediction horizon.

#### Dependencies

To enable this port, select the **Lower state limits**
parameter.

`x.max`

— Maximum state constraints

vector | matrix

To specify run-time maximum state constraints, enable this input port. If this
port is disabled, the block uses the upper bounds specified in the
`States.Max`

property of its controller object.

To use the same bounds over the prediction horizon, connect
**x.max** to a row vector signal with
*N _{x}* elements, where

*N*is the number of outputs. Each element specifies the upper bound for a state.

_{x}To vary the bounds over the prediction horizon from time *k*+1 to
time *k*+*p*, connect **x.max** to
a matrix signal with *N _{y}* columns and up to

*p*rows. Here,

*k*is the current time and

*p*is the prediction horizon. Each row contains the bounds for one prediction horizon step. If you specify fewer than

*p*rows, the bounds in the final row apply for the remainder of the prediction horizon.

#### Dependencies

To enable this port, select the **Upper state limits**
parameter.

**Others**

`x.terminal`

— Terminal state

vector

Terminal state, specified as a vector signal of length
*N _{x}*. To specify desired terminal state
constraints, enable this input port. To specify desired terminal states at run-time
via this input port, you must specify finite values in the

`TerminalState`

field of the `Model`

property
of the `nlmpcMultistage`

object that is passed as a parameter to the
block. Specify `inf`

for the states that you do not need to constrain
to a terminal value. At run time, the block ignores any values in the input signal
that correspond to `inf`

values in the object. If you do not specify
any terminal value condition in the `nlmpcMultistage`

object, the
signal at this input port is ignored at runtime.If this port is not enabled the terminal state constraint (if present) does not change at run time.

#### Dependencies

To enable this port, select the **Terminal state**
parameter.

`z0`

— Initial guesses for the decision variables vector

vector

To specify initial guesses for the decision variable vector, enable this input port. If this port is disabled, the block uses the decision variable sequences calculated in the previous control interval as initial guesses. Good initial guesses are important since they help the solver to converge to a solution faster.

**z0** is a column vector of length equal to the sum of the
lengths of all the decision variable vectors for each stage. The initial guesses must
be stacked as
follows.

[state vector guess for stage 1; manipulated variable vector guess for stage 1; manipulated variable vector rate guess for stage 1; % if used slack variable vector guess for stage 1; % if used state vector guess for stage 2; manipulated variable vector guess for stage 2; manipulated variable vector rate guess for stage 2; % if used slack variable vector guess for stage 2; % if used ... state vector guess for stage p; manipulated variable vector guess for stage p; manipulated variable vector rate guess for stage p; % if used slack variable vector guess for stage p; % if used state vector guess for stage p+1; slack variable vector guess for stage p+1; % if used ]

`nlmpcMultistage`

and `nlmpcmove`

.
#### Dependencies

To enable this port, select the **Initial guess**
parameter.

### Output

**Required Output**

`mv`

— Optimal manipulated variable control action

column vector

Optimal manipulated variable control action, output as a column vector signal of
length *N _{mv}*, where

*N*is the number of manipulated variables.

_{mv}If the solver converges to a local optimum solution
(**nlp.status** is positive), then **mv** contains
the optimal solution.

If the solver reaches the maximum number of iterations without finding an optimal
solution (**nlp.status** is zero) and the
`Optimization.UseSuboptimalSolution`

property of the controller is
`true`

, then **mv** contains the suboptimal
solution, otherwise, **mv** is the same as
**last_mv**.

If the solver fails (**nlp.status** is negative), then
**mv** is the same as **last_mv**.

**Additional Outputs**

`cost`

— Objective function cost

nonnegative scalar

Objective function cost, output as a nonnegative scalar signal. The cost quantifies the degree to which the controller has achieved its objectives.

The cost value is meaningful only when the **nlp.status** output
is nonnegative.

#### Dependencies

To enable this port, select the **Optimal cost**
parameter.

`slack`

— Stacked slack variables vector

nonnegative vector

Stacked slack variables vector, used in constraint softening. If all elements are zero, then all soft constraints are satisfied over the entire prediction horizon. If any element is greater than zero, then at least one soft constraint is violated.

The slack variable vector for all stages are stacked as follows.

[slack variable vector for stage 1; % if used slack variable vector for stage 2; % if used ... slack variable vector for stage p+1; % if used ]

`nlp.status`

— Optimization status

scalar

Optimization status, output as one of the following:

Positive Integer — Solver converged to an optimal solution

`0`

— Maximum number of iterations reached without converging to an optimal solutionNegative integer — Solver failed

#### Dependencies

To enable this port, select the **Optimization status**
parameter.

**Optimal Sequences**

`mv.seq`

— Optimal manipulated variable sequence

matrix

Optimal manipulated variable sequence, returned as a matrix signal with *p*+1 rows and *N _{mv}* columns, where

*p*is the prediction horizon and

*N*is the number of manipulated variables.

_{mv}The first *p* rows of **mv.seq** contain the
calculated optimal manipulated variable values from current time *k* to
time *k*+*p*-1. The first row of
**mv.seq** contains the current manipulated variable values (output
**mv**). Since the controller does not calculate optimal control
moves at time *k*+*p*, the final two rows of **mv.seq** are
identical.

#### Dependencies

To enable this port, select the **Optimal control sequence** parameter.

`x.seq`

— Optimal prediction model state sequence

matrix

Optimal prediction model state sequence, returned as a matrix signal with *p*+1 rows and *N _{x}* columns, where

*p*is the prediction horizon and

*N*is the number of states.

_{x}The first row of **x.seq** contains the current estimated state
values, either from the built-in state estimator or from the custom state estimation
block input **x[k|k]**. The next *p* rows of
**x.seq** contain the calculated optimal state values from time
*k*+1 to time *k*+*p*.

#### Dependencies

To enable this port, select the **Optimal state sequence** parameter.

## Parameters

`Multistage Nonlinear MPC Controller`

— Controller object

`nlmpcMultistage`

object name

You must provide an `nlmpcMultistage`

object that defines a nonlinear MPC controller. To do so, enter the name of an
`nlmpc`

object in the MATLAB workspace.

#### Programmatic Use

Block Parameter:
`nlmpcobj` |

Type: string, character vector |

Default:
`""` |

`Use prediction model sample time`

— Flag for using the prediction model sample time

on (default) | off

Select this parameter to run the controller using the same sample time as its
prediction model. To use a different controller sample time, clear this parameter, and
specify the sample time using the **Make block run at a different sample
time** parameter.

To limit the number of decision variables and improve computational efficiency, you can run the controller with a sample time that is different from the prediction horizon. For example, consider the case of a nonlinear MPC controller running at 10 Hz. If the plant and controller sample times match, predicting plant behavior for ten seconds requires a prediction horizon of length 100, which produces a large number of decision variables. To reduce the number of decision variables, you can use a plant sample time of 1 second and a prediction horizon of length 10.

#### Programmatic Use

Block Parameter:
`UseObjectTs` |

Type: string, character vector |

Values:
`"off"` , `"on"` |

Default:
`"on"` |

`Make block run at a different sample time`

— Controller sample time

positive finite scalar | `-1`

Specify this parameter to run the controller using a different sample time from its
prediction model. Setting this parameter to `-1`

allows the block to
inherit the sample time from its parent subsystem.

**Note**

The first element of the MV rate vector (which is the difference between the current and the last value of the manipulated variable) is normally weighted and constrained assuming that the last value of the MV occurred in the past at the sample time specified in the MPC object. When the block is executed with a different sample rate, this assumption no longer holds, therefore, in this case, you must make sure that the weights and constraints defined in the controller handle the first element of the MV rate vector correctly.

#### Dependencies

To enable this parameter, clear the **Use prediction model sample
time** parameter.

#### Programmatic Use

Block Parameter:
`TsControl` |

Type: string, character vector |

Default:
`""` |

`Use MEX to speed up simulation`

— Flag for simulating controller use MEX function

off (default) | on

Select this parameter to simulate the controller using a MEX function generated
using `buildMEX`

. Doing so reduces the simulation time of the
controller. To specify the name of the MEX function, use the **Specify MEX
function name** parameter.

#### Programmatic Use

Block Parameter:
`UseMEX` |

Type: string, character vector |

Values:
`"off"` , `"on"` |

Default:
`"off"` |

`Specify MEX function name`

— Controller MEX function name

string

Use this parameter to specify the name of the MEX function to use during simulation.
To create the MEX function, use the `buildMEX`

function.

#### Dependencies

To enable this parameter, select the **Use MEX to speed up
simulation** parameter.

#### Programmatic Use

Block Parameter:
`mexname` |

Type: string, character vector |

Default:
`""` |

### General Tab

`Measured disturbances`

— Add measured disturbance input port

off (default) | on

If your controller has measured disturbances, you must select this parameter to
add the **md** output port to the block.

#### Programmatic Use

Block Parameter:
`md_enabled` |

Type: string, character vector |

Values:
`"off"` , `"on"` |

Default:
`"off"` |

`StateFcn parameter`

— Add state function parameters input port

off (default) | on

If your prediction model uses optional parameters, you must select this parameter
to add the **state.param** input port to the block.

#### Programmatic Use

Block Parameter:
`stateparam_enabled` |

Type: string, character vector |

Values:
`"off"` , `"on"` |

Default:
`"off"` |

`Stacked stage parameters`

— Add stage functions parameter input port

off (default) | on

If your cost or constraint functions use parameters at any stage, you must select
this parameter to add the **stage.param** input port to the
block.

#### Programmatic Use

Block Parameter:
`stageparam_enabled` |

Type: string, character vector |

Values:
`"off"` , `"on"` |

Default:
`"off"` |

`Optimal cost`

— Add optimal cost output port

off (default) | on

Select this parameter to add the **cost** output port to the
block.

#### Programmatic Use

Block Parameter:
`cost_enabled` |

Type: string, character vector |

Values:
`"off"` , `"on"` |

Default:
`"off"` |

`Optimal control sequence`

— Add optimal control sequence output port

off (default) | on

Select this parameter to add the **mv.seq** output port to the
block.

#### Programmatic Use

Block Parameter:
`mvseq_enabled` |

Type: string, character vector |

Values:
`"off"` , `"on"` |

Default:
`"off"` |

`Optimal state sequence`

— Add optimal state sequence output port

off (default) | on

Select this parameter to add the **x.seq** output port to the
block.

#### Programmatic Use

Block Parameter:
`stateseq_enabled` |

Type: string, character vector |

Values:
`"off"` , `"on"` |

Default:
`"off"` |

`Slack variable`

— Add slack variable output port

off (default) | on

Select this parameter to add the **slack** output port to the
block.

#### Programmatic Use

Block Parameter:
`slack_enabled` |

Type: string, character vector |

Values:
`"off"` , `"on"` |

Default:
`"off"` |

`Optimization status`

— Add optimization status output port

off (default) | on

Select this parameter to add the **nlp.status** output port to
the block.

#### Programmatic Use

Block Parameter:
`status_enabled` |

Type: string, character vector |

Values:
`"off"` , `"on"` |

Default:
`"off"` |

### Online Features Tab

`Lower MV limits`

— Add minimum MV constraint input port

off (default) | on

Select this parameter to add the **mv.min** input port to the
block.

#### Programmatic Use

Block Parameter:
`mv_min` |

Type: string, character vector |

Values:
`"off"` , `"on"` |

Default:
`"off"` |

`Upper MV limits`

— Add maximum MV constraint input port

off (default) | on

Select this parameter to add the **mv.max** input port to the
block.

#### Programmatic Use

Block Parameter:
`mv_max` |

Type: string, character vector |

Values:
`"off"` , `"on"` |

Default:
`"off"` |

`Lower MVRate limits`

— Add minimum MV rate constraint input port

off (default) | on

Select this parameter to add the **dmv.min** input port to the
block.

#### Programmatic Use

Block Parameter:
`mvrate_min` |

Type: string, character vector |

Values:
`"off"` , `"on"` |

Default:
`"off"` |

`Upper MVRate limits`

— Add maximum MV rate constraint input port

off (default) | on

Select this parameter to add the **dmv.max** input port to the
block.

#### Programmatic Use

Block Parameter:
`mvrate_max` |

Type: string, character vector |

Values:
`"off"` , `"on"` |

Default:
`"off"` |

`Lower state limits`

— Add minimum state constraint input port

off (default) | on

Select this parameter to add the **x.min** input port to the
block.

#### Programmatic Use

Block Parameter:
`state_min` |

Type: string, character vector |

Values:
`"off"` , `"on"` |

Default:
`"off"` |

`Upper state limits`

— Add maximum state constraint input port

off (default) | on

Select this parameter to add the **x.max** input port to the
block.

#### Programmatic Use

Block Parameter:
`state_max` |

Type: string, character vector |

Values:
`"off"` , `"on"` |

Default:
`"off"` |

`Terminal state`

— Terminal State

off (default) | on

Select this parameter to add the **x.terminal** input port to the
block.

#### Programmatic Use

Block Parameter:
`terminal_state` |

Type: string, character vector |

Values:
`"off"` , `"on"` |

Default:
`"off"` |

`Initial guess`

— Add initial guess input port

off (default) | on

Select this parameter to add the **z0** input port to the
block.

**Note**

By default, the Nonlinar MPC Controller block uses the calculated optimal states, manipulated variables, and slack variables from one control interval as initial guesses for the next control interval.

Enable the initial guess port only if you need it for your application.

#### Programmatic Use

Block Parameter:
`nlp_initialize` |

Type: string, character vector |

Values:
`"off"` , `"on"` |

Default:
`"off"` |

## Extended Capabilities

### C/C++ Code Generation

Generate C and C++ code using Simulink® Coder™.

Usage notes and limitations:

The Multistage Nonlinear MPC Controller block supports generating code only for multistage nonlinear MPC controllers that use the default

`fmincon`

solver with the SQP algorithm.Code generation for single-precision or fixed-point computations is not supported.

When used for code generation, nonlinear MPC controllers do not support expressing prediction model functions, stage cost functions or constraint functions as anonymous functions.

The

**Support non-finite numbers**check box in the**Interface**section of the**Code Generation**options, under the model**Configuration Parameters**dialog box, must be checked (default option).When generating code using Embedded Coder

^{®}, the**Support variable-size signals**in the**Interface**section of the**Code Generation**options, under the model**Configuration Parameters**dialog box, must be checked. By default this check box is unchecked and you must check it before generating code.

## Version History

**Introduced in R2021a**

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