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
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
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
RateMinandRateMaxbounds 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 usingTs.false— Discrete-time prediction model. In this case,Tsis 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:
Jiis a double scalar expressing the cost for stagei.iis the stage number from1(current control interval) top+1(end of the prediction horizon).xis the state vector.uis the input vector.dmvis the manipulated variable rate vector (change with respect to previous control interval).eis the stage slack variable vector.pvis 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
endNote 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
Gxis the gradient of cost function for stageiwith respect to the state vectorx. It must be a column vector with Nx elements, where Nx is the number of states.Gmvis the gradient of the cost function for stageiwith respect to the manipulated variable vectormv. It must be a column vector with Nmv elements, where Nmv is the number of manipulated variables.Gdmvis the gradient of the cost function for stageiwith respect to the manipulated variable vector changedmv. It must be a column vector with Nmv elements, where Nmv is the number of manipulated variables.Geis the gradient of the cost function for stageiwith respect to the stage slack variable vectore. It must be a column vector with Ne elements, where Ne is the number of stage slack variables.iis the stage number from1(current control interval) top+1(end of the prediction horizon).xis the state vector.uis the input vector.dmvis the manipulated variable rate vector (change with respect to the previous control interval).eis the stage slack variable vector.pvis 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
endNote 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
Ceqis a vector expressing the equality constraints for stagei. At any feasible solution of the MPC problem the returnedCeqmust be equal to0. Note that the number of elements inCeqmust be less than the number of manipulated variables otherwise the problem is overspecified and generally infeasible.iis the stage number from1(current control interval) top+1(end of the prediction horizon).xis the state vector.uis the input vector.dmvis the manipulated variable rate vector (change with respect to previous control interval).pvis 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
endNote 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
Ceqxis the Jacobian of the equality constraint function for stagei, with respect to the state vectorx. 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.Ceqmvis the Jacobian of the equality constraint function for stagei, with respect to the manipulated variable vectormv. 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.Ceqdmvis the Jacobian of the equality constraint function for stagei, 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.iis the stage number from1(current control interval) top+1(end of the prediction horizon).xis the state vector.uis the input vector.dmvis the manipulated variable rate vector (change with respect to previous control interval).pvis 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:
Cis a vector expressing the inequality constraints for stagei. For any feasible solution of the MPC problem,Cmust be non-positive.iis the stage number from1(current control interval) top+1(end of the prediction horizon).xis the state vector.uis the input vector.dmvis the manipulated variable rate vector (change with respect to previous control interval).eis the stage slack variable vector.pvis 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
endNote 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.
Note
If you use an nlmpcMultistage object configured to use the
C/GMRES algorithm within a Multistage
Nonlinear MPC Controller block, the number of inequality constraints
must remain the same for each stage. If you need to use a different number of
inequality constraints at any stage, then write separate inequality functions
for each stage.
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:
Cxis the Jacobian of the inequality constraint function for stagei, with respect to the state vectorx. 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.Cmvis the Jacobian of the inequality constraint function for stagei, with respect to the manipulated variable vectormv. 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.Cdmvis the Jacobian of the inequality constraint function for stagei, 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.Ceis the Jacobian of the inequality constraint function for stagei, with respect to the stage slack variable vectore. 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.iis the stage number from1(current control interval) top+1(end of the prediction horizon).xis the state vector.uis the input vector.dmvis the manipulated variable rate vector (change with respect to previous control interval).eis the stage slack variable vector.pvis 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
endNote 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™ functionfminconto 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.Note
If you use an
nlmpcMultistageobject configured to use the C/GMRES algorithm within a Multistage Nonlinear MPC Controller block, the number of inequality constraints must remain the same for each stage. If you need to use a different number of inequality constraints at any stage, then write separate inequality functions for each stage.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
UseSuboptimalSolutionisfalseApplies the suboptimal solution found by the solver after the final iteration if
UseSuboptimalSolutionistrue
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
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 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
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)