# nlmpcMultistage

Multistage Nonlinear model predictive controller

## Description

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

## Creation

### Syntax

``nlobj = nlmpcMultistage(p,nx,nu)``
``nlobj = nlmpcMultistage(p,nx,'MV',mvIndex,'MD',mdIndex)``
``nlobj = nlmpcMultistage(p,nx,'MV',mvIndex,'UD',udIndex)``
``nlobj = nlmpcMultistage(p,nx,'MV',mvIndex,'MD',mdIndex,'UD',udIndex)``

### Description

example

````nlobj = nlmpcMultistage(p,nx,nu)` creates an `nlmpcMultistage` object with a prediction horizon `p`, and whose prediction model has `nx` states, and `nu` inputs, and where all inputs are manipulated variables. Use this syntax if your model has no measured or unmeasured disturbance inputs.```

example

````nlobj = nlmpcMultistage(p,nx,'MV',mvIndex,'MD',mdIndex)` creates an `nlmpcMultistage` object whose prediction model has measured disturbance inputs. Specify the input indices for the manipulated variables, `mvIndex`, and measured disturbances, `mdIndex`.```

example

````nlobj = nlmpcMultistage(p,nx,'MV',mvIndex,'UD',udIndex)` creates an `nlmpcMultistage` object whose prediction model has unmeasured disturbance inputs. Specify the input indices for the manipulated variables, `mvIndex`, and unmeasured disturbances, `udIndex`.```

example

````nlobj = nlmpcMultistage(p,nx,'MV',mvIndex,'MD',mdIndex,'UD',udIndex)` creates an `nlmpcMultistage` object whose prediction model has both measured and unmeasured disturbance inputs. Specify the input indices for the manipulated variables, measured disturbances, and unmeasured disturbances.```

### Input Arguments

expand all

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

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.

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.

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 Nu, where Nu is the number of prediction model inputs.

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 Nu, where Nu is the number of prediction model inputs.

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 Nu, where Nu is the number of prediction model inputs.

## Properties

expand all

Prediction 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`.

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.

Flag indicating whether the rate of change of the manipulated variables is used as a decision variable in the problem formulation. 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.

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

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

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

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

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

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

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

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 local function, or a function defined in the current working folder or on the MATLAB path

`Model.StateFcn = @myStateFunction;`

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

where `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.

State Jacobian function, 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 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.StateJacFcn = "myStateJacFunction";`
• Handle to a local function, or a function defined in the current working folder or on the MATLAB path

`Model.StateJacFcn = @myStateJacFunction;`

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

where `x` is the state vector, `u` is the input vector, and `pm` is the model parameter vector. `A` is Jacobian of the state function (either continuous or discrete time) with respect to the state vector, and `B` the Jacobian of the state function with respect to the manipulated variable vector. `A` is a square matrix with Nx rows and columns, where Nx is the number of states (`Dimensions.NumberOfStates`). `Bmv` must have Nx rows and Nmv columns, where Nmv is the number of manipulated variables.

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

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.

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.

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.

State information and hard bounds, specified as a structure array with Nx elements, where Nx is the number of states. Each structure element has the following fields.

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

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

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

State units, specified as a string or character vector.

Manipulated Variable (MV) information and hard bounds, specified as a structure array with Nmv elements, where Nmv is the number of manipulated variables. To access this property, you can use the alias `MV` instead of `ManipulatedVariables`.

Each structure element has the following fields.

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

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

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 constraint to implement soft bounds (see Stages).

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.

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 constraint to implement soft bounds (see Stages).

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

MV units, specified as a string or character vector.

Measured disturbance (MD) information, specified as a structure array with Nmd elements, where Nmd is the number of measured disturbances. If your model does not have measured disturbances, then `MeasuredDisturbances` is `[]`. To access this property, you can use the alias `MD` instead of `MeasuredDisturbances`.

Each structure element has the following fields.

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

MD units, specified as a string or character vector.

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.

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

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 input and outputs:

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

where

• `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`, then the `dmv` input must be skipped.

If `Stages(i).SlackVariableLength` is `0` then the `e` input must be skipped.

If `Stages(i).ParameterLength` is `0` then the `pv` input must be skipped.

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 that all functions have the required number of inputs and outputs, in the required order.

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.

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

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 input 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 Nx elements, where Nx is the number of states.

• `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 Nmv elements, where Nmv is the number of manipulated variables.

