Main Content

Nonlinear model predictive controller

A nonlinear model predictive controller computes optimal control moves across the prediction horizon using a nonlinear prediction model, a nonlinear cost function, and nonlinear constraints. For more information on nonlinear MPC, see Nonlinear MPC.

`nx`

— Number of prediction model statespositive integer

Number of prediction model states, specified as a positive integer. This value is
stored in the `Dimensions.NumberOfStates`

controller read-only
property. You cannot change the number of states after creating the controller
object.

`ny`

— Number of prediction model outputspositive integer

Number of prediction model outputs, specified as a positive integer. This value is
stored in the `Dimensions.NumberOfOutputs`

controller read-only
property. You cannot change the number of outputs after creating the controller
object.

`nu`

— Number of prediction model inputspositive integer

Number of prediction model inputs, which are all set to be manipulated variables,
specified as a positive integer. This value is stored in the
`Dimensions.NumberOfInputs`

controller read-only property. You
cannot change the number of manipulated variables after creating the controller
object.

`mvIndex`

— Manipulated variable indicesvector of positive integers

Manipulated variable indices, specified as a vector of positive integers. This
value is stored in the `Dimensions.MVIndex`

controller read-only
property. You cannot change these indices after creating the controller object.

The combined set of indices from `mvIndex`

,
`mdIndex`

, and `udIndex`

must contain all
integers from `1`

through
*N _{u}*, where

`mdIndex`

— Measured disturbance indicesvector of positive integers

Measured disturbance indices, specified as a vector of positive integers. This
value is stored in the `Dimensions.MDIndex`

controller read-only
property. You cannot change these indices after creating the controller object.

The combined set of indices from `mvIndex`

,
`mdIndex`

, and `udIndex`

must contain all
integers from `1`

through
*N _{u}*, where

`udIndex`

— Unmeasured disturbance indicesvector of positive integers

Unmeasured disturbance indices, specified as a vector of positive integers. This
value is stored in the `Dimensions.UDIndex`

controller read-only
property. You cannot change these indices after creating the controller object.

The combined set of indices from `mvIndex`

,
`mdIndex`

, and `udIndex`

must contain all
integers from `1`

through
*N _{u}*, where

`Ts`

— Prediction model sample time`1`

(default) | positive finite scalarPrediction model sample time, specified as a positive finite scalar. The controller
uses a discrete-time model with sample time `Ts`

for prediction. If
you specify a continuous-time prediction model
(`Model.IsContinuousTime`

is `true`

), then the
controller discretizes the model using the built-in implicit trapezoidal rule with a
sample time of `Ts`

.

`PredictionHorizon`

— Prediction horizon`10`

(default) | positive integerPrediction horizon steps, specified as a positive integer. The product of
`PredictionHorizon`

and `Ts`

is the prediction
time; that is, how far the controller looks into the future.

`ControlHorizon`

— Control horizon`2`

(default) | positive integer | vector of positive integersControl horizon, specified as one of the following:

Positive integer,

*m*, between`1`

and*p*, inclusive, where*p*is equal to`PredictionHorizon`

. In this case, the controller computes*m*free control moves occurring at times*k*through*k*+*m*-1, and holds the controller output constant for the remaining prediction horizon steps from*k*+*m*through*k*+*p*-1. Here,*k*is the current control interval.Vector of positive integers [

*m*_{1},*m*_{2}, …], specifying the lengths of blocking intervals. By default the controller computes*M*blocks of free moves, where*M*is the number of blocking intervals. The first free move applies to times*k*through*k*+*m*_{1}-1, the second free move applies from time*k*+*m*_{1}through*k*+*m*_{1}+*m*_{2}-1, and so on. Using block moves can improve the robustness of your controller. The sum of the values in`ControlHorizon`

must match the prediction horizon*p*. If you specify a vector whose sum is:Less than the prediction horizon, then the controller adds a blocking interval. The length of this interval is such that the sum of the interval lengths is

*p*. For example, if*p*=`10`

and you specify a control horizon of`ControlHorizon`

=`[1 2 3]`

, then the controller uses four intervals with lengths`[1 2 3 4]`

.Greater than the prediction horizon, then the intervals are truncated until the sum of the interval lengths is equal to

*p*. For example, if*p*=`10`

and you specify a control horizon of`ControlHorizon`

=`[1 2 3 6 7]`

, then the controller uses four intervals with lengths`[1 2 3 4]`

.

Piecewise constant blocking moves are often too restrictive for optimal path
planning applications. To produce a less-restrictive, better-conditioned nonlinear
programming problem, you can specify piecewise linear manipulated variable blocking
intervals. To do so, set the `Optimization.MVInterpolationOrder`

property of your `nlmpc`

controller object to
`1`

.

For more information on how manipulated variable blocking works with different interpolation methods, see Manipulated Variable Blocking.

`Dimensions`

— Prediction model dimensional informationstructure

This property is read-only.

Prediction model dimensional information, specified when the controller is created and stored as a structure with the following fields.

`NumberOfStates`

— Number of statespositive integer

Number of states in the prediction model, specified as a positive integer.
This value corresponds to `nx`

.

`NumberOfOutputs`

— Number of outputspositive integer

Number of outputs in the prediction model, specified as a positive integer.
This value corresponds to `ny`

.

`NumberOfInputs`

— Number of statespositive integer

Number of inputs in the prediction model, specified as a positive integer.
This value corresponds to either `nmv`

or the sum of the
lengths of `mvIndex`

, `mdIndex`

, and
`udIndex`

.

`MVIndex`

— Manipulated variable indicesvector of positive integers

Manipulated variable indices for the prediction model, specified as a vector
of positive integers. This value corresponds to
`mvIndex`

.

`MDIndex`

— Measured disturbance indicesvector of positive integers

