Main Content

Simulate nonlinear model predictive controllers

**Library:**Model Predictive Control Toolbox

The Nonlinear MPC Controller block simulates a nonlinear model predictive controller. At each control interval, the block computes optimal control moves by solving a nonlinear programming problem. For more information on nonlinear MPC, see Nonlinear MPC.

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

object in the
MATLAB^{®} workspace.

None of the Nonlinear MPC Controller block parameters are tunable.

`x`

— inputvector

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

`ref`

— Model output reference valuesrow vector | matrix

Plant output reference values, specified as a row vector signal or matrix signal.

To use the same reference values across the prediction horizon, connect **ref** to a row vector signal with *N _{Y}* elements, where

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

`last_mv`

— Control signals used in plant at previous control intervalvector

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

**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 this is not always the case. 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 control signal to
**last_mv** can help achieve bumpless transfer when the
controller is switched back online.

`md`

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

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

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

`params`

— Optional parametersbus

If your controller uses optional parameters in its prediction model, custom cost
function, or custom constraint functions, enable this input port, and connect a
parameter bus signal with *N _{p}* elements, where

`createParameterBus`

. The controller, passes these parameters to its model
functions, cost function, constraint functions, and Jacobian functions.If your controller does not use optional parameters, you must disable
**params**.

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

`mv.target`

— Manipulated variable targetsrow vector | array

To specify manipulated variable targets, enable this input port, and connect a row vector or matrix signal. To make a given manipulated variable track its specified target value, you must also specify a nonzero tuning weight for that manipulated variable.

To use the same manipulated variable targets across the prediction horizon, connect **mv.target** to a row vector signal with *N _{mv}* elements, where

To vary the targets over the prediction horizon (previewing) from time *k* to time *k*+*p*-1, connect **mv.target** to a matrix signal with *N _{mv}* columns and up to

To enable this port, select the **Targets for manipulated variables** parameter.

`y.min`

— Minimum output variable constraintsvector | matrix

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

property of its controller object.

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

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

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

`y.max`

— Maximum output variable constraintsvector | matrix

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

property of its controller object.

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

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

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

`mv.min`

— Minimum manipulated variable constraintsvector | 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

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

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

`mv.max`

— Maximum manipulated variable constraintsvector | 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

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

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

`dmv.min`

— Minimum manipulated variable rate constraintsvector | 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

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

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

`dmv.max`

— Maximum manipulated variable rate constraintsvector | 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

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

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

`x.min`

— Minimum state constraintsvector | 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

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

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

`x.max`

— Maximum state constraintsvector | 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

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

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

`y.wt`

— Output variable tuning weightsrow vector | matrix

To specify run-time output variable tuning weights, enable this input port. If this port is disabled, the block uses the tuning weights specified in the `Weights.OutputVariables`

property of its controller object. These tuning weights penalize deviations from output references.

If the MPC controller object uses constant output tuning weights over the prediction horizon, you can specify only constant output tuning weights at runtime. Similarly, if the MPC controller object uses output tuning weights that vary over the prediction horizon, you can specify only time-varying output tuning weights at runtime

To use constant tuning weights over the prediction horizon, connect **y.wt**
to a row vector signal with *N _{y}* elements, where

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

To enable this port, select the **OV weights** parameter.

`mv.wt`

— Manipulated variable tuning weightsrow vector | matrix

To specify run-time manipulated variable tuning weights, enable this input port.
If this port is disabled, the block uses the tuning weights specified in the
`Weights.ManipulatedVariables`

property of its controller object.
These tuning weights penalize deviations from MV targets.

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

To vary the tuning weights over the prediction horizon from time
*k* to time *k*+*p*-1, connect
**mv.wt** to a matrix signal with
*N _{mv}* columns and up to

To enable this port, select the **MV weights**
parameter.

`dmv.wt`

— Manipulated variable rate tuning weightsrow vector | matrix

To specify run-time manipulated variable rate tuning weights, enable this input
port. If this port is disabled, the block uses the tuning weights specified in the
`Weights.ManipulatedVariablesRate`

property of its controller
object. These tuning weights penalize large changes in control moves.

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

To vary the tuning weights over the prediction horizon from time
*k* to time *k*+*p*-1, connect
**dmv.wt** to a matrix signal with
*N _{mv}* columns and up to

To enable this port, select the **MVRate weights**
parameter.

`ecr.wt`

— Slack variable tuning weightscalar

