# nlmpcMultistage

## Description

A multistage nonlinear model predictive controller computes optimal control moves
across the prediction horizon *p* using a nonlinear prediction model. Stages
include the current time *k* and all prediction steps (from
*k*+1 to *k*+*p*). You can specify
different cost and constraint functions for each stage. These functions rely only on plant
information such as states and inputs available at that stage. For more information on
nonlinear MPC, see Nonlinear MPC.

## Creation

### Syntax

### Description

### Input Arguments

`p`

— Prediction horizon

positive integer

Prediction horizon number of steps, specified as a positive integer. This syntax
sets the read-only property `PredictionHorizon`

equal to the input
argument `p`

. Since this property is read-only, you cannot change
it after creating the controller object. Note that `p`

also
determines the number of stages (`p`

+1).

`nx`

— Number of prediction model states

positive 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.

`nu`

— Number of prediction model inputs

positive 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 indices

vector of positive integers

Manipulated variable indices, specified as a vector of positive integers. You
cannot change these indices after creating the controller object. This value is stored
in the `Dimensions.MVIndex`

controller property.

The combined set of indices from `mvIndex`

,
`mdIndex`

, and `udIndex`

must contain all
integers from `1`

through
*N _{u}*, where

*N*is the number of prediction model inputs.

_{u}`mdIndex`

— Measured disturbance indices

vector of positive integers

Measured disturbance indices, specified as a vector of positive integers. You
cannot change these indices after creating the controller object. This value is stored
in the `Dimensions.MDIndex`

controller property.

The combined set of indices from `mvIndex`

,
`mdIndex`

, and `udIndex`

must contain all
integers from `1`

through
*N _{u}*, where

*N*is the number of prediction model inputs.

_{u}`udIndex`

— Unmeasured disturbance indices

vector of positive integers

Unmeasured disturbance indices, specified as a vector of positive integers. You
cannot change these indices after creating the controller object. This value is stored
in the `Dimensions.UDIndex`

controller property.

The combined set of indices from `mvIndex`

,
`mdIndex`

, and `udIndex`

must contain all
integers from `1`

through
*N _{u}*, where

*N*is the number of prediction model inputs.

_{u}## Properties

`Ts`

— Prediction model sample time

`1`

(default) | positive finite scalar

Prediction model sample time, specified as a positive finite scalar. The controller
uses a discrete-time model with a sample time of `Ts`

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

is `true`

), then the
controller discretizes the model using a sample time of `Ts`

to
predict the trajectory. The default solver based on `fmincon`

uses an
implicit trapezoidal rule while the C/GMRES solver uses an implicit Euler method.

`PredictionHorizon`

— Prediction horizon

positive integer

This property is read-only.

Prediction horizon steps, specified as a read-only positive integer. The product of
`PredictionHorizon`

and `Ts`

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

`UseMVRate`

— MV rate used in MPC problem

`false`

(default) | `true`

Flag indicating whether the rate of change of the manipulated variables is used as a
decision variable in the problem formulation, specified as a logical value. Set
`UseMVRate`

to `true`

if:

You need to specify hard upper or lower bounds on the MV rate.

The MV rate appears as a term in a cost or constraint function at any stage.

You need to implement block moves (which you can do so by setting the

`RateMin`

and`RateMax`

bounds at the corresponding stages to zero).

By default, the value is `false`

, which means that the
rate of change of the manipulated variables does not explicitly appear in the
formulation of your MPC problem.

`Dimensions`

— Prediction model dimensional information

structure

This property is read-only.

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

`NumberOfStates`

— Number of states

positive integer

This property is read-only.

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

.

`NumberOfInputs`

— Number of inputs

positive integer

This property is read-only.

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

or the sum of the lengths
of `mvIndex`

, `mdIndex`

, and
`udIndex`

.

`MVIndex`

— Manipulated variable indices

vector of positive integers

This property is read-only.

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

.

`MDIndex`

— Measured disturbance indices

vector of positive integers

This property is read-only.

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

.

`UDIndex`

— Unmeasured disturbance indices

vector of positive integers

This property is read-only.

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

.

`Model`

— Prediction model

structure

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

`StateFcn`

— State function