• `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 Nmv elements, where Nmv is the number of manipulated variables.

• `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 Ne elements, where Ne is the number of stage slack variables.

• `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`, then the `dmv` input and the `Gdmv` output must be skipped.

If `Stages(i).SlackVariableLength` is `0` then the `e` input and the `Ge` output must be skipped.

If `Stages(i).ParameterLength` is `0` then the `pv` input must be skipped.

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 that all functions have the required number of inputs and outputs, in the required order.

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:

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

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

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 input 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`, then the `dmv` input must be skipped.

If `Stages(i).ParameterLength` is `0` then the `pv` input must be skipped.

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 that all functions have the required number of inputs and outputs, in the required order.

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:

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

`Stages(i).EqConJacFcn = 'myEqConJacFunction';`
• Handle to a local function, or a function defined in the current working folder or on the MATLAB path

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

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 input 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 NCeq rows and Nx columns, where NCeq is the number of stage equality constraints and Nx the number of states. Note that NCeq has to be less than NCmv otherwise the problem is overdetermined and generally infeasible.

• `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 NCeq rows and Nmv columns, where NCeq is the number of stage equality constraints and Nmv the number of manipulated variables.

• `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 NCeq rows and Nmv columns, where NCeq is the number of stage equality constraints and Nmv the number of manipulated variables.

• `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`, then the `dmv` input and the `Ceqdmv` output must be skipped.

If `Stages(i).ParameterLength` is `0` then the `pv` input must be skipped.

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 that all functions have the required number of inputs and outputs, in the required order.

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:

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

`Stages(i).IneqConFcn = 'myIneqConFunction';`
• Handle to a local function, or a function defined in the current working folder or on the MATLAB path

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

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 input and outputs:

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

where

• `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`, then the `dmv` input must be skipped.

If `Stages(i).SlackVariableLength` is `0` then the `e` input must be skipped.

If `Stages(i).ParameterLength` is `0` then the `pv` input must be skipped.

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.

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:

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

`Stages(i).IneqConJacFcn = 'myIneqConJacFunction';`
• Handle to a local function, or a function defined in the current working folder or on the MATLAB path

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

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 input and outputs:

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

where

• `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 NC rows and Nx columns, where NC is the number of stage inequality constraints and Nx the number of states.

• `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 NC rows and Nmv columns, where NC is the number of stage inequality constraints and Nmv the number of manipulated variables.

• `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 NC rows and Nmv columns, where NC is the number of stage inequality constraints and Nmv the number of manipulated variables.

• `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 NC rows and Ne columns, where NC is the number of stage inequality constraints and Ne the number of stage slack variables.

• `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`, then the `dmv` input and the `Cdmv` output must be skipped.

If `Stages(i).SlackVariableLength` is `0` then the `e` input and the `Ce` output must be skipped.

If `Stages(i).ParameterLength` is `0` then the `pv` input must be skipped.

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.

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.

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.

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

Custom 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:

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

`Optimization.CustomSolverFcn = "myNLPSolver";`
• Handle to a function in the current working folder or on the MATLAB path

`Optimization.CustomSolverFcn = @myNLPSolver;`

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 `[]`.

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

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

 `nlmpcmove` Compute optimal control action for nonlinear MPC controller `validateFcns` Examine prediction model and custom functions of `nlmpc` or `nlmpcMultistage` objects for potential problems `getSimulationData` Create data structure to simulate multistage MPC controller with `nlmpcmove`

## Examples

collapse all

Create a nonlinear multistage MPC object with a prediction horizon of `5` steps, `2` states, and `1` manipulated variable.

`nlobj = nlmpcMultistage(5,2,1);`

Create a nonlinear multistage MPC object with a prediction horizon of `5` steps, `2` states, and `2` inputs, where the first input is a measured disturbances and the second is a manipulated variable.

`nlobj = nlmpcMultistage(5,2,'MV',2,'MD',1);`

Create a nonlinear multistage MPC object with a prediction horizon of `5` steps, `2` states, and `2` inputs, where the first one is a manipulated variable and the second is an unmeasured disturbance.

`nlobj = nlmpcMultistage(5,2,'MV',1,'UD',2);`

Create a nonlinear multistage 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.

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

Set a sampling time of `2` seconds and display the `nlobj` object

`nlobj.Ts = 2`
```nlobj = 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]```

### Topics

Introduced in R2021a