To specify a run-time slack variable tuning weight, enable this input port and connect a scalar signal. If this port is disabled, the block uses the tuning weight specified in the `Weights.ECR`

property of its controller object.

The slack variable tuning weight has no effect unless your controller object defines soft constraints whose associated ECR values are nonzero. If there are soft constraints, increasing the **ecr.wt** value makes these constraints relatively harder. The controller then places a higher priority on minimizing the magnitude of the predicted worst-case constraint violation.

To enable this port, select the **ECR weight** parameter.

`mv.init`

— Initial guesses for the optimal manipulated variable solutionsvector | matrix

To specify initial guesses for the optimal manipulated variable solutions, enable this input port. If this port is disabled, the block uses the optimal control sequences calculated in the previous control interval as initial guesses.

To use the same initial guesses over the prediction horizon, connect
**mv.init** to a vector signal with
*N _{mv}* elements, where

To vary the initial guesses over the prediction horizon from time
*k* to time *k*+*p*-1, connect
**mv.init** to a matrix signal with
*N _{mv}* columns and up to

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

`x.init`

— Initial guesses for the optimal state variable solutionsvector | matrix

To specify initial guesses for the optimal state solutions, enable this input port. If this port is disabled, the block uses the optimal state sequences calculated in the previous control interval as initial guesses.

To use the same initial guesses over the prediction horizon, connect
**x.init** to a vector signal with
*N _{x}* elements, where

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

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

`e.init`

— Initial guess for the slack variable at the solutionnonnegative scalar

To specify an initial guess for the slack variable at the solution, enable this
input port and connect a nonnegative scalar signal. If this port is disabled, the
block uses an initial guess of `0`

.

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

`mv`

— Optimal manipulated variable control actioncolumn vector

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

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

, then**mv**is the same as**last_mv**

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

`cost`

— Objective function costnonnegative 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 only meaningful when the **nlp.status** output
is nonnegative.

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

`slack`

— Slack variable0 | nonnegative scalar

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

or
a positive scalar value.

ε = 0 — All soft constraints are satisfied over 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 the ECR values for each constraint).

To enable this port, select the **Slack variable**
parameter.

`nlp.status`

— Optimization statusscalar

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

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

`mv.seq`

— Optimal manipulated variable sequencematrix

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

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.

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

`x.seq`

— Optimal prediction model state sequencematrix

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

The first *p* rows of **x.seq** contain the
calculated optimal state values from current time *k* to time
*k*+*p*-1. The first row of
**x.seq** contains the current estimated state values. Since the
controller does not calculate optimal states at time *k*+*p*, the final two rows of **x.seq** are
identical.

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

`y.seq`

— Optimal output variable sequencematrix

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

The first *p* rows of **y.seq** contain the
calculated optimal output values from current time *k* to time
*k*+*p*-1. The first row of
**y.seq** is computed based on the current estimated states and the
current measured disturbances (first row of input **md**). Since the
controller does not calculate optimal output values at time *k*+*p*, the final two rows of **y.seq** are
identical.

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

`Nonlinear MPC Controller`

— Controller object`nlmpc`

object nameYou must provide an `nlmpc`

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

object in the MATLAB workspace.

Block Parameter:
`nlmpcobj` |

Type: string, character vector |

Default:
`""` |

`Use prediction model sample time`