Measured disturbance indices for the prediction model, specified as a vector
of positive integers. This value corresponds to
`mdIndex`

.

`UDIndex`

— Unmeasured disturbance indicesvector of positive integers

Unmeasured disturbance indices for the prediction model, specified as a vector
of positive integers. This value corresponds to
`udIndex`

.

`Model`

— Prediction modelstructure

Prediction model, specified as a structure with the following fields.

`StateFcn`

— State functionstring | character vector | function handle

State function, specified as a string, character vector, or function handle.
For a continuous-time prediction model, `StateFcn`

is the state
derivative function. For a discrete-time prediction model,
`StateFcn`

is the state update function.

If your state function is continuous-time, the controller automatically
discretizes the model using the implicit trapezoidal rule. This method can handle
moderately stiff models, and its prediction accuracy depends on the controller
sample time `Ts`

; that is, a large sample time leads to
inaccurate prediction.

If the default discretization method does not provide satisfactory prediction for your application, you can specify your own discrete-time prediction model that uses a different method, such as the multistep forward Euler rule.

You can specify your state function in one of the following ways:

Name of a function in the current working folder or on the MATLAB

^{®}path, specified as a string or character vector`Model.StateFcn = "myStateFunction";`

Handle to a function in the current working folder or on the MATLAB path

Model.StateFcn = @myStateFunction;

Anonymous function

Model.StateFcn = @(x,u,params) myStateFunction(x,u,params)

For more information, see Specify Prediction Model for Nonlinear MPC.

`OutputFcn`

— Output function`[]`

(default) | string | character vector | function handleOutput function, specified as a string, character vector, or function handle.
If the number of states and outputs of the prediction model are the same, you can
omit `OutputFcn`

, which implies that all states are measurable;
that is, each output corresponds to one state.

**Note**

You output function cannot have direct feedthrough from any manipulated variable to any output at any time.

You can specify your output function in one of the following ways:

Name of a function in the current working folder or on the MATLAB path, specified as a string or character vector

`Model.OutputFcn = "myOutputFunction";`

Handle to a function in the current working folder or on the MATLAB path

Model.OutputFcn = @myOutputFunction;

Anonymous function

Model.OutputFcn = @(x,u,params) myOutputFunction(x,u,params)

For more information, see Specify Prediction Model for Nonlinear MPC.

`IsContinuousTime`

— Flag indicating prediction model time domain`true`

(default) | `false`

Flag indicating prediction model time domain, specified as one of the following:

`true`

— Continuous-time prediction model. In this case, the controller automatically discretizes the model during prediction using`Ts`

.`false`

— Discrete-time prediction model. In this case,`Ts`

is the sample time of the model.

**Note**

`IsContinuousTime`

must be consistent with the functions
specified in `Model.StateFcn`

and
`Model.OutputFcn`

.

If `IsContinuousTime`

is `true`

,
`StateFcn`

must return the derivative of the state with
respect to time, at the current time. Otherwise `StateFcn`

must return the state at the next control interval.

`NumberOfParameters`

— Number of optional model parameters`0`

(default) | nonnegative integerNumber of optional model parameters used by the prediction model, custom cost
function, and custom constraint functions, specified as a nonnegative integer. The
number of parameters includes all the parameters used by these functions. For
example, if the state function uses only parameter `p1`

, the
constraint functions use only parameter `p2`

, and the cost
function uses only parameter `p3`

, then
`NumberOfParameters`

is `3`

.

`States`

— State information, bounds, and scale factorsstructure array

State information, bounds, and scale factors, specified as a structure array with
*N _{x}* elements, where

`Min`

— State lower bound`-Inf`

(default) | scalar | vectorState lower bound, specified as a scalar or vector. By default, the lower bound is unconstrained.

To use the same bound across the prediction horizon, specify a scalar value.

To vary the bound over the prediction horizon from time *k*+1
to time *k*+*p*, specify a vector of up to
*p* values. Here, *k* is the current time and
*p* is the prediction horizon. If you specify fewer than
*p* values, the final bound is used for the remaining steps of
the prediction horizon.

State bounds are always hard constraints.

`Max`

— State upper bound`Inf`

(default) | scalar | vectorState upper bound, specified as a scalar or vector. By default, the upper bound is unconstrained.

To use the same bound across the prediction horizon, specify a scalar value.

To vary the bound over the prediction horizon from time *k*+1
to time *k*+*p*, specify a vector of up to
*p* values. Here, *k* is the current time and
*p* is the prediction horizon. If you specify fewer than
*p* values, the final bound is used for the remaining steps of
the prediction horizon.

State bounds are always hard constraints.

`Name`

— State namestring | character vector

State name, specified as a string or character vector. The default state name
is `"x#"`

, where `#`

is its state index.

`Units`

— State units`""`

(default) | string | character vectorState units, specified as a string or character vector.

`ScaleFactor`

— State scale factor`1`

(default) | positive finite scalarState scale factor, specified as a positive finite scalar. In general, use the operating range of the state. Specifying the proper scale factor can improve numerical conditioning for optimization.

`OutputVariables`

— Output variable information, bounds, and scale factorsstructure array

Output variable (OV) information, bounds, and scale factors, specified as a
structure array with *N _{y}* elements, where

`OV`

instead of
`OutputVariables`

.Each structure element has the following fields.

`Min`

— OV lower bound`-Inf`

(default) | scalar | vectorOV lower bound, specified as a scalar or vector. By default, this lower bound is unconstrained.

To use the same bound across the prediction horizon, specify a scalar value.

To vary the bound over the prediction horizon from time *k*+1
to time *k*+*p*, specify a vector of up to
*p* values. Here, *k* is the current time and
*p* is the prediction horizon. If you specify fewer than
*p* values, the final bound is used for the remaining steps of
the prediction horizon.

`Max`

— OV upper bound`Inf`

