# nlmpcmoveopt

Option set for `nlmpcmove`

function

## Description

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.

## Creation

### Syntax

### Description

creates a default set
of options for the `options`

= nlmpcmoveopt`nlmpcmove`

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

## Properties

`OutputWeights`

— Output variable tuning weights

`[]`

(default) | row vector | matrix

Output 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

*N*is the number of output variables.

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

*p*rows. Here,

*k*is the current time and

*p*is the prediction horizon. Each row contains the output variable tuning weights for one prediction horizon step. If you specify fewer than

*p*rows, the weights in the final row are used for the remaining steps of the prediction horizon.

`MVWeights`

— Manipulated variable tuning weights

`[]`

(default) | row vector | matrix

Manipulated 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

*N*is the number of manipulated variables.

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

*p*rows. Here,

*k*is the current time and

*p*is the prediction horizon. Each row contains the manipulated variable tuning weights for one prediction horizon step. If you specify fewer than

*p*rows, the weights in the final row are used for the remaining steps of the prediction horizon.

`MVRateWeights`

— Manipulated variable rate tuning weights

`[]`

(default) | row vector | matrix

Manipulated 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

*N*is the number of manipulated variables.

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

*p*rows. Here,

*k*is the current time and

*p*is the prediction horizon. Each row contains the manipulated variable rate tuning weights for one prediction horizon step. If you specify fewer than

*p*rows, the weights in the final row are used for the remaining steps of the prediction horizon.

`ECR Weight`

— Slack variable tuning weight

`[]`

(default) | positive scalar

Slack 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 | matrix

Output variable lower bounds, specified as a row vector of length
*N _{y}* or a matrix with

*N*columns, where

_{y}*N*is the number of output variables.

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

Output variable upper bounds, specified as a row vector of length
*N _{y}* or a matrix with

*N*columns, where

_{y}*N*is the number of output variables.

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

Manipulated variable lower bounds, specified as a row vector of length
*N _{mv}* or a matrix with

*N*columns, where

_{mv}*N*is the number of manipulated variables.

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

Manipulated variable upper bounds, specified as a row vector of length
*N _{mv}* or a matrix with

*N*columns, where

_{mv}*N*is the number of manipulated variables.

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

Manipulated variable rate lower bounds, specified as a row vector of length
*N _{mv}* or a matrix with

*N*columns, where

_{mv}*N*is the number of manipulated variables.

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

Manipulated variable rate upper bounds, specified as a row vector of length
*N _{mv}* or a matrix with

*N*columns, where

_{mv}*N*is the number of manipulated variables.

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

State lower bounds, specified as a row vector of length
*N _{x}* or a matrix with

*N*columns, where

_{x}*N*is the number of states.

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

State upper bounds, specified as a row vector of length
*N _{x}* or a matrix with

*N*columns, where

_{x}*N*is the number of states.

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

Manipulated variable targets, specified as a row vector of length
*N _{mv}* or a matrix with

*N*columns, where

_{mv}*N*is the number of manipulated variables.

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

Parameter 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 | matrix

Initial guesses for the optimal state solutions, specified as a row vector of length
*N _{x}* or a matrix with

*N*columns, where

_{x}*N*is the number of states.

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

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

*N*columns, where

_{mv}*N*is the number of manipulated variables.

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

## Object Functions

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

## Examples

### Specify Run-Time Parameters for Nonlinear MPC

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.

## Version History

**Introduced in R2018b**

## Open Example

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

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