string | 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 when the solver is set
to `fmincon`

, or the Euler method when the solver is set to
`cgmres`

. Note that the implicit trapezoidal rule can handle
moderately stiff models, but 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, instead of using a continuous-time prediction model, 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 local function, or a function defined in the current working folder or on the MATLAB path:

Model.StateFcn = @myStateFunction;

For more information on local functions, see Local Functions.

**Note**

Only functions defined in a separate file in the current folder or on the MATLAB path are supported for C/C++ code generation. Therefore, specifying state, cost, or constraint functions (or their Jacobians) as local functions is not recommended.

The state function must have the following input and outputs.

if Model.ParameterLength>0 out = myStateFunction(x,u,pm); else out = myStateFunction(x,u); end

Here, `x`

is the state vector, `u`

is the
input vector, and `pm`

is the model parameter vector. If
`IsContinuousTime`

is true then `out`

must
be the value of the state derivative with respect to time, otherwise it must be
the value of the state in the following time interval.

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

`StateJacFcn`

— State Jacobian function

`[]`

(default) | string | character vector | function handle

State Jacobian function, specified as a string, character vector, or function handle. As a best practice, 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 compute the Jacobian numerically for each optimization step.

**Note**

You can automatically generate a Jacobian function using `generateJacobianFunction`

.