(default) | scalar | vectorOV upper bound, specified as a scalar or vector. By default, this upper bound is unconstrained.

To use the same bound across the prediction horizon, specify a scalar value.

*k*+1
to time *k*+*p*, specify a vector of up to
*p* values. Here, *k* is the current time and
*p* is the prediction horizon. If you specify fewer than
*p* values, the final bound is used for the remaining steps of
the prediction horizon.

`MinECR`

— OV lower bound softness`1`

(default) | nonnegative finite scalar | vectorOV lower bound softness, where a larger ECR value indicates a softer constraint, specified as a nonnegative finite scalar or vector. By default, OV upper bounds are soft constraints.

To use the same ECR value across the prediction horizon, specify a scalar value.

To vary the ECR value over the prediction horizon from time
*k*+1 to time *k*+*p*,
specify a vector of up to *p* values. Here, *k*
is the current time and *p* is the prediction horizon. If you
specify fewer than *p* values, the final ECR value is used for
the remaining steps of the prediction horizon.

`MaxECR`

— OV upper bound softness`1`

(default) | nonnegative finite scalar | vectorOV upper bound softness, where a larger ECR value indicates a softer constraint, specified as a nonnegative finite scalar or vector. By default, OV lower bounds are soft constraints.

To use the same ECR value across the prediction horizon, specify a scalar value.

To vary the ECR value over the prediction horizon from time
*k*+1 to time *k*+*p*,
specify a vector of up to *p* values. Here, *k*
is the current time and *p* is the prediction horizon. If you
specify fewer than *p* values, the final ECR value is used for
the remaining steps of the prediction horizon.

`Name`

— OV namestring | character vector

OV name, specified as a string or character vector. The default OV name is
`"y#"`

, where `#`

is its output index.

`Units`

— OV units`""`

(default) | string | character vectorOV units, specified as a string or character vector.

`ScaleFactor`

— OV scale factor`1`

(default) | positive finite scalarOV scale factor, specified as a positive finite scalar. In general, use the operating range of the output variable. Specifying the proper scale factor can improve numerical conditioning for optimization.

`ManipulatedVariables`

— Manipulated variable information, bounds, and scale factorsstructure array

Manipulated Variable (MV) information, bounds, and scale factors, specified as a
structure array with *N _{mv}* elements, where

`MV`

instead
of `ManipulatedVariables`

.Each structure element has the following fields.

`Min`

— MV lower bound`-Inf`

(default) | scalar | vectorMV lower bound, specified as a scalar or vector. By default, this lower bound is unconstrained.

To use the same bound across the prediction horizon, specify a scalar value.

To vary the bound over the prediction horizon from time *k*
to time *k*+*p*-1, specify a vector of up to
*p* values. Here, *k* is the current time and
*p* is the prediction horizon. If you specify fewer than
*p* values, the final bound is used for the remaining steps of
the prediction horizon.

`Max`

— MV upper bound`Inf`

(default) | scalar | vectorMV upper bound, specified as a scalar or vector. By default, this upper bound is unconstrained.

To use the same bound across the prediction horizon, specify a scalar value.

To vary the bound over the prediction horizon from time *k*
to time *k*+*p*-1, specify a vector of up to
*p* values. Here, *k* is the current time and
*p* is the prediction horizon. If you specify fewer than
*p* values, the final bound is used for the remaining steps of
the prediction horizon.

`MinECR`

— MV lower bound softness`0`

(default) | nonnegative scalar | vectorMV lower bound softness, where a larger ECR value indicates a softer constraint, specified as a nonnegative scalar or vector. By default, MV lower bounds are hard constraints.

To use the same ECR value across the prediction horizon, specify a scalar value.

To vary the ECR value over the prediction horizon from time
*k* to time *k*+*p*-1,
specify a vector of up to *p* values. Here, *k*
is the current time and *p* is the prediction horizon. If you
specify fewer than *p* values, the final ECR value is used for
the remaining steps of the prediction horizon.

`MaxECR`

— MV upper bound`0`

(default) | nonnegative scalar | vectorMV upper bound softness, where a larger ECR value indicates a softer constraint, specified as a nonnegative scalar or vector. By default, MV upper bounds are hard constraints.

To use the same ECR value across the prediction horizon, specify a scalar value.

To vary the ECR value over the prediction horizon from time
*k* to time *k*+*p*-1,
specify a vector of up to *p* values. Here, *k*
is the current time and *p* is the prediction horizon. If you
specify fewer than *p* values, the final ECR value is used for
the remaining steps of the prediction horizon.

`RateMin`

— MV rate of change lower bound`-Inf`

(default) | nonpositive scalar | vectorMV rate of change lower bound, specified as a nonpositive scalar or vector.
The MV rate of change is defined as *MV*(*k*) -
*MV*(*k*-1), where *k* is the
current time. By default, this lower bound is unconstrained.

To use the same bound across the prediction horizon, specify a scalar value.

To vary the bound over the prediction horizon from time *k*
to time *k*+*p*-1, specify a vector of up to
*p* values. Here, *k* is the current time and
*p* is the prediction horizon. If you specify fewer than
*p* values, the final bound is used for the remaining steps of
the prediction horizon.

`RateMax`

— MV rate of change upper bound`Inf`

(default) | nonnegative scalar | vectorMV rate of change upper bound, specified as a nonnegative scalar or vector.
The MV rate of change is defined as *MV*(*k*) -
*MV*(*k*-1), where *k* is the
current time. By default, this lower bound is unconstrained.

To use the same bound across the prediction horizon, specify a scalar value.

*k*
to time *k*+*p*-1, specify a vector of up to
*p* values. Here, *k* is the current time and
*p* is the prediction horizon. If you specify fewer than
*p* values, the final bound is used for the remaining steps of
the prediction horizon.

`RateMinECR`

— MV rate of change lower bound softness`0`

