Main Content

Option set for `nlmpcmove`

function

To specify options for the `nlmpcmove`

function,
use an `nlmpcmoveopt`

option set.

Using this option set, you can specify run-time values for a subset of controller
properties, such as tuning weights and constraints. If you do not specify a value for one of
the `nlmpcmoveopt`

properties, the corresponding value defined in the
`nlmpc`

controller
object is used instead.

creates a default set
of options for the `options`

= nlmpcmoveopt`nlmpcmove`

function. To modify the property values,
use dot notation.

`OutputWeights`

— Output variable tuning weights`[]`

(default) | row vector | matrixOutput variable tuning weights that replace the
`Weights.OutputVariables`

property of the controller at run time,
specified as a row vector or matrix of nonnegative values.

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

`MVWeights`

— Manipulated variable tuning weights`[]`

(default) | row vector | matrixManipulated variable tuning weights that replace the
`Weights.ManipulatedVariables`

property of the controller at run
time, specified as a row vector or matrix of nonnegative values.

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

`MVRateWeights`

— Manipulated variable rate tuning weights`[]`

(default) | row vector | matrixManipulated variable rate tuning weights that replace the
`Weights.ManipulatedVariablesRate`

property of the controller at run
time, specified as a row vector or matrix of nonnegative values.

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

`ECR Weight`

— Slack variable tuning weight`[]`

(default) | positive scalarSlack variable tuning weight that replaces the `Weights.ECR`

property of the controller at run time, specified as a positive scalar.

`OutputMin`

— Output variable lower bounds`[]`

(default) | row vector | matrixOutput variable lower bounds, specified as a row vector of length
*N _{y}* or a matrix with

`OutputMin(:,i)`

replaces the
`OutputVariables(i).Min`

property of the controller at run
time.To use the same bounds across the prediction horizon, specify a row vector.

To vary the bounds over the prediction horizon from time *k*+1 to
time *k*+*p*, specify a matrix with 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 final
bounds are used for the remaining steps of the prediction horizon.

`OutputMax`

— Output variable upper bounds`[]`

(default) | row vector | matrixOutput variable upper bounds, specified as a row vector of length
*N _{y}* or a matrix with

`OutputMax(:,i)`

replaces the
`OutputVariables(i).Max`

property of the controller at run
time.To use the same bounds across the prediction horizon, specify a row vector.

To vary the bounds over the prediction horizon from time *k*+1 to
time *k*+*p*, specify a matrix with 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 final
bounds are used for the remaining steps of the prediction horizon.

`MVMin`

— Manipulated variable lower bounds`[]`

(default) | row vector | matrixManipulated variable lower bounds, specified as a row vector of length
*N _{mv}* or a matrix with

`MVMin(:,i)`

replaces the
`ManipulatedVariables(i).Min`

property of the controller at run
time.To use the same bounds across the prediction horizon, specify a row vector.

To vary the bounds over the prediction horizon from time *k* to
time *k*+*p*-1, specify a matrix with 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 final
bounds are used for the remaining steps of the prediction horizon.

`MVMax`

— Manipulated variable upper bounds`[]`

(default) | row vector | matrixManipulated variable upper bounds, specified as a row vector of length
*N _{mv}* or a matrix with

`MVMax(:,i)`

replaces the
`ManipulatedVariables(i).Max`

property of the controller at run
time.To use the same bounds across the prediction horizon, specify a row vector.

To vary the bounds over the prediction horizon from time *k* to
time *k*+*p*-1, specify a matrix with 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 final
bounds are used for the remaining steps of the prediction horizon.

`MVRateMin`

— Manipulated variable rate lower bounds`[]`

(default) | row vector | matrixManipulated variable rate lower bounds, specified as a row vector of length
*N _{mv}* or a matrix with

`MVRateMin(:,i)`

replaces the
`ManipulatedVariables(i).RateMin`

property of the controller at run
time. `MVRateMin`

bounds must be nonpositive.To use the same bounds across the prediction horizon, specify a row vector.

To vary the bounds over the prediction horizon from time *k* to
time *k*+*p*-1, specify a matrix with 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 final
bounds are used for the remaining steps of the prediction horizon.

`MVRateMax`

— Manipulated variable rate upper bounds`[]`

(default) | row vector | matrixManipulated variable rate upper bounds, specified as a row vector of length
*N _{mv}* or a matrix with

`MVRateMax(:,i)`

replaces the
`ManipulatedVariables(i).RateMax`

property of the controller at run
time. `MVRateMax`

bounds must be nonnegative.To use the same bounds across the prediction horizon, specify a row vector.

*k* to
time *k*+*p*-1, specify a matrix with 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 final
bounds are used for the remaining steps of the prediction horizon.

`StateMin`

— State lower bounds`[]`

(default) | row vector | matrixState lower bounds, specified as a row vector of length
*N _{x}* or a matrix with

`StateMin(:,i)`

replaces the `States(i).Min`

property of the controller at run time.To use the same bounds across the prediction horizon, specify a row vector.

To vary the bounds over the prediction horizon from time *k*+1 to
time *k*+*p*, specify a matrix with 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 final
bounds are used for the remaining steps of the prediction horizon.

`StateMax`

— State upper bounds`[]`

(default) | row vector | matrixState upper bounds, specified as a row vector of length
*N _{x}* or a matrix with

`StateMax(:,i)`

replaces the `States(i).Max`

property of the controller at run time.To use the same bounds across the prediction horizon, specify a row vector.

*k*+1 to
time *k*+*p*, specify a matrix with 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 final
bounds are used for the remaining steps of the prediction horizon.

`MVTarget`

— Manipulated variable targets`[]`

(default) | row vector | matrixManipulated variable targets, specified as a row vector of length
*N _{mv}* or a matrix with

To use the same manipulated variable targets across the prediction horizon, specify a row vector.

To vary the targets over the prediction horizon (previewing) from time
*k* to time *k*+*p*-1, specify a
matrix with up to *p* rows. Here, *k* is the current
time and *p* is the prediction horizon. Each row contains the targets
for one prediction horizon step. If you specify fewer than *p* rows,
the final targets are used for the remaining steps of the prediction horizon.

`Parameters`

— Parameter values`{}`

(default) | cell vectorParameter values used by the prediction model, custom cost function, and custom
constraints, specified as a cell vector with length equal to the
`Model.NumberOfParameters`

property of the controller. If the
controller has no parameters, then `Parameters`

must be
`{}`

.

The controller, `nlmpcobj`

, passes these parameters to the:

Model functions in

`nlmpcobj.Model`

(`StateFcn`

and`OutputFcn`

)Cost function

`nlmpcobj.Optimization.CustomCostFcn`

Constraint functions in

`nlmpcobj.Optimization`

(`CustomEqConFcn`

and`CustomIneqConFcn`

)Jacobian functions in

`nlmpcobj.Jacobian`

The order of the parameters must match the order defined for these functions.

`X0`

— Initial guesses for the optimal state solutions`[]`

(default) | vector | matrixInitial guesses for the optimal state solutions, specified as a row vector of length
*N _{x}* or a matrix with

To use the same initial guesses across the prediction horizon, specify a row vector.

To vary the initial guesses over the prediction horizon from time
*k*+1 to time *k*+*p*, specify a
matrix with up to *p* rows. Here, *k* is the current
time and *p* is the prediction horizon. Each row contains the initial
guesses for one prediction horizon step. If you specify fewer than *p*
rows, the final guesses are used for the remaining steps of the prediction
horizon.

If `X0`

is `[]`

, the default initial guesses are
the current states of the prediction model (`x`

input argument to
`nlmpcmove`

).

In general, during closed-loop simulation, you do not specify
`X0`

yourself. Instead, when calling `nlmpcmove`

,
return the `opt`

output argument, which is an
`nlmpcmoveopt`

object. `opt.X0`

contains the
calculated optimal state trajectories as initial guesses. You can then pass
`opt`

in as the `options`

input argument to
`nlmpcmove`

for the next control interval. These steps are a best
practice, even if you do not specify any other run-time options.

`MV0`

— Initial guesses for the optimal manipulated variable solutions`[]`

(default) | vector | matrixInitial guesses for the optimal manipulated variable solutions, specified as a row
vector of length *N _{mv}* or a matrix with

To use the same initial guesses across the prediction horizon, specify a row vector.

To vary the initial guesses over the prediction horizon from time
*k* to time *k*+*p*-1, specify a
matrix with up to *p* rows. Here, *k* is the current
time and *p* is the prediction horizon. Each row contains the initial
guesses for one prediction horizon step. If you specify fewer than *p*
rows, the final guesses are used for the remaining steps of the prediction
horizon.

If `MV0`

is `[]`

, the default initial guesses
are the control signals used in the plant at the previous control interval
(`lastmv`

input argument to `nlmpcmove`

).

In general, during closed-loop simulation, you do not specify
`MV0`

yourself. Instead, when calling `nlmpcmove`

,
return the `opt`

output argument, which is an
`nlmpcmoveopt`

object. `opt.MV0`

contains the
calculated optimal manipulated variable trajectories as initial guesses. You can then
pass `opt`

in as the `options`

input argument to
`nlmpcmove`

for the next control interval. These steps are a best
practice, even if you do not specify any other run-time options.

`Slack0`

— Initial guess for the slack variable at the solution`[]`

(default) | nonnegative scalar Initial guess for the slack variable at the solution, specified as a nonnegative
scalar. If `Slack0`

is `[]`

, the default initial
guess is `0`

.

In general, during closed-loop simulation, you do not specify
`Slack0`

yourself. Instead, when calling `nlmpcmove`

,
return the `opt`

output argument, which is an
`nlmpcmoveopt`

object. `opt.Slack`

contains the
calculated slack variable as an initial guess. You can then pass `opt`

in as the `options`

input argument to `nlmpcmove`

for the next control interval. These steps are a best practice, even if you do not
specify any other run-time options.

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

Create a default `nlmpcmoveopt`

option set.

options = nlmpcmoveopt;

Specify the run-time values for the controller prediction model parameters. For this example, assume that the controller has the following optional parameters, which are input arguments to all the prediction model functions and custom functions of the controller.

Sample time of the model, specified as a single numeric value. Specify a value of

`0.25`

.Gain factors, specified as a two-element row vector. Specify a value of

`[0.7 0.35]`

.

The order in which you specify the parameters must match the order specified in the custom function argument lists. Also, the dimensions of the parameters must match the dimensions expected by the custom functions.

options.Parameters = {0.25,[0.7 0.35]};

To use these parameters when computing optional control actions for a nonlinear MPC controller, pass `options`

to the `nlmpcmove`

function.

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)