Main Content

nlmpcMultistage

Multistage nonlinear model predictive controller

Since R2021a

expand all in page

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

msobj = nlmpcMultistage(p,nx,nu)
msobj = nlmpcMultistage(p,nx,MV=mvIndex,MD=mdIndex)
msobj = nlmpcMultistage(p,nx,MV=mvIndex,UD=udIndex)
msobj = nlmpcMultistage(p,nx,MV=mvIndex,MD=mdIndex,UD=udIndex)

Description

msobj = nlmpcMultistage(p,nx,nu) creates an nlmpcMultistage object with a prediction horizon p, 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

msobj = 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

msobj = 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

msobj = 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.

example

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

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.

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.

This property is read-only.

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

This property is read-only.

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

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.

This property is read-only.

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

This property is read-only.

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

This property is read-only.

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

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

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

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.

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

    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.

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

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

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;

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

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;

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

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;

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

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;

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

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.

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.

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:

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

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

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.

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

generateJacobianFunctionGenerate MATLAB Jacobian functions for multistage nonlinear MPC using automatic differentiation
validateFcnsExamine prediction model and custom functions of nlmpc or nlmpcMultistage objects for potential problems
nlmpcmoveCompute optimal control action for nonlinear MPC controller
getSimulationDataCreate data structure to simulate multistage MPC controller with nlmpcmove

Examples

collapse all

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

Objects

Blocks

Topics