(default) | nonnegative finite scalar | vectorMV rate of change lower bound softness, where a larger ECR value indicates a softer constraint, specified as a nonnegative finite scalar or vector. By default, MV rate of change lower bounds are hard constraints.

To use the same ECR value across the prediction horizon, specify a scalar value.

To vary the ECR values over the prediction horizon from time
*k* to time *k*+*p*-1,
specify a vector of up to *p* values. Here, *k*
is the current time and *p* is the prediction horizon. If you
specify fewer than *p* values, the final ECR values are used for
the remaining steps of the prediction horizon.

`RateMaxECR`

— MV rate of change upper bound softness`0`

(default) | nonnegative finite scalar | vectorMV rate of change upper bound softness, where a larger ECR value indicates a softer constraint, specified as a nonnegative finite scalar or vector. By default, MV rate of change upper bounds are hard constraints.

To use the same ECR value across the prediction horizon, specify a scalar value.

To vary the ECR values over the prediction horizon from time
*k* to time *k*+*p*-1,
specify a vector of up to *p* values. Here, *k*
is the current time and *p* is the prediction horizon. If you
specify fewer than *p* values, the final ECR values are used for
the remaining steps of the prediction horizon.

`Name`

— MV namestring | character vector

MV name, specified as a string or character vector. The default MV name is
`"u#"`

, where `#`

is its input index.

`Units`

— MV units`""`

(default) | string | character vectorMV units, specified as a string or character vector.

`ScaleFactor`

— MV scale factor`1`

(default) | positive finite scalarMV scale factor, specified as a positive finite scalar. In general, use the operating range of the manipulated variable. Specifying the proper scale factor can improve numerical conditioning for optimization.

`MeasuredDisturbances`

— Measured disturbance information and scale factorsstructure array

Measured disturbance (MD) information and scale factors, specified as a structure
array with *N _{md}* elements, where

`MeasuredDisturbances`

is `[]`

. To access this
property, you can use the alias `MD`

instead of
`MeasuredDisturbances`

.Each structure element has the following fields.

`Name`

— MD namestring | character vector

MD name, specified as a string or character vector. The default MD name is
`"u#"`

, where `#`

is its input index.

`Units`

— MD units`""`

(default) | string | character vectorMD units, specified as a string or character vector.

`ScaleFactor`

— MD scale factor`1`

(default) | positive finite scalarMD scale factor, specified as a positive finite scalar. In general, use the operating range of the disturbance. Specifying the proper scale factor can improve numerical conditioning for optimization.

`Weights`

— Standard cost function tuning weightsstructure

Standard cost function tuning weights, specified as a structure. The controller applies these weights to the scaled variables. Therefore, the tuning weights are dimensionless values.

**Note**

If you define a custom cost function using
`Optimization.CustomCostFcn`

and set
`Optimization.ReplaceStandardCost`

to `true`

, then
the controller ignores the standard cost function tuning weights in
`Weights`

.

`Weights`

has the following fields.

`ManipulatedVariables`

— Manipulated variable tuning weightsrow vector | array

Manipulated variable tuning weights, which penalize deviations from MV
targets, specified as a row vector or array of nonnegative values. The default
weight for all manipulated variables is `0`

.

To use the same weights across the prediction horizon, specify a row vector of length
*N _{mv}*, where

To vary the tuning weights over the prediction horizon from time *k* to time *k*+*p*-1, specify an array with *N _{mv}* columns and up to

To specify MV targets at run time, create an `nlmpcmoveopt`

object, and set its `MVTarget`

property.

`ManipulatedVariablesRate`

— Manipulated variable rate tuning weightsrow vector | array

Manipulated variable rate tuning weights, which penalize large changes in
control moves, specified as a row vector or array of nonnegative values. The
default weight for all manipulated variable rates is
`0.1`

.

To use the same weights across the prediction horizon, specify a row vector of length
*N _{mv}*, where

To vary the tuning weights over the prediction horizon from time *k* to time
*k*+*p*-1, specify
an array with *N _{mv}* columns
and up to

`OutputVariables`

— Output variable tuning weightsvector | array

Output variable tuning weights, which penalize deviation from output
references, specified as a row vector or array of nonnegative values. The default
weight for all output variables is `1`

.

To use the same weights across the prediction horizon, specify a row vector of length
*N _{y}*, where

To vary the tuning weights over the prediction horizon from time *k*+1 to time *k*+*p*, specify an array with *N _{y}* columns and up to

`ECR`

— Slack variable tuning weight`1e5`

(default) | positive scalarSlack variable tuning weight, specified as a positive scalar.

`Optimization`

— Custom optimization functions and solverstructure

Custom optimization functions and solver, specified as a structure with the following fields.

`CustomCostFcn`

— Custom cost function`[]`

| string | character vector | function handleCustom cost function, specified as one of the following:

Name of a function in the current working folder or on the MATLAB path, specified as a string or character vector

`Optimization.CustomCostFcn = "myCostFunction";`

Handle to a function in the current working folder or on the MATLAB path

Optimization.CustomCostFcn = @myCostFunction;

Anonymous function

Optimization.CustomCostFcn = @(X,U,e,data,params) myCostFunction(X,U,e,data,params);

Your cost function must have the signature:

`function J = myCostFunction(X,U,e,data,params)`

For more information, see Specify Cost Function for Nonlinear MPC.

`ReplaceStandardCost`

— Flag indicating whether to replace the standard cost function`true`

(default) | `false`

Flag indicating whether to replace the standard cost function with the custom cost function, specified as one of the following:

`true`

— The controller uses the custom cost alone as the objective function during optimization. In this case, the`Weights`

property of the controller is ignored.`false`

— The controller uses the sum of the standard cost and custom cost as the objective function during optimization.

If you do not specify a custom cost function using
`CustomCostFcn`

, then the controller ignores
`RepalceStandardCost`