— Flag for using the prediction model sample timeon (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.

Block Parameter:
`UseObjectTs` |

Type: string, character vector |

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

Default:
`"on"` |

`Make block run at a different sample time`

— Controller sample timepositive finite scalar

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

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

Block Parameter:
`TsControl` |

Type: string, character vector |

Default:
`""` |

`Use MEX to speed up simulation`

— Flag for simulating controller use MEX functionoff (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.

Block Parameter:
`UseMEX` |

Type: string, character vector |

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

Default:
`"off"` |

`Specify MEX function name`

— Controller MEX function namestring

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

function.

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

Block Parameter:
`mexname` |

Type: string, character vector |

Default:
`""` |

`Measured disturbances`

— Add measured disturbance input portoff (default) | on

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

Block Parameter:
`md_enabled` |

Type: string, character vector |

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

Default:
`"off"` |

`Targets for manipulated variables`

— Add manipulated variable target input portoff (default) | on

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

Block Parameter:
`mvtarget_enabled` |

Type: string, character vector |

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

Default:
`"off"` |

`Model parameters`

— Add model parameters input portoff (default) | on

If your controller uses optional parameters, you must select this parameter to add
the **params** output port to the block.

For more information on creating a parameter bus signal, see `createParameterBus`

.

Block Parameter:
`param_enabled` |

Type: string, character vector |

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

Default:
`"off"` |

`Optimal cost`

— Odd optimal cost output portoff (default) | on

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

Block Parameter:
`cost_enabled` |

Type: string, character vector |

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

Default:
`"off"` |

`Optimal control sequence`

— Add optimal control sequence output portoff (default) | on

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

Block Parameter:
`mvseq_enabled` |

Type: string, character vector |

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

Default:
`"off"` |

`Optimal state sequence`

— Add optimal state sequence output portoff (default) | on

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

Block Parameter:
`stateseq_enabled` |

Type: string, character vector |

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

Default:
`"off"` |

`Optimal output sequence`

— Add optimal output sequence output portoff (default) | on

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

Block Parameter:
`ovseq_enabled` |

Type: string, character vector |

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

Default:
`"off"` |

`Slack variable`

— Add slack variable output portoff (default) | on

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

Block Parameter:
`slack_enabled` |

Type: string, character vector |

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

Default:
`"off"` |

`Optimization status`

— Add optimization status output portoff (default) | on

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

Block Parameter:
`status_enabled` |

Type: string, character vector |

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

Default:
`"off"` |

`Lower OV limits`

— Add minimum OV constraint input portoff (default) | on

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

Block Parameter:
`ov_min` |

Type: string, character vector |

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

Default:
`"off"` |

`Upper OV limits`

— Add maximum OV constraint input portoff (default) | on

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

Block Parameter:
`ov_max` |

Type: string, character vector |

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

Default:
`"off"` |

`Lower MV limits`

— Add minimum MV constraint input portoff (default) | on

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

Block Parameter:
`mv_min` |

Type: string, character vector |

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

Default:
`"off"` |

`Upper MV limits`

— Add maximum MV constraint input portoff (default) | on

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

Block Parameter:
`mv_max` |

Type: string, character vector |

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

Default:
`"off"` |

`Lower MVRate limits`

— Add minimum MV rate constraint input portoff (default) | on

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

Block Parameter:
`mvrate_min` |

Type: string, character vector |

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

Default:
`"off"` |

`Upper MVRate limits`

— Add maximum MV rate constraint input portoff (default) | on

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

Block Parameter:
`mvrate_max` |

Type: string, character vector |

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

Default:
`"off"` |

`Lower state limits`

— Add minimum state constraint input portoff (default) | on

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

Block Parameter:
`state_min` |

Type: string, character vector |

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

Default:
`"off"` |

`Upper state limits`

— Add maximum state constraint input portoff (default) | on

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

Block Parameter:
`state_max` |

Type: string, character vector |

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

Default:
`"off"` |

`OV weights`

— Add OV tuning weights input portoff (default) | on

Select this parameter to add the **y.wt** input port to the
block.

Block Parameter:
`ov_weight` |

Type: string, character vector |

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

Default:
`"off"` |

`MV weights`

— Add MV tuning weights input portoff (default) | on

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

Block Parameter:
`mv_weight` |

Type: string, character vector |

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

Default:
`"off"` |

`MVRate weights`

— Add MV rate tuning weights input portoff (default) | on

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

Block Parameter:
`mvrate_weight` |

Type: string, character vector |

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

Default:
`"off"` |

`ECR weight`

— Add ECR tuning weight input portoff (default) | on

Select this parameter to add the **ecr.wt** input port to the
block.

Block Parameter:
`ecr_weight` |

Type: string, character vector |

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

Default:
`"off"` |

`Initial guess`

— Add initial guess input portsoff (default) | on

Select this parameter to add the **mv.init**,
**x.init**, and **e.init** input ports to the
block.

**Note**

By default, the Nonlinar MPC Controller block uses the calculated optimal manipulated variable and state trajectories from one control interval as the initial guesses for the next control interval.

Enable the initial guess ports only if it is necessary for your application.

Block Parameter:
`nlp_initialize` |

Type: string, character vector |

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

Default:
`"off"` |

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

Usage notes and limitations:

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

`fmincon`

solver with the SQP algorithm.When used for code generation, nonlinear MPC controllers do not support anonymous functions for the prediction model, custom cost function, or custom constraint functions.

If your controller uses optional parameters, you must also generate code for the Bus Creator block connected to the

**params**input port. To do so, place the Nonlinear MPC Controller and Bus Creator blocks within a subsystem, and generate code for that subsystem.

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)