You can specify your state Jacobian 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.StateJacFcn = "myStateJacFunction";`

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

Model.StateJacFcn = @myStateJacFunction;

For more information on local functions, see Local Functions.

**Note**

Only functions defined in a separate file in the current folder or on the MATLAB path are supported for C/C++ code generation. Therefore, specifying state, cost, or constraint functions (or their Jacobians) as local functions is not recommended.

The state Jacobian function must have the following input and outputs.

if Model.ParameterLength>0 [A,Bmv] = myStateJacFunction(x,u,pm); else [A,Bmv] = myStateJacFunction(x,u); end

Here, `x`

is the state vector, `u`

is the
input vector, and `pm`

is the model parameter vector.
`A`

is the Jacobian of the state function (either continuous or
discrete time) with respect to the state vector and `B`

is the
Jacobian of the state function with respect to the manipulated variable vector.
`A`

is a square matrix with
*N _{x}* rows and columns, where

*N*is the number of states (

_{x}`Dimensions.NumberOfStates`

). `Bmv`

must
have *N*rows and

_{x}*N*columns, where

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

_{mv}For more information, see Specify Prediction Model for Nonlinear MPC.

`IsContinuousTime`

— Flag indicating prediction model time domain

`true`

(default) | `false`

Flag indicating the 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**

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.

`ParameterLength`

— Length of the parameter vector

`0`

(default) | nonnegative integer

Length of the parameter vector used by the prediction model, specified as a nonnegative integer. If the model state function or its Jacobian require external parameters, set this value to the number of scalar parameters needed. At runtime you must then provide a numeric parameter vector, across the whole prediction horizon, to the controller.

`TerminalState`

— Terminal state

`[]`

(default) | vector

Terminal state, specified as a column vector with as many elements as the
number of states. The terminal state is the desired state at the last prediction
step. If any states in the vector do not have terminal values, specify
`inf`

at the corresponding locations to leave their terminal
values free.

The default value of this property is `[]`

, meaning that no
terminal state constraint is enforced.

`States`

— State information and bounds

structure array

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

*N*is the number of states. Each structure element has the following fields.

_{x}`Min`

— State hard lower bound

`-Inf`

(default) | scalar | vector

State hard lower bound, specified as a scalar or vector. By default, this
lower bound is `-Inf`

.

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. Use stage inequality constraints to implement soft bounds (see Stages).

`Max`

— State hard upper bound

`Inf`

(default) | scalar | vector

State hard upper bound, specified as a scalar or vector. By default, this
upper bound is `Inf`

.

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. Use stage inequality constraints to implement soft bounds (see Stages).

`Name`

— State name

string | 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 vector

State units, specified as a string or character vector.

`ManipulatedVariables`

— Manipulated variable information and hard bounds

structure array

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

*N*is the number of manipulated variables. To access this property, you can use the alias

_{mv}`MV`

instead
of `ManipulatedVariables`

.Each structure element has the following fields.

`Min`

— MV hard lower bound

`-Inf`

(default) | scalar | vector

MV hard lower bound, specified as a scalar or vector. By default, this lower
bound is `-Inf`

.

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.

MV bounds are always hard constraints. Use stage inequality constraints to implement soft bounds (see Stages).

`Max`

— MV hard upper bound

`Inf`

(default) | scalar | vector

MV hard upper bound, specified as a scalar or vector. By default, this upper
bound is `+Inf`

.

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.

MV bounds are always hard constraints. Use stage inequality constraints to implement soft bounds (see Stages).

`RateMin`

— MV rate of change hard lower bound

`-Inf`

(default) | nonpositive scalar | vector

MV rate of change hard lower bound, specified as a nonpositive scalar or
vector. The MV rate of change at stage *i* is defined as
*MV*(*i*) -
*MV*(*i*–1). By default, this lower bound is
`-Inf`

. If UseMVRate is `false`

this value is ignored.

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.

MV rate bounds are always hard constraints. Use stage inequality constraints to implement soft bounds (see Stages).

`RateMax`

— MV rate of change hard upper bound

`Inf`

(default) | nonnegative scalar | vector

MV rate of change hard upper bound, specified as a nonnegative scalar or
vector. The MV rate of change at stage *i* is defined as
*MV*(*i*) -
*MV*(*i*–1). By default, this upper bound is
`+Inf`

.

To use the same bound across the prediction horizon, specify a scalar value.
If UseMVRate is `false`

this value is ignored.

*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.

MV Rate bounds are always hard constraints. Use stage inequality constraint to implement soft bounds (see Stages).

`Name`

— MV name

string | 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 vector

MV units, specified as a string or character vector.

`MeasuredDisturbances`

— Measured disturbance information

structure array

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

*N*is the number of measured disturbances. If your model does not have measured disturbances, then

_{md}`MeasuredDisturbances`

is `[]`

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

instead of
`MeasuredDisturbances`

.Each structure element has the following fields.

`Name`

— MD name

string | 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 vector

MD units, specified as a string or character vector.

`Stages`

— Stage cost and constraint functions

structure

Stage cost and constraint functions, specified as an array of `p+1`

structures (where `p`

is the prediction horizon), each one with the
following fields.

`CostFcn`

— Cost function at stage `i`

string | character vector | function handle

Cost function at stage `i`

(where `i`

ranges
from `1`

to `p+1`

), specified as a string,
character vector, or function handle. The overall cost function of the nonlinear
MPC problem is the sum of the cost functions at each stage.

You can specify your stage cost 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

`Stages(i).CostFcn = 'myCostFunction';`

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

Stages(i).CostFcn = @myCostFunction;

For more information on local functions, see Local Functions.

**Note**

Only functions defined in a separate file in the current folder or on the MATLAB path are supported for C/C++ code generation. Therefore, specifying state, cost, or constraint functions (or their Jacobians) as local functions is not recommended.

In the most general case in which UseMVRate is `true`

, and both
`Stages(i).ParameterLength`

and
`Stages(i).SlackVariableLength`

are greater than
`0`

, the cost function must have the following inputs and
outputs.

Ji = myCostFunction(i,x,u,dmv,e,pv);

Here:

`Ji`

is a double scalar expressing the cost for stage`i`

.`i`

is the stage number from`1`

(current control interval) to`p+1`

(end of the prediction horizon).`x`

is the state vector.`u`

is the input vector.`dmv`

is the manipulated variable rate vector (change with respect to previous control interval).`e`

is the stage slack variable vector.`pv`

is the stage parameter vector.

If `UseMVRate`

is `false`

, omit the
`dmv`

input.

If `Stages(i).SlackVariableLength`

is `0`

,
omit the `e`

input.

If `Stages(i).ParameterLength`

is `0`

,
omit the `pv`

input.

In summary:

if UseMVRate is true if Stages(i).SlackVariableLength>0 if Stages(i).ParameterLength>0 Ji = myCostFunction(i,x,u,dmv,e,pv); else Ji = myCostFunction(i,x,u,dmv,e); end else if Stages(i).ParameterLength>0 Ji = myCostFunction(i,x,u,dmv,pv); else Ji = myCostFunction(i,x,u,dmv); end end else if Stages(i).SlackVariableLength>0 if Stages(i).ParameterLength>0 Ji = myCostFunction(i,x,u,e,pv); else Ji = myCostFunction(i,x,u,e); end else if Stages(i).ParameterLength>0 Ji = myCostFunction(i,x,u,pv); else Ji = myCostFunction(i,x,u); end end end

Note that you can also write separate functions for separate stages as long as
their name is specified in ` Stages(i).CostFcn`

and all
functions have the required number of inputs and outputs, in the required
order.

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

`CostJacFcn`

— Gradient of the cost function at stage `i`

string | character vector | function handle

Gradient of the cost function at stage `i`

(where
`i`

ranges from `1`

to
`p+1`

), specified as a string, character vector, or function
handle. It is best practice to use Jacobians (in this case, gradients) 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 at each optimization step.

**Note**

You can automatically generate a Jacobian function using `generateJacobianFunction`

.

You can specify your stage cost Jacobian 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

`Stages(i).CostJacFcn = 'myCostJacFunction';`

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

Stages(i).CostJacFcn = @myCostJacFunction;

For more information on local functions, see Local Functions.

**Note**

In the most general case in which UseMVRate is `true`

, and both
`Stages(i).ParameterLength`

and
`Stages(i).SlackVariableLength`

are greater than
`0`

, the stage cost gradient function must have the following
inputs and outputs.

[Gx,Gmv,Gdmv,Ge] = myCostJacFunction(i,x,u,dmv,e,pv);

where

`Gx`

is the gradient of cost function for stage`i`

with respect to the state vector`x`

. It must be a column vector with*N*elements, where_{x}*N*is the number of states._{x}`Gmv`

is the gradient of the cost function for stage`i`

with respect to the manipulated variable vector`mv`

. It must be a column vector with*N*elements, where_{mv}*N*is the number of manipulated variables._{mv}`Gdmv`

is the gradient of the cost function for stage`i`

with respect to the manipulated variable vector change`dmv`

. It must be a column vector with*N*elements, where_{mv}*N*is the number of manipulated variables._{mv}`Ge`

is the gradient of the cost function for stage`i`

with respect to the stage slack variable vector`e`

. It must be a column vector with*N*elements, where_{e}*N*is the number of stage slack variables._{e}`i`

is the stage number from`1`

(current control interval) to`p+1`

(end of the prediction horizon).`x`

is the state vector.`u`

is the input vector.`dmv`

is the manipulated variable rate vector (change with respect to the previous control interval).`e`

is the stage slack variable vector.`pv`

is the stage parameter vector.

If `UseMVRate`

is `false`

, omit the
`dmv`

input and the `Gdmv`

output.

If `Stages(i).SlackVariableLength`

is `0`

,
omit the `e`

input and the `Ge`

output.

If `Stages(i).ParameterLength`

is `0`

,
omit the `pv`

input.

In summary:

if UseMVRate is true if Stages(i).SlackVariableLength>0 if Stages(i).ParameterLength>0 [Gx,Gmv,Gdmv,Ge] = myCostJacFunction(i,x,u,dmv,e,pv); else [Gx,Gmv,Gdmv,Ge] = myCostJacFunction(i,x,u,dmv,e); end else if Stages(i).ParameterLength>0 [Gx,Gmv,Gdmv] = myCostJacFunction(i,x,u,dmv,pv); else [Gx,Gmv,Gdmv] = myCostJacFunction(i,x,u,dmv); end end else if Stages(i).SlackVariableLength>0 if Stages(i).ParameterLength>0 [Gx,Gmv,Ge] = myCostJacFunction(i,x,u,e,pv); else [Gx,Gmv,Ge] = myCostJacFunction(i,x,u,e); end else if Stages(i).ParameterLength>0 [Gx,Gmv] = myCostJacFunction(i,x,u,pv); else [Gx,Gmv] = myCostJacFunction(i,x,u); end end end

Note that you can also write separate functions for separate stages as long as
their name is specified in ` Stages(i).CostJacFcn`

and all
functions have the required number of inputs and outputs, in the required
order.

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

`EqConFcn`

— Equality constraint function at stage `i`

string | character vector | function handle

Equality constraint function at stage `i`

(where
`i`

ranges from `1`

to `p`

),
specified as a string, character vector, or function handle. Note that specifying
an equality constraint for the last stage (`p`

+1) is not
supported. Use the `TerminalState`

field of the
`Model`

property instead.

You can specify your stage equality constraint function in one of the following ways:

`Stages(i).EqConFcn = 'myEqConFunction';`

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

Stages(i).EqConFcn = @myEqConFunction;

For more information on local functions, see Local Functions.

**Note**

In the most general case in which UseMVRate is `true`

, and
`Stages(i).ParameterLength`

is greater than
`0`

, the equality constraint function must have the following
inputs and outputs.

Ceq = myEqConFunction(i,x,u,dmv,pv);

where

`Ceq`

is a vector expressing the equality constraints for stage`i`

. At any feasible solution of the MPC problem the returned`Ceq`

must be equal to`0`

. Note that the number of elements in`Ceq`

must be less than the number of manipulated variables otherwise the problem is overspecified and generally infeasible.`i`

is the stage number from`1`

(current control interval) to`p+1`

(end of the prediction horizon).`x`

is the state vector.`u`

is the input vector.`dmv`

is the manipulated variable rate vector (change with respect to previous control interval).`pv`

is the stage parameter vector.

If `UseMVRate`

is `false`

, omit the
`dmv`

input.

If `Stages(i).ParameterLength`

is `0`

,
omit the `pv`

input.

In summary:

if UseMVRate is true if Stages(i).ParameterLength>0 Ceq = myEqConFunction(i,x,u,dmv,pv); else Ceq = myEqConFunction(i,x,u,dmv); end else if Stages(i).ParameterLength>0 Ceq = myEqConFunction(i,x,u,pv); else Ceq = myEqConFunction(i,x,u); end end

Note that you can also write separate functions for separate stages as long as
their name is specified in ` Stages(i).EqConFcn`

and all
functions have the required number of inputs and outputs, in the required
order.

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

`EqConJacFcn`

— Jacobian of equality constraint function at stage `i`

string | character vector | function handle

Jacobian of the equality constraint function at stage `i`

(where `i`

ranges from `1`

to
`p`

), specified as a string, character vector, or function
handle. Note that specifying an equality constraint (and hence its Jacobian
function) for the last stage (`p`

+1) is not supported.

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.

You can specify your stage equality constraint Jacobian function in one of the following ways:

`Stages(i).EqConJacFcn = 'myEqConJacFunction';`

Stages(i).EqConJacFcn = @myEqConJacFunction;

For more information on local functions, see Local Functions.

**Note**

In the most general case in which UseMVRate is `true`

, and
`Stages(i).ParameterLength`

is greater than
`0`

, the equality constraint Jacobian function must have the
following inputs and outputs.

[Ceqx,Ceqmv,Ceqdmv] = myEqConJacFunction(i,x,u,dmv,pv);

where

`Ceqx`

is the Jacobian of the equality constraint function for stage`i`

, with respect to the state vector`x`

. It must be a matrix with*N*rows and_{Ceq}*N*columns, where_{x}*N*is the number of stage equality constraints and_{Ceq}*N*the number of states. Note that_{x}*N*has to be less than_{Ceq}*N*otherwise the problem is overdetermined and generally infeasible._{Cmv}`Ceqmv`

is the Jacobian of the equality constraint function for stage`i`

, with respect to the manipulated variable vector`mv`

. It must be a matrix with*N*rows and_{Ceq}*N*columns, where_{mv}*N*is the number of stage equality constraints and_{Ceq}*N*the number of manipulated variables._{mv}`Ceqdmv`

is the Jacobian of the equality constraint function for stage`i`

, with respect to the manipulated variable vector change (rate)`dmv`

. It must be a matrix with*N*rows and_{Ceq}*N*columns, where_{mv}*N*is the number of stage equality constraints and_{Ceq}*N*the number of manipulated variables._{mv}`i`

is the stage number from`1`

(current control interval) to`p+1`

(end of the prediction horizon).`x`

is the state vector.`u`

is the input vector.`dmv`

is the manipulated variable rate vector (change with respect to previous control interval).`pv`

is the stage parameter vector.

If `UseMVRate`

is `false`

, omit the
`dmv`

input and the `Ceqdmv`

output.

If `Stages(i).ParameterLength`

is `0`

,
omit the `pv`

input.

In summary

if UseMVRate is true if Stages(i).ParameterLength>0 [Ceqx,Ceqmv,Ceqdmv] = myEqConJacFunction(i,x,u,dmv,pv); else [Ceqx,Ceqmv,Ceqdmv] = myEqConJacFunction(i,x,u,dmv); end else if Stages(i).ParameterLength>0 [Ceqx,Ceqmv] = myEqConJacFunction(i,x,u,pv); else [Ceqx,Ceqmv] = myEqConJacFunction(i,x,u); end end

Note that you can also write separate functions for separate stages as long as
their name is specified in ` Stages(i).EqConJacFcn`

and all
functions have the required number of inputs and outputs, in the required
order.

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

`IneqConFcn`

— Inequality constraint function at stage `i`

string | character vector | function handle

Inequality constraint function at stage `i`

(where
`i`

ranges from `1`

to
`p+1`

), specified as a string, character vector, or function
handle.

You can specify your stage inequality constraint function in one of the following ways:

`Stages(i).IneqConFcn = 'myIneqConFunction';`

Stages(i).IneqConFcn = @myIneqConFunction;

For more information on local functions, see Local Functions.

**Note**

In the most general case in which `UseMVRate`

is `true`

, and both
`Stages(i).ParameterLength`

and
`Stages(i).SlackVariableLength`

are greater than
`0`

, the inequality constraint function must have the following
inputs and outputs.

C = myIneqConFunction(i,x,u,dmv,e,pv);

Here:

`C`

is a vector expressing the inequality constraints for stage`i`

. For any feasible solution of the MPC problem,`C`

must be non-positive.`i`

is the stage number from`1`

(current control interval) to`p+1`

(end of the prediction horizon).`x`

is the state vector.`u`

is the input vector.`dmv`

is the manipulated variable rate vector (change with respect to previous control interval).`e`

is the stage slack variable vector.`pv`

is the stage parameter vector.

If `UseMVRate`

is `false`

, omit the
`dmv`

input.

If `Stages(i).SlackVariableLength`

is
`0`

, omit the `e`

input.

If `Stages(i).ParameterLength`

is `0`

,
omit the `pv`

input.

In summary:

if UseMVRate is true if Stages(i).SlackVariableLength>0 if Stages(i).ParameterLength>0 C = myIneqConFunction(i,x,u,dmv,e,pv); else C = myIneqConFunction(i,x,u,dmv,e); end else if Stages(i).ParameterLength>0 C = myIneqConFunction(i,x,u,dmv,pv); else C = myIneqConFunction(i,x,u,dmv); end end else if Stages(i).SlackVariableLength>0 if Stages(i).ParameterLength>0 C = myIneqConFunction(i,x,u,e,pv); else C = myIneqConFunction(i,x,u,e); end else if Stages(i).ParameterLength>0 C = myIneqConFunction(i,x,u,pv); else C = myIneqConFunction(i,x,u); end end end

Note that you can also write separate functions for separate stages as long as
their name is specified in `Stages(i).IneqConFcn`

and that all
functions have the required number of inputs and outputs, in the required
order.

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

`IneqConJacFcn`

— Jacobian of the inequality constraint function at stage `i`

string | character vector | function handle

Jacobian of the inequality constraint function at stage `i`

(where `i`

ranges from `1`

to
`p+1`

), specified as a string, character vector, or function
handle. 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.

You can specify your stage constraint Jacobian function in one of the following ways:

`Stages(i).IneqConJacFcn = 'myIneqConJacFunction';`

Stages(i).IneqConJacFcn = @myIneqConJacFunction;

For more information on local functions, see Local Functions.

**Note**

In the most general case in which UseMVRate is `true`

, and both
`Stages(i).ParameterLength`

and
`Stages(i).SlackVariableLength`

are greater than
`0`

, the stage cost Jacobian function must have the following
inputs and outputs.

[Cx,Cmv,Cdmv,Ce] = myEqConJacFunction(i,x,u,dmv,e,pv);

Here:

`Cx`

is the Jacobian of the inequality constraint function for stage`i`

, with respect to the state vector`x`

. It must be a matrix with*N*rows and_{C}*N*columns, where_{x}*N*is the number of stage inequality constraints and_{C}*N*the number of states._{x}`Cmv`

is the Jacobian of the inequality constraint function for stage`i`

, with respect to the manipulated variable vector`mv`

. It must be a matrix with*N*rows and_{C}*N*columns, where_{mv}*N*is the number of stage inequality constraints and_{C}*N*the number of manipulated variables._{mv}`Cdmv`

is the Jacobian of the inequality constraint function for stage`i`

, with respect to the manipulated variable change (rate)`dmv`

. It must be a matrix with*N*rows and_{C}*N*columns, where_{mv}*N*is the number of stage inequality constraints and_{C}*N*the number of manipulated variables._{mv}`Ce`

is the Jacobian of the inequality constraint function for stage`i`

, with respect to the stage slack variable vector`e`

. It must be a matrix with*N*rows and_{C}*N*columns, where_{e}*N*is the number of stage inequality constraints and_{C}*N*the number of stage slack variables._{e}`i`

is the stage number from`1`

(current control interval) to`p+1`

(end of the prediction horizon).`x`

is the state vector.`u`

is the input vector.`dmv`

is the manipulated variable rate vector (change with respect to previous control interval).`e`

is the stage slack variable vector.`pv`

is the stage parameter vector.

If `UseMVRate`

is `false`

, omit the
`dmv`

input and the `Cdmv`

output.

If `Stages(i).SlackVariableLength`

is `0`

,
omit the `e`

input and the `Ce`

output.

If `Stages(i).ParameterLength`

is `0`

,
omit the `pv`

input.

In summary:

if UseMVRate is true if Stages(i).SlackVariableLength>0 if Stages(i).ParameterLength>0 [Cx,Cmv,Cdmv,Ce] = myIneqConJacFunction(i,x,u,dmv,e,pv); else [Cx,Cmv,Cdmv,Ce] = myIneqConJacFunction(i,x,u,dmv,e); end else if Stages(i).ParameterLength>0 [Cx,Cmv,Cdmv] = myIneqConJacFunction(i,x,u,dmv,pv); else [Cx,Cmv,Cdmv] = myIneqConJacFunction(i,x,u,dmv); end end else if Stages(i).SlackVariableLength>0 if Stages(i).ParameterLength>0 [Cx,Cmv,Ce] = myIneqConJacFunction(i,x,u,e,pv); else [Cx,Cmv,Ce] = myIneqConJacFunction(i,x,u,e); end else if Stages(i).ParameterLength>0 [Cx,Cmv] = myIneqConJacFunction(i,x,u,pv); else [Cx,Cmv] = myIneqConJacFunction(i,x,u); end end end

Note that you can also write separate functions for separate stages as long as
their name is specified in` Stages(i).IneqConFcn`

and that all
functions have the required number of inputs and outputs, in the required
order.

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

`SlackVariableLength`

— Length of the stage slack variable vector

`0`

(default) | nonnegative integer

Length of the slack variable vector used by the cost and constraint functions
at stage `i`

, specified as a nonnegative integer. You can use
slack variables to implement soft constraints for a given stage, using the
corresponding `IneqConFcn`

and `CostFcn`

functions.

`ParameterLength`

— Length of the parameter vector

`0`

(default) | nonnegative integer

Length of the parameter vector used by the cost and constraint functions at
stage `i`

, specified as a nonnegative integer. If any stage uses
parameters, this value must be positive, and as a consequence all the stage
functions must have a parameter vector as their last input argument.

`Optimization`

— Custom optimization functions and solver

structure

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

`Solver`

— Solver

`'fmincon'`

(default) | `'cgmres'`

Solver function, specified as one of the following strings or character vectors:

`'fmincon'`

or`"fmincon"`

— The software uses the Optimization Toolbox™ function`fmincon`

to solve the multistage nonlinear MPC optimization problem at each time step.`'cgmres'`

or`"cgmres"`

— The software uses a Continuation / Generalized Minimum Residual (C/GMRES) method to solve the multistage nonlinear MPC problem at each time step. Use this solver for large-scale linear and nonlinear systems and for systems with relevant nonlinear constraints. Due to its computational efficiency, this solver is also generally suitable for implementation in real-time embedded systems.For an example on how to use the C/GMRES solver, see Control Robot Manipulator Using C/GMRES Solver.

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

`CustomSolverFcn`

— Custom nonlinear programming solver

`[]`

(default) | string | character vector | function handle

Custom nonlinear programming solver function, specified as a string, character vector, or function handle. 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 options

options object for `fmincon`

(default) | options object for C/GMRES solver | `[]`

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

, an options object for the C/GMRES solver, or
`[]`

.

If you have Optimization Toolbox software, by default `SolverOptions`

contains an
options object for the `fmincon`

solver.

If you do not have Optimization Toolbox, by default `SolverOptions`

is
`[]`

.

If you specify the `Optimization.Solver`

property of
`msobj`

as `"cgmres"`

,
`SolverOptions`

is an options object for the C/GMRES
solver.

For more information, see Configure Optimization Solver for 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`