.

For more information, see Specify Cost Function for Nonlinear MPC.

`CustomEqConFcn`

— Custom equality constraint function`[]`

(default) | string | character vector | function handleCustom equality constraint function, specified as one of the following:

Name of a function in the current working folder or on the MATLAB path, specified as a string or character vector

`Optimization.CustomEqConFcn = "myEqConFunction";`

Handle to a function in the current working folder or on the MATLAB path

Optimization.CustomEqConFcn = @myEqConFunction;

Anonymous function

Optimization.CustomEqConFcn = @(X,U,data,params) myEqConFunction(X,U,data,params);

Your equality constraint function must have the signature:

function ceq = myEqConFunction(X,U,data,p1,p2,...)

For more information, see Specify Constraints for Nonlinear MPC.

`CustomIneqConFcn`

— Custom inequality constraint function`[]`

(default) | string | character vector | function handleCustom inequality constraint function, specified as one of the following:

`Optimization.CustomIneqConFcn = "myIneqConFunction";`

Handle to a function in the current working folder or on the MATLAB path

Optimization.CustomIneqConFcn = @myIneqConFunction;

Anonymous function

Optimization.CustomIneqConFcn = @(X,U,e,data,params) myIneqConFunction(X,U,e,data,params);

Your equality constraint function must have the signature:

`function cineq = myIneqConFunction(X,U,e,data,params)`

For more information, see Specify Constraints for Nonlinear MPC.

`CustomSolverFcn`

— Custom nonlinear programming solver`[]`

(default) | string | character vector | function handleCustom nonlinear programming solver function, specified as a string, character vector, or function handle. If you do not have Optimization Toolbox™ software, you must specify your own custom nonlinear programming solver. You can specify your custom solver function in one of the following ways:

`Optimization.CustomSolverFcn = "myNLPSolver";`

Handle to a function in the current working folder or on the MATLAB path

Optimization.CustomSolverFcn = @myNLPSolver;

For more information, see Configure Optimization Solver for Nonlinear MPC.

`SolverOptions`

— Solver optionsoptions object for

`fmincon`

| `[]`

Solver options, specified as an options object for
`fmincon`

or `[]`

.

If you have Optimization Toolbox software, `SolverOptions`

contains an options
object for the `fmincon`

solver.

If you do not have Optimization Toolbox, `SolverOptions`

is `[]`

.

For more information, see Configure Optimization Solver for Nonlinear MPC.

`RunAsLinearMPC`

— Flag indicating whether to simulate as a linear controller`"off"`

(default) | `"Adaptive"`

| `"TimeVarying"`

Flag indicating whether to simulate as a linear controller, specified as one of the following:

`"off"`

— Simulate the controller as a nonlinear controller with a nonlinear prediction model.`"Adaptive"`

— For each control interval, a linear model is obtained from the specified nonlinear state and output functions at the current operating point and used across the prediction horizon. To determine if an adaptive MPC controller provides comparable performance to the nonlinear controller, use this option. For more information on adaptive MPC, see Adaptive MPC.`"TimeVarying"`

— For each control interval,*p*linear models are obtained from the specified nonlinear state and output functions at the*p*operating points predicted from the previous interval, one for each prediction horizon step. To determine if a linear time-varying MPC controller provides comparable performance to the nonlinear controller, use this option. For more information on time-varying MPC, see Time-Varying MPC.

To use the either the `"Adaptive"`

or
`"TimeVarying"`

option, your controller must have no custom
constraints and no custom cost function.

For an example that simulates a nonlinear MPC controller as a linear controller, see Optimization and Control of a Fed-Batch Reactor Using Nonlinear MPC.

`UseSuboptimalSolution`

— Flag indicating whether a suboptimal solution is acceptable`false`

(default) | `true`

Flag indicating whether a suboptimal solution is acceptable, specified as a
logical value. When the nonlinear programming solver reaches the maximum number of
iterations without finding a solution (the exit flag is `0`

), the
controller:

Freezes the MV values if

`UseSuboptimalSolution`

is`false`

Applies the suboptimal solution found by the solver after the final iteration if

`UseSuboptimalSolution`

is`true`

To specify the maximum number of iterations, use
`Optimization.SolverOptions.MaxIter`

.

`MVInterpolationOrder`

— Linear interpolation order used for block moves`0`

(default) | `1`

Linear interpolation order used by block moves, specified as one of the following:

`0`

— Use piecewise constant manipulated variable intervals.`1`

— Use piecewise linear manipulated variable intervals.

If the control horizon is a scalar, then the controller ignores
`MVInterpolationOrder`

.

For more information on manipulated variable blocking, see Manipulated Variable Blocking.

`Jacobian`

— Jacobians of model functions, and custom cost and constraint functionsstructure

Jacobians of model functions, and custom cost and constraint functions, specified as a structure. It is best practice to use Jacobians whenever they are available, since they improve optimization efficiency. If you do not specify a Jacobian for a given function, the nonlinear programming solver must numerically compute the Jacobian.

The `Jacobian`

structure contains the following fields.

`StateFcn`

— Jacobian of state function`[]`

(default) | string | character vector | function handleJacobian of state function `z`

from
`Model.StateFcn`

, specified as one of the following

`Model.StateFcn = "myStateJacobian";`

Handle to a function in the current working folder or on the MATLAB path

Model.StateFcn = @myStateJacobian;

Anonymous function

Model.StateFcn = @(x,u,params) myStateJacobian(x,u,params)

For more information, see Specify Prediction Model for Nonlinear MPC.

`OutputFcn`

— Jacobian of output function`[]`

(default) | string | character vector | function handleJacobian of output function `y`

from
`Model.OutputFcn`

, specified as one of the following:

`Model.StateFcn = "myOutputJacobian";`

Handle to a function in the current working folder or on the MATLAB path

Model.StateFcn = @myOutputJacobian;

Anonymous function

Model.StateFcn = @(x,u,params) myOutputJacobian(x,u,params)

For more information, see Specify Prediction Model for Nonlinear MPC.

`CustomCostFcn`

— Jacobian of custom cost function`[]`

| string | character vector | function handleJacobian of custom cost function `J`

from
`Optimization.CustomCostFcn`

, specified as one of the
following:

`Jacobian.CustomCostFcn = "myCostJacobian";`

Handle to a function in the current working folder or on the MATLAB path

Jacobian.CustomCostFcn = @myCostJacobian;

Anonymous function

Jacobian.CustomCostFcn = @(X,U,e,data,params) myCostJacobian(X,U,e,data,params)

Your cost Jacobian function must have the signature:

`function [G,Gmv,Ge] = myCostJacobian(X,U,e,data,params)`

For more information, see Specify Cost Function for Nonlinear MPC.

`CustomEqConFcn`

— Jacobian of custom equality constraints`[]`

(default) | string | character vector | function handleJacobian of custom equality constraints `ceq`

from
`Optimization.CustomEqConFcn`

, specified as one of the
following:

`Jacobian.CustomEqConFcn = "myEqConJacobian";`

Handle to a function in the current working folder or on the MATLAB path

Jacobian.CustomEqConFcn = @myEqConJacobian;

Anonymous function

Jacobian.CustomEqConFcn = @(X,U,data,params) myEqConJacobian(X,U,data,params);

Your equality constraint Jacobian function must have the signature:

`function [G,Gmv] = myEqConJacobian(X,U,data,params)`

For more information, see Specify Constraints for Nonlinear MPC.

`CustomIneqConFcn`

— Jacobian of custom inequality constraints`[]`

(default) | string | character vector | function handleJacobian of custom inequality constraints `c`

from
`Optimization.CustomIneqConFcn`

, specified as one of the
following:

`Jacobian.CustomEqConFcn = "myIneqConJacobian";`

Handle to a function in the current working folder or on the MATLAB path

Jacobian.CustomEqConFcn = @myIneqConJacobian;

Anonymous function

Jacobian.CustomEqConFcn = @(X,U,data,params) myIneqConJacobian(X,U,data,params);

Your inequality constraint Jacobian function must have the signature:

`function [G,Gmv,Ge] = myIneqConJacobian(X,U,data,params)`

For more information, see Specify Constraints for Nonlinear MPC.

`nlmpcmove` | Compute optimal control action for nonlinear MPC controller |

`validateFcns` | Examine prediction model and custom functions of `nlmpc` or
`nlmpcMultistage` objects for potential problems |

`convertToMPC` | Convert `nlmpc` object into one or more `mpc`
objects |

`createParameterBus` | Create Simulink bus object and configure Bus Creator block for passing model parameters to Nonlinear MPC Controller block |

Create a nonlinear MPC controller with four states, two outputs, and one input.

nx = 4; ny = 2; nu = 1; nlobj = nlmpc(nx,ny,nu);

In standard cost function, zero weights are applied by default to one or more OVs because there are fewer MVs than OVs.

Specify the sample time and horizons of the controller.

Ts = 0.1; nlobj.Ts = Ts; nlobj.PredictionHorizon = 10; nlobj.ControlHorizon = 5;

Specify the state function for the controller, which is in the file `pendulumDT0.m`

. This discrete-time model integrates the continuous time model defined in `pendulumCT0.m`

using a multistep forward Euler method.

```
nlobj.Model.StateFcn = "pendulumDT0";
nlobj.Model.IsContinuousTime = false;
```

The discrete-time state function uses an optional parameter, the sample time `Ts`

, to integrate the continuous-time model. Therefore, you must specify the number of optional parameters as `1`

.

nlobj.Model.NumberOfParameters = 1;

Specify the output function for the controller. In this case, define the first and third states as outputs. Even though this output function does not use the optional sample time parameter, you must specify the parameter as an input argument (`Ts`

).

nlobj.Model.OutputFcn = @(x,u,Ts) [x(1); x(3)];

Validate the prediction model functions for nominal states `x0`

and nominal inputs `u0`

. Since the prediction model uses a custom parameter, you must pass this parameter to `validateFcns`

.

x0 = [0.1;0.2;-pi/2;0.3]; u0 = 0.4; validateFcns(nlobj, x0, u0, [], {Ts});

Model.StateFcn is OK. Model.OutputFcn is OK. Analysis of user-provided model, cost, and constraint functions complete.

Create a nonlinear MPC controller with three states, one output, and four inputs. The first two inputs are measured disturbances, the third input is the manipulated variable, and the fourth input is an unmeasured disturbance.

nlobj = nlmpc(3,1,'MV',3,'MD',[1 2],'UD',4);

To view the controller state, output, and input dimensions and indices, use the `Dimensions`

property of the controller.

nlobj.Dimensions

`ans = `*struct with fields:*
NumberOfStates: 3
NumberOfOutputs: 1
NumberOfInputs: 4
MVIndex: 3
MDIndex: [1 2]
UDIndex: 4

Specify the controller sample time and horizons.

nlobj.Ts = 0.5; nlobj.PredictionHorizon = 6; nlobj.ControlHorizon = 3;

Specify the prediction model state function, which is in the file `exocstrStateFcnCT.m`

.

`nlobj.Model.StateFcn = 'exocstrStateFcnCT';`

Specify the prediction model output function, which is in the file `exocstrOutputFcn.m`

.

`nlobj.Model.OutputFcn = 'exocstrOutputFcn';`

Validate the prediction model functions using the initial operating point as the nominal condition for testing and setting the unmeasured disturbance state, `x0(3)`

, to `0`

. Since the model has measured disturbances, you must pass them to `validateFcns`

.

x0 = [311.2639; 8.5698; 0]; u0 = [10; 298.15; 298.15]; validateFcns(nlobj,x0,u0(3),u0(1:2)');

Model.StateFcn is OK. Model.OutputFcn is OK. Analysis of user-provided model, cost, and constraint functions complete.

Create nonlinear MPC controller with six states, six outputs, and four inputs.

nx = 6; ny = 6; nu = 4; nlobj = nlmpc(nx,ny,nu);

In standard cost function, zero weights are applied by default to one or more OVs because there are fewer MVs than OVs.

Specify the controller sample time and horizons.

Ts = 0.4; p = 30; c = 4; nlobj.Ts = Ts; nlobj.PredictionHorizon = p; nlobj.ControlHorizon = c;

Specify the prediction model state function and the Jacobian of the state function. For this example, use a model of a flying robot.

nlobj.Model.StateFcn = "FlyingRobotStateFcn"; nlobj.Jacobian.StateFcn = "FlyingRobotStateJacobianFcn";

Specify a custom cost function for the controller that replaces the standard cost function.

nlobj.Optimization.CustomCostFcn = @(X,U,e,data) Ts*sum(sum(U(1:p,:))); nlobj.Optimization.ReplaceStandardCost = true;

Specify a custom constraint function for the controller.

nlobj.Optimization.CustomEqConFcn = @(X,U,data) X(end,:)';

Validate the prediction model and custom functions at the initial states (`x0`

) and initial inputs (`u0`

) of the robot.

x0 = [-10;-10;pi/2;0;0;0]; u0 = zeros(nu,1); validateFcns(nlobj,x0,u0);

Model.StateFcn is OK. Jacobian.StateFcn is OK. No output function specified. Assuming "y = x" in the prediction model. Optimization.CustomCostFcn is OK. Optimization.CustomEqConFcn is OK. Analysis of user-provided model, cost, and constraint functions complete.

Create a nonlinear MPC controller with four states, one output variable, one manipulated variable, and one measured disturbance.

nlobj = nlmpc(4,1,'MV',1,'MD',2);

Specify the controller sample time and horizons.

nlobj.PredictionHorizon = 10; nlobj.ControlHorizon = 3;

Specify the state function of the prediction model.

`nlobj.Model.StateFcn = 'oxidationStateFcn';`

Specify the prediction model output function and the output variable scale factor.

nlobj.Model.OutputFcn = @(x,u) x(3); nlobj.OutputVariables.ScaleFactor = 0.03;

Specify the manipulated variable constraints and scale factor.

nlobj.ManipulatedVariables.Min = 0.0704; nlobj.ManipulatedVariables.Max = 0.7042; nlobj.ManipulatedVariables.ScaleFactor = 0.6;

Specify the measured disturbance scale factor.

nlobj.MeasuredDisturbances.ScaleFactor = 0.5;

Compute the state and input operating conditions for three linear MPC controllers using the `fsolve`

function.

options = optimoptions('fsolve','Display','none'); uLow = [0.38 0.5]; xLow = fsolve(@(x) oxidationStateFcn(x,uLow),[1 0.3 0.03 1],options); uMedium = [0.24 0.5]; xMedium = fsolve(@(x) oxidationStateFcn(x,uMedium),[1 0.3 0.03 1],options); uHigh = [0.15 0.5]; xHigh = fsolve(@(x) oxidationStateFcn(x,uHigh),[1 0.3 0.03 1],options);

Create linear MPC controllers for each of these nominal conditions.

mpcobjLow = convertToMPC(nlobj,xLow,uLow); mpcobjMedium = convertToMPC(nlobj,xMedium,uMedium); mpcobjHigh = convertToMPC(nlobj,xHigh,uHigh);

You can also create multiple controllers using arrays of nominal conditions. The number of rows in the arrays specifies the number controllers to create. The linear controllers are returned as cell array of `mpc`

objects.

u = [uLow; uMedium; uHigh]; x = [xLow; xMedium; xHigh]; mpcobjs = convertToMPC(nlobj,x,u);

View the properties of the `mpcobjLow`

controller.

mpcobjLow

MPC object (created on 23-Feb-2021 13:19:55): --------------------------------------------- Sampling time: 1 (seconds) Prediction Horizon: 10 Control Horizon: 3 Plant Model: -------------- 1 manipulated variable(s) -->| 4 states | | |--> 1 measured output(s) 1 measured disturbance(s) -->| 2 inputs | | |--> 0 unmeasured output(s) 0 unmeasured disturbance(s) -->| 1 outputs | -------------- Indices: (input vector) Manipulated variables: [1 ] Measured disturbances: [2 ] (output vector) Measured outputs: [1 ] Disturbance and Noise Models: Output disturbance model: default (type "getoutdist(mpcobjLow)" for details) Measurement noise model: default (unity gain after scaling) Weights: ManipulatedVariables: 0 ManipulatedVariablesRate: 0.1000 OutputVariables: 1 ECR: 100000 State Estimation: Default Kalman Filter (type "getEstimator(mpcobjLow)" for details) Constraints: 0.0704 <= u1 <= 0.7042, u1/rate is unconstrained, y1 is unconstrained

Create nonlinear MPC controller with six states, six outputs, and four inputs.

nx = 6; ny = 6; nu = 4; nlobj = nlmpc(nx,ny,nu);

In standard cost function, zero weights are applied by default to one or more OVs because there are fewer MVs than OVs.

Specify the controller sample time and horizons.

Ts = 0.4; p = 30; c = 4; nlobj.Ts = Ts; nlobj.PredictionHorizon = p; nlobj.ControlHorizon = c;

Specify the prediction model state function and the Jacobian of the state function. For this example, use a model of a flying robot.

nlobj.Model.StateFcn = "FlyingRobotStateFcn"; nlobj.Jacobian.StateFcn = "FlyingRobotStateJacobianFcn";

Specify a custom cost function for the controller that replaces the standard cost function.

nlobj.Optimization.CustomCostFcn = @(X,U,e,data) Ts*sum(sum(U(1:p,:))); nlobj.Optimization.ReplaceStandardCost = true;

Specify a custom constraint function for the controller.

nlobj.Optimization.CustomEqConFcn = @(X,U,data) X(end,:)';

Specify linear constraints on the manipulated variables.

for ct = 1:nu nlobj.MV(ct).Min = 0; nlobj.MV(ct).Max = 1; end

Validate the prediction model and custom functions at the initial states (`x0`

) and initial inputs (`u0`

) of the robot.

x0 = [-10;-10;pi/2;0;0;0]; u0 = zeros(nu,1); validateFcns(nlobj,x0,u0);

Model.StateFcn is OK. Jacobian.StateFcn is OK. No output function specified. Assuming "y = x" in the prediction model. Optimization.CustomCostFcn is OK. Optimization.CustomEqConFcn is OK. Analysis of user-provided model, cost, and constraint functions complete.

Compute the optimal state and manipulated variable trajectories, which are returned in the `info`

.

[~,~,info] = nlmpcmove(nlobj,x0,u0);

Slack variable unused or zero-weighted in your custom cost function. All constraints will be hard.

Plot the optimal trajectories.

FlyingRobotPlotPlanning(info)

Optimal fuel consumption = 4.712383

Create a nonlinear MPC controller with four states, two outputs, and one input.

nlobj = nlmpc(4,2,1);

Specify the sample time and horizons of the controller.

Ts = 0.1; nlobj.Ts = Ts; nlobj.PredictionHorizon = 10; nlobj.ControlHorizon = 5;

Specify the state function for the controller, which is in the file `pendulumDT0.m`

. This discrete-time model integrates the continuous time model defined in `pendulumCT0.m`

using a multistep forward Euler method.

```
nlobj.Model.StateFcn = "pendulumDT0";
nlobj.Model.IsContinuousTime = false;
```

The prediction model uses an optional parameter, `Ts`

, to represent the sample time. Specify the number of parameters.

nlobj.Model.NumberOfParameters = 1;

Specify the output function of the model, passing the sample time parameter as an input argument.

nlobj.Model.OutputFcn = @(x,u,Ts) [x(1); x(3)];

Define standard constraints for the controller.

nlobj.Weights.OutputVariables = [3 3]; nlobj.Weights.ManipulatedVariablesRate = 0.1; nlobj.OV(1).Min = -10; nlobj.OV(1).Max = 10; nlobj.MV.Min = -100; nlobj.MV.Max = 100;

Validate the prediction model functions.

x0 = [0.1;0.2;-pi/2;0.3]; u0 = 0.4; validateFcns(nlobj, x0, u0, [], {Ts});

Model.StateFcn is OK. Model.OutputFcn is OK. Analysis of user-provided model, cost, and constraint functions complete.

Only two of the plant states are measurable. Therefore, create an extended Kalman filter for estimating the four plant states. Its state transition function is defined in `pendulumStateFcn.m`

and its measurement function is defined in `pendulumMeasurementFcn.m`

.

EKF = extendedKalmanFilter(@pendulumStateFcn,@pendulumMeasurementFcn);

Define initial conditions for the simulation, initialize the extended Kalman filter state, and specify a zero initial manipulated variable value.

x = [0;0;-pi;0]; y = [x(1);x(3)]; EKF.State = x; mv = 0;

Specify the output reference value.

yref = [0 0];

Create an `nlmpcmoveopt`

object, and specify the sample time parameter.

nloptions = nlmpcmoveopt; nloptions.Parameters = {Ts};

Run the simulation for `10`

seconds. During each control interval:

Correct the previous prediction using the current measurement.

Compute optimal control moves using

`nlmpcmove`

. This function returns the computed optimal sequences in`nloptions`

. Passing the updated options object to`nlmpcmove`

in the next control interval provides initial guesses for the optimal sequences.Predict the model states.

Apply the first computed optimal control move to the plant, updating the plant states.

Generate sensor data with white noise.

Save the plant states.

Duration = 10; xHistory = x; for ct = 1:(Duration/Ts) % Correct previous prediction xk = correct(EKF,y); % Compute optimal control moves [mv,nloptions] = nlmpcmove(nlobj,xk,mv,yref,[],nloptions); % Predict prediction model states for the next iteration predict(EKF,[mv; Ts]); % Implement first optimal control move x = pendulumDT0(x,mv,Ts); % Generate sensor data y = x([1 3]) + randn(2,1)*0.01; % Save plant states xHistory = [xHistory x]; end

Plot the resulting state trajectories.

figure subplot(2,2,1) plot(0:Ts:Duration,xHistory(1,:)) xlabel('time') ylabel('z') title('cart position') subplot(2,2,2) plot(0:Ts:Duration,xHistory(2,:)) xlabel('time') ylabel('zdot') title('cart velocity') subplot(2,2,3) plot(0:Ts:Duration,xHistory(3,:)) xlabel('time') ylabel('theta') title('pendulum angle') subplot(2,2,4) plot(0:Ts:Duration,xHistory(4,:)) xlabel('time') ylabel('thetadot') title('pendulum velocity')

- Trajectory Optimization and Control of Flying Robot Using Nonlinear MPC
- Nonlinear Model Predictive Control of an Exothermic Chemical Reactor
- Swing-up Control of a Pendulum Using Nonlinear Model Predictive Control
- Nonlinear and Gain-Scheduled MPC Control of an Ethylene Oxidation Plant
- Plan and Execute Task- and Joint-Space Trajectories Using KINOVA Gen3 Manipulator (Robotics System Toolbox)
- Nonlinear MPC

You have a modified version of this example. Do you want to open this example with your edits?

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)