.

`PerturbationRatio`

— Coefficient used to calculate perturbation sizes

`1e-6`

(default) | positive scalar

Coefficient used to calculate the perturbation sizes applied to the decision
variables when using forward finite differences to estimate derivatives. The
perturbation size vector for the decision variable vector `z`

is
`PerturbationRatio*max(abs(z),1)`

. The default value for this
parameter is `1e–6`

. If your prediction model is stiff and your
cost/constraint terms are sensitive, use a smaller value such as
`1e–8`

.

## Object Functions

`generateJacobianFunction` | Generate MATLAB Jacobian functions for multistage nonlinear MPC using automatic differentiation |

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

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

`getSimulationData` | Create data structure to simulate multistage MPC controller with
`nlmpcmove` |

## Examples

### Create Multistage Nonlinear MPC object

Create a multistage nonlinear MPC object with a prediction horizon of
`5`

steps, `2`

states, and `1`

manipulated variable.

msobj = nlmpcMultistage(5,2,1);

### Create Multistage Nonlinear MPC object with Measured Disturbance Inputs

Create a multistage nonlinear MPC object with a prediction horizon of
`5`

steps, `2`

states, and `2`

inputs, where the first input is a measured disturbance and the second is a manipulated
variable.

msobj = nlmpcMultistage(5,2,MV=2,MD=1);

### Create Multistage Nonlinear MPC object with Unmeasured Disturbance Inputs

Create a multistage nonlinear MPC object with a prediction horizon of
`5`

steps, `2`

states, and `2`

inputs, where the first input is a manipulated variable and the second is an unmeasured
disturbance.

msobj = nlmpcMultistage(5,2,MV=1,UD=2);

### Create Multistage Nonlinear MPC Object with Measured and Unmeasured Disturbance Inputs

Create a multistage nonlinear MPC object with a prediction horizon of
`6`

steps, `3`

states, and `4`

inputs, where the first two inputs are measured disturbances, the third is the manipulated
variable, and the fourth is an unmeasured disturbance.

msobj = nlmpcMultistage(6, 3, MV=3, MD=[1 2], UD=4);

Set a sampling time of `2`

seconds and display the
`msobj`

object

msobj.Ts = 2

msobj = nlmpcMultistage with properties: Ts: 2 PredictionHorizon: 6 UseMVRate: 0 Dimensions: [1×1 struct] Model: [1×1 struct] States: [1×3 struct] ManipulatedVariables: [1×1 struct] MeasuredDisturbances: [1×2 struct] Stages: [1×7 struct] Optimization: [1×1 struct]

## Version History

**Introduced in R2021a**

## See Also

### Functions

`generateJacobianFunction`

|`validateFcns`

|`nlmpcmove`

|`nlmpcmoveCodeGeneration`

|`getSimulationData`

|`getCodeGenerationData`

### Objects

### Blocks

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