nlmpcMultistage
Description
A multistage nonlinear model predictive controller computes optimal control moves across the prediction horizon p using a nonlinear prediction model. Stages include the current time k and all prediction steps (from k+1 to k+p). You can specify different cost and constraint functions for each stage. These functions rely only on plant information such as states and inputs available at that stage. For more information on nonlinear MPC, see Nonlinear MPC.
Creation
Syntax
Description
Input Arguments
p
— Prediction horizon
positive integer
Prediction horizon number of steps, specified as a positive integer. This syntax
sets the read-only property PredictionHorizon
equal to the input
argument p
. Since this property is read-only, you cannot change
it after creating the controller object. Note that p
also
determines the number of stages (p
+1).
nx
— Number of prediction model states
positive integer
Number of prediction model states, specified as a positive integer. This value is
stored in the Dimensions.NumberOfStates
controller read-only
property. You cannot change the number of states after creating the controller
object.
nu
— Number of prediction model inputs
positive integer
Number of prediction model inputs, which are all set to be manipulated variables,
specified as a positive integer. This value is stored in the
Dimensions.NumberOfInputs
controller read-only property. You
cannot change the number of manipulated variables after creating the controller
object.
mvIndex
— Manipulated variable indices
vector of positive integers
Manipulated variable indices, specified as a vector of positive integers. You
cannot change these indices after creating the controller object. This value is stored
in the Dimensions.MVIndex
controller property.
The combined set of indices from mvIndex
,
mdIndex
, and udIndex
must contain all
integers from 1
through
Nu, where
Nu is the number of prediction model
inputs.
mdIndex
— Measured disturbance indices
vector of positive integers
Measured disturbance indices, specified as a vector of positive integers. You
cannot change these indices after creating the controller object. This value is stored
in the Dimensions.MDIndex
controller property.
The combined set of indices from mvIndex
,
mdIndex
, and udIndex
must contain all
integers from 1
through
Nu, where
Nu is the number of prediction model
inputs.
udIndex
— Unmeasured disturbance indices
vector of positive integers
Unmeasured disturbance indices, specified as a vector of positive integers. You
cannot change these indices after creating the controller object. This value is stored
in the Dimensions.UDIndex
controller property.
The combined set of indices from mvIndex
,
mdIndex
, and udIndex
must contain all
integers from 1
through
Nu, where
Nu is the number of prediction model
inputs.
Properties
Ts
— Prediction model sample time
1
(default) | positive finite scalar
Prediction model sample time, specified as a positive finite scalar. The controller
uses a discrete-time model with a sample time of Ts
for prediction.
If you specify a continuous-time prediction model
(Model.IsContinuousTime
is true
), then the
controller discretizes the model using a sample time of Ts
to
predict the trajectory. The default solver based on fmincon
uses an
implicit trapezoidal rule while the C/GMRES solver uses an implicit Euler method.
PredictionHorizon
— Prediction horizon
positive integer
This property is read-only.
Prediction horizon steps, specified as a read-only positive integer. The product of
PredictionHorizon
and Ts
is the prediction
time, that is, how far the controller looks into the future.
UseMVRate
— MV rate used in MPC problem
false
(default) | true
Flag indicating whether the rate of change of the manipulated variables is used as a
decision variable in the problem formulation, specified as a logical value. Set
UseMVRate
to true
if:
You need to specify hard upper or lower bounds on the MV rate.
The MV rate appears as a term in a cost or constraint function at any stage.
You need to implement block moves (which you can do so by setting the
RateMin
andRateMax
bounds at the corresponding stages to zero).
By default, the value is false
, which means that the
rate of change of the manipulated variables does not explicitly appear in the
formulation of your MPC problem.
Dimensions
— Prediction model dimensional information
structure
This property is read-only.
Prediction model dimensional information, specified when you create the controller and stored as a structure with the following fields.
NumberOfStates
— Number of states
positive integer
This property is read-only.
Number of states in the prediction model, specified as a positive integer.
This value corresponds to nx
.
NumberOfInputs
— Number of inputs
positive integer
This property is read-only.
Number of inputs in the prediction model, specified as a positive integer.
This value corresponds to either nu
or the sum of the lengths
of mvIndex
, mdIndex
, and
udIndex
.
MVIndex
— Manipulated variable indices
vector of positive integers
This property is read-only.
Manipulated variable indices for the prediction model, specified as a vector
of positive integers. This value corresponds to
mvIndex
.
MDIndex
— Measured disturbance indices
vector of positive integers
This property is read-only.
Measured disturbance indices for the prediction model, specified as a vector
of positive integers. This value corresponds to
mdIndex
.
UDIndex
— Unmeasured disturbance indices
vector of positive integers
This property is read-only.
Unmeasured disturbance indices for the prediction model, specified as a vector
of positive integers. This value corresponds to
udIndex
.
Model
— Prediction model
structure
Prediction model, specified as a structure with the following fields.
StateFcn
— State function
string | character vector | function handle
State function, specified as a string, character vector, or function handle.
For a continuous-time prediction model, StateFcn
is the state
derivative function. For a discrete-time prediction model,
StateFcn
is the state update function.
If your state function is continuous-time, the controller automatically
discretizes the model using the implicit trapezoidal rule when the solver is set
to fmincon
, or the Euler method when the solver is set to
cgmres
. Note that the implicit trapezoidal rule can handle
moderately stiff models, but its prediction accuracy depends on the controller
sample time Ts
; that is, a large sample time leads to
inaccurate prediction.
If the default discretization method does not provide satisfactory prediction for your application, instead of using a continuous-time prediction model, specify your own discrete-time prediction model that uses a different method, such as the multistep forward Euler rule.
You can specify your state function in one of the following ways:
Name of a function in the current working folder or on the MATLAB® path, specified as a string or character vector:
Model.StateFcn = "myStateFunction";
Handle to a local function, or a function defined in the current working folder or on the MATLAB path:
Model.StateFcn = @myStateFunction;
For more information on local functions, see Local Functions.
Note
Only functions defined in a separate file in the current folder or on the MATLAB path are supported for C/C++ code generation. Therefore, specifying state, cost, or constraint functions (or their Jacobians) as local functions is not recommended.
The state function must have the following input and outputs.
if Model.ParameterLength>0 out = myStateFunction(x,u,pm); else out = myStateFunction(x,u); end
Here, x
is the state vector, u
is the
input vector, and pm
is the model parameter vector. If
IsContinuousTime
is true then out
must
be the value of the state derivative with respect to time, otherwise it must be
the value of the state in the following time interval.
For more information, see Specify Prediction Model for Nonlinear MPC.
StateJacFcn
— State Jacobian function
[]
(default) | string | character vector | function handle
State Jacobian function, specified as a string, character vector, or function handle. As a best practice, use Jacobians whenever they are available, since they improve optimization efficiency. If you do not specify a Jacobian for a given function, the nonlinear programming solver must compute the Jacobian numerically for each optimization step.
Note
You can automatically generate a Jacobian function using generateJacobianFunction
.
You can specify your state Jacobian function in one of the following ways:
Name of a function in the current working folder or on the MATLAB path, specified as a string or character vector
Model.StateJacFcn = "myStateJacFunction";
Handle to a local function, or a function defined in the current working folder or on the MATLAB path
Model.StateJacFcn = @myStateJacFunction;
For more information on local functions, see Local Functions.
Note
Only functions defined in a separate file in the current folder or on the MATLAB path are supported for C/C++ code generation. Therefore, specifying state, cost, or constraint functions (or their Jacobians) as local functions is not recommended.
The state Jacobian function must have the following input and outputs.
if Model.ParameterLength>0 [A,Bmv] = myStateJacFunction(x,u,pm); else [A,Bmv] = myStateJacFunction(x,u); end
Here, x
is the state vector, u
is the
input vector, and pm
is the model parameter vector.
A
is the Jacobian of the state function (either continuous or
discrete time) with respect to the state vector and B
is the
Jacobian of the state function with respect to the manipulated variable vector.
A
is a square matrix with
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.
IsContinuousTime
— Flag indicating prediction model time domain
true
(default) | false
Flag indicating the prediction model time domain, specified as one of the following:
true
— Continuous-time prediction model. In this case, the controller automatically discretizes the model during prediction usingTs
.false
— Discrete-time prediction model. In this case,Ts
is the sample time of the model.
Note
If IsContinuousTime
is true
,
StateFcn
must return the derivative of the state with
respect to time, at the current time. Otherwise StateFcn
must return the state at the next control interval.
ParameterLength
— Length of the parameter vector
0
(default) | nonnegative integer
Length of the parameter vector used by the prediction model, specified as a nonnegative integer. If the model state function or its Jacobian require external parameters, set this value to the number of scalar parameters needed. At runtime you must then provide a numeric parameter vector, across the whole prediction horizon, to the controller.
TerminalState
— Terminal state
[]
(default) | vector
Terminal state, specified as a column vector with as many elements as the
number of states. The terminal state is the desired state at the last prediction
step. If any states in the vector do not have terminal values, specify
inf
at the corresponding locations to leave their terminal
values free.
The default value of this property is []
, meaning that no
terminal state constraint is enforced.
States
— State information and bounds
structure array
State information and hard bounds, specified as a structure array with Nx elements, where Nx is the number of states. Each structure element has the following fields.
Min
— State hard lower bound
-Inf
(default) | scalar | vector
State hard lower bound, specified as a scalar or vector. By default, this
lower bound is -Inf
.
To use the same bound across the prediction horizon, specify a scalar value.
To vary the bound over the prediction horizon from time k+1 to time k+p, specify a vector of up to p values. Here, k is the current time and p is the prediction horizon. If you specify fewer than p values, the final bound is used for the remaining steps of the prediction horizon.
State bounds are always hard constraints. Use stage inequality constraints to implement soft bounds (see Stages).
Max
— State hard upper bound
Inf
(default) | scalar | vector
State hard upper bound, specified as a scalar or vector. By default, this
upper bound is Inf
.
To use the same bound across the prediction horizon, specify a scalar value.
To vary the bound over the prediction horizon from time k+1 to time k+p, specify a vector of up to p values. Here, k is the current time and p is the prediction horizon. If you specify fewer than p values, the final bound is used for the remaining steps of the prediction horizon.
State bounds are always hard constraints. Use stage inequality constraints to implement soft bounds (see Stages).
Name
— State name
string | character vector
State name, specified as a string or character vector. The default state name
is "x#"
, where #
is its state index.
Units
— State units
""
(default) | string | character vector
State units, specified as a string or character vector.
ManipulatedVariables
— Manipulated variable information and hard bounds
structure array
Manipulated Variable (MV) information and hard bounds, specified as a structure
array with 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.
Min
— MV hard lower bound
-Inf
(default) | scalar | vector
MV hard lower bound, specified as a scalar or vector. By default, this lower
bound is -Inf
.
To use the same bound across the prediction horizon, specify a scalar value.
To vary the bound over the prediction horizon from time k to time k+p–1, specify a vector of up to p values. Here, k is the current time and p is the prediction horizon. If you specify fewer than p values, the final bound is used for the remaining steps of the prediction horizon.
MV bounds are always hard constraints. Use stage inequality constraints to implement soft bounds (see Stages).
Max
— MV hard upper bound
Inf
(default) | scalar | vector
MV hard upper bound, specified as a scalar or vector. By default, this upper
bound is +Inf
.
To use the same bound across the prediction horizon, specify a scalar value.
To vary the bound over the prediction horizon from time k to time k+p–1, specify a vector of up to p values. Here, k is the current time and p is the prediction horizon. If you specify fewer than p values, the final bound is used for the remaining steps of the prediction horizon.
MV bounds are always hard constraints. Use stage inequality constraints to implement soft bounds (see Stages).
RateMin
— MV rate of change hard lower bound
-Inf
(default) | nonpositive scalar | vector
MV rate of change hard lower bound, specified as a nonpositive scalar or
vector. The MV rate of change at stage i is defined as
MV(i) -
MV(i–1). By default, this lower bound is
-Inf
. If UseMVRate is false
this value is ignored.
To use the same bound across the prediction horizon, specify a scalar value.
To vary the bound over the prediction horizon from time k to time k+p–1, specify a vector of up to p values. Here, k is the current time and p is the prediction horizon. If you specify fewer than p values, the final bound is used for the remaining steps of the prediction horizon.
MV rate bounds are always hard constraints. Use stage inequality constraints to implement soft bounds (see Stages).
RateMax
— MV rate of change hard upper bound
Inf
(default) | nonnegative scalar | vector
MV rate of change hard upper bound, specified as a nonnegative scalar or
vector. The MV rate of change at stage i is defined as
MV(i) -
MV(i–1). By default, this upper bound is
+Inf
.
To use the same bound across the prediction horizon, specify a scalar value.
If UseMVRate is false
this value is ignored.
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).
Name
— MV name
string | character vector
MV name, specified as a string or character vector. The default MV name is
"u#"
, where #
is its input index.
Units
— MV units
""
(default) | string | character vector
MV units, specified as a string or character vector.
MeasuredDisturbances
— Measured disturbance information
structure array
Measured disturbance (MD) information, specified as a structure array with
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.
Name
— MD name
string | character vector
MD name, specified as a string or character vector. The default MD name is
"u#"
, where #
is its input index.
Units
— MD units
""
(default) | string | character vector
MD units, specified as a string or character vector.
Stages
— Stage cost and constraint functions
structure
Stage cost and constraint functions, specified as an array of p+1
structures (where p
is the prediction horizon), each one with the
following fields.
CostFcn
— Cost function at stage i
string | character vector | function handle
Cost function at stage i
(where i
ranges
from 1
to p+1
), specified as a string,
character vector, or function handle. The overall cost function of the nonlinear
MPC problem is the sum of the cost functions at each stage.
You can specify your stage cost function in one of the following ways:
Name of a function in the current working folder or on the MATLAB path, specified as a string or character vector
Stages(i).CostFcn = 'myCostFunction';
Handle to a local function or a function defined in the current working folder or on the MATLAB path
Stages(i).CostFcn = @myCostFunction;
For more information on local functions, see Local Functions.
Note
Only functions defined in a separate file in the current folder or on the MATLAB path are supported for C/C++ code generation. Therefore, specifying state, cost, or constraint functions (or their Jacobians) as local functions is not recommended.
In the most general case in which UseMVRate is true
, and both
Stages(i).ParameterLength
and
Stages(i).SlackVariableLength
are greater than
0
, the cost function must have the following inputs and
outputs.
Ji = myCostFunction(i,x,u,dmv,e,pv);
Here:
Ji
is a double scalar expressing the cost for stagei
.i
is the stage number from1
(current control interval) top+1
(end of the prediction horizon).x
is the state vector.u
is the input vector.dmv
is the manipulated variable rate vector (change with respect to previous control interval).e
is the stage slack variable vector.pv
is the stage parameter vector.
If UseMVRate
is false
, omit the
dmv
input.
If Stages(i).SlackVariableLength
is 0
,
omit the e
input.
If Stages(i).ParameterLength
is 0
,
omit the pv
input.
In summary:
if UseMVRate is true if Stages(i).SlackVariableLength>0 if Stages(i).ParameterLength>0 Ji = myCostFunction(i,x,u,dmv,e,pv); else Ji = myCostFunction(i,x,u,dmv,e); end else if Stages(i).ParameterLength>0 Ji = myCostFunction(i,x,u,dmv,pv); else Ji = myCostFunction(i,x,u,dmv); end end else if Stages(i).SlackVariableLength>0 if Stages(i).ParameterLength>0 Ji = myCostFunction(i,x,u,e,pv); else Ji = myCostFunction(i,x,u,e); end else if Stages(i).ParameterLength>0 Ji = myCostFunction(i,x,u,pv); else Ji = myCostFunction(i,x,u); end end end
Note that you can also write separate functions for separate stages as long as
their name is specified in Stages(i).CostFcn
and all
functions have the required number of inputs and outputs, in the required
order.
For more information, see Specify Prediction Model for Nonlinear MPC.
CostJacFcn
— Gradient of the cost function at stage i
string | character vector | function handle
Gradient of the cost function at stage i
(where
i
ranges from 1
to
p+1
), specified as a string, character vector, or function
handle. It is best practice to use Jacobians (in this case, gradients) whenever
they are available, since they improve optimization efficiency. If you do not
specify a Jacobian for a given function, the nonlinear programming solver must
numerically compute the Jacobian at each optimization step.
Note
You can automatically generate a Jacobian function using generateJacobianFunction
.
You can specify your stage cost Jacobian function in one of the following ways:
Name of a function in the current working folder or on the MATLAB path, specified as a string or character vector
Stages(i).CostJacFcn = 'myCostJacFunction';
Handle to a local function, or a function defined in the current working folder or on the MATLAB path
Stages(i).CostJacFcn = @myCostJacFunction;
For more information on local functions, see Local Functions.
Note
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 stagei
with respect to the state vectorx
. 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 stagei
with respect to the manipulated variable vectormv
. 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 stagei
with respect to the manipulated variable vector changedmv
. 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 stagei
with 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.i
is the stage number from1
(current control interval) top+1
(end of the prediction horizon).x
is the state vector.u
is the input vector.dmv
is the manipulated variable rate vector (change with respect to the previous control interval).e
is the stage slack variable vector.pv
is the stage parameter vector.
If UseMVRate
is false
, omit the
dmv
input and the Gdmv
output.
If Stages(i).SlackVariableLength
is 0
,
omit the e
input and the Ge
output.
If Stages(i).ParameterLength
is 0
,
omit the pv
input.
In summary:
if UseMVRate is true if Stages(i).SlackVariableLength>0 if Stages(i).ParameterLength>0 [Gx,Gmv,Gdmv,Ge] = myCostJacFunction(i,x,u,dmv,e,pv); else [Gx,Gmv,Gdmv,Ge] = myCostJacFunction(i,x,u,dmv,e); end else if Stages(i).ParameterLength>0 [Gx,Gmv,Gdmv] = myCostJacFunction(i,x,u,dmv,pv); else [Gx,Gmv,Gdmv] = myCostJacFunction(i,x,u,dmv); end end else if Stages(i).SlackVariableLength>0 if Stages(i).ParameterLength>0 [Gx,Gmv,Ge] = myCostJacFunction(i,x,u,e,pv); else [Gx,Gmv,Ge] = myCostJacFunction(i,x,u,e); end else if Stages(i).ParameterLength>0 [Gx,Gmv] = myCostJacFunction(i,x,u,pv); else [Gx,Gmv] = myCostJacFunction(i,x,u); end end end
Note that you can also write separate functions for separate stages as long as
their name is specified in Stages(i).CostJacFcn
and all
functions have the required number of inputs and outputs, in the required
order.
For more information, see Specify Prediction Model for Nonlinear MPC.
EqConFcn
— Equality constraint function at stage i
string | character vector | function handle
Equality constraint function at stage i
(where
i
ranges from 1
to p
),
specified as a string, character vector, or function handle. Note that specifying
an equality constraint for the last stage (p
+1) is not
supported. Use the TerminalState
field of the
Model
property instead.
You can specify your stage equality constraint function in one of the following ways:
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 stagei
. At any feasible solution of the MPC problem the returnedCeq
must be equal to0
. Note that the number of elements inCeq
must be less than the number of manipulated variables otherwise the problem is overspecified and generally infeasible.i
is the stage number from1
(current control interval) top+1
(end of the prediction horizon).x
is the state vector.u
is the input vector.dmv
is the manipulated variable rate vector (change with respect to previous control interval).pv
is the stage parameter vector.
If UseMVRate
is false
, omit the
dmv
input.
If Stages(i).ParameterLength
is 0
,
omit the pv
input.
In summary:
if UseMVRate is true if Stages(i).ParameterLength>0 Ceq = myEqConFunction(i,x,u,dmv,pv); else Ceq = myEqConFunction(i,x,u,dmv); end else if Stages(i).ParameterLength>0 Ceq = myEqConFunction(i,x,u,pv); else Ceq = myEqConFunction(i,x,u); end end
Note that you can also write separate functions for separate stages as long as
their name is specified in Stages(i).EqConFcn
and all
functions have the required number of inputs and outputs, in the required
order.
For more information, see Specify Prediction Model for Nonlinear MPC.
EqConJacFcn
— Jacobian of equality constraint function at stage i
string | character vector | function handle
Jacobian of the equality constraint function at stage i
(where i
ranges from 1
to
p
), specified as a string, character vector, or function
handle. Note that specifying an equality constraint (and hence its Jacobian
function) for the last stage (p
+1) is not supported.
It is best practice to use Jacobians whenever they are available, since they improve optimization efficiency. If you do not specify a Jacobian for a given function, the nonlinear programming solver must numerically compute the Jacobian.
You can specify your stage equality constraint Jacobian function in one of the following ways:
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 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.Ceqmv
is 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.Ceqdmv
is 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.i
is the stage number from1
(current control interval) top+1
(end of the prediction horizon).x
is the state vector.u
is the input vector.dmv
is the manipulated variable rate vector (change with respect to previous control interval).pv
is the stage parameter vector.
If UseMVRate
is false
, omit the
dmv
input and the Ceqdmv
output.
If Stages(i).ParameterLength
is 0
,
omit the pv
input.
In summary
if UseMVRate is true if Stages(i).ParameterLength>0 [Ceqx,Ceqmv,Ceqdmv] = myEqConJacFunction(i,x,u,dmv,pv); else [Ceqx,Ceqmv,Ceqdmv] = myEqConJacFunction(i,x,u,dmv); end else if Stages(i).ParameterLength>0 [Ceqx,Ceqmv] = myEqConJacFunction(i,x,u,pv); else [Ceqx,Ceqmv] = myEqConJacFunction(i,x,u); end end
Note that you can also write separate functions for separate stages as long as
their name is specified in Stages(i).EqConJacFcn
and all
functions have the required number of inputs and outputs, in the required
order.
For more information, see Specify Prediction Model for Nonlinear MPC.
IneqConFcn
— Inequality constraint function at stage i
string | character vector | function handle
Inequality constraint function at stage i
(where
i
ranges from 1
to
p+1
), specified as a string, character vector, or function
handle.
You can specify your stage inequality constraint function in one of the following ways:
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 stagei
. For any feasible solution of the MPC problem,C
must be non-positive.i
is the stage number from1
(current control interval) top+1
(end of the prediction horizon).x
is the state vector.u
is the input vector.dmv
is the manipulated variable rate vector (change with respect to previous control interval).e
is the stage slack variable vector.pv
is the stage parameter vector.
If UseMVRate
is false
, omit the
dmv
input.
If Stages(i).SlackVariableLength
is
0
, omit the e
input.
If Stages(i).ParameterLength
is 0
,
omit the pv
input.
In summary:
if UseMVRate is true if Stages(i).SlackVariableLength>0 if Stages(i).ParameterLength>0 C = myIneqConFunction(i,x,u,dmv,e,pv); else C = myIneqConFunction(i,x,u,dmv,e); end else if Stages(i).ParameterLength>0 C = myIneqConFunction(i,x,u,dmv,pv); else C = myIneqConFunction(i,x,u,dmv); end end else if Stages(i).SlackVariableLength>0 if Stages(i).ParameterLength>0 C = myIneqConFunction(i,x,u,e,pv); else C = myIneqConFunction(i,x,u,e); end else if Stages(i).ParameterLength>0 C = myIneqConFunction(i,x,u,pv); else C = myIneqConFunction(i,x,u); end end end
Note that you can also write separate functions for separate stages as long as
their name is specified in Stages(i).IneqConFcn
and that all
functions have the required number of inputs and outputs, in the required
order.
For more information, see Specify Prediction Model for Nonlinear MPC.
IneqConJacFcn
— Jacobian of the inequality constraint function at stage i
string | character vector | function handle
Jacobian of the inequality constraint function at stage i
(where i
ranges from 1
to
p+1
), specified as a string, character vector, or function
handle. It is best practice to use Jacobians whenever they are available, since
they improve optimization efficiency. If you do not specify a Jacobian for a given
function, the nonlinear programming solver must numerically compute the
Jacobian.
You can specify your stage constraint Jacobian function in one of the following ways:
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 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.Cmv
is 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.Cdmv
is 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.Ce
is 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.i
is the stage number from1
(current control interval) top+1
(end of the prediction horizon).x
is the state vector.u
is the input vector.dmv
is the manipulated variable rate vector (change with respect to previous control interval).e
is the stage slack variable vector.pv
is the stage parameter vector.
If UseMVRate
is false
, omit the
dmv
input and the Cdmv
output.
If Stages(i).SlackVariableLength
is 0
,
omit the e
input and the Ce
output.
If Stages(i).ParameterLength
is 0
,
omit the pv
input.
In summary:
if UseMVRate is true if Stages(i).SlackVariableLength>0 if Stages(i).ParameterLength>0 [Cx,Cmv,Cdmv,Ce] = myIneqConJacFunction(i,x,u,dmv,e,pv); else [Cx,Cmv,Cdmv,Ce] = myIneqConJacFunction(i,x,u,dmv,e); end else if Stages(i).ParameterLength>0 [Cx,Cmv,Cdmv] = myIneqConJacFunction(i,x,u,dmv,pv); else [Cx,Cmv,Cdmv] = myIneqConJacFunction(i,x,u,dmv); end end else if Stages(i).SlackVariableLength>0 if Stages(i).ParameterLength>0 [Cx,Cmv,Ce] = myIneqConJacFunction(i,x,u,e,pv); else [Cx,Cmv,Ce] = myIneqConJacFunction(i,x,u,e); end else if Stages(i).ParameterLength>0 [Cx,Cmv] = myIneqConJacFunction(i,x,u,pv); else [Cx,Cmv] = myIneqConJacFunction(i,x,u); end end end
Note that you can also write separate functions for separate stages as long as
their name is specified in Stages(i).IneqConFcn
and that all
functions have the required number of inputs and outputs, in the required
order.
For more information, see Specify Prediction Model for Nonlinear MPC.
SlackVariableLength
— Length of the stage slack variable vector
0
(default) | nonnegative integer
Length of the slack variable vector used by the cost and constraint functions
at stage i
, specified as a nonnegative integer. You can use
slack variables to implement soft constraints for a given stage, using the
corresponding IneqConFcn
and CostFcn
functions.
ParameterLength
— Length of the parameter vector
0
(default) | nonnegative integer
Length of the parameter vector used by the cost and constraint functions at
stage i
, specified as a nonnegative integer. If any stage uses
parameters, this value must be positive, and as a consequence all the stage
functions must have a parameter vector as their last input argument.
Optimization
— Custom optimization functions and solver
structure
Custom optimization functions and solver, specified as a structure with the following fields.
Solver
— Solver
'fmincon'
(default) | 'cgmres'
Solver function, specified as one of the following strings or character vectors:
'fmincon'
or"fmincon"
— The software uses the Optimization Toolbox™ functionfmincon
to solve the multistage nonlinear MPC optimization problem at each time step.'cgmres'
or"cgmres"
— The software uses a Continuation / Generalized Minimum Residual (C/GMRES) method to solve the multistage nonlinear MPC problem at each time step. Use this solver for large-scale linear and nonlinear systems and for systems with relevant nonlinear constraints. Due to its computational efficiency, this solver is also generally suitable for implementation in real-time embedded systems.For an example on how to use the C/GMRES solver, see Control Robot Manipulator Using C/GMRES Solver.
For more information, see Configure Optimization Solver for Nonlinear MPC.
CustomSolverFcn
— Custom nonlinear programming solver
[]
(default) | string | character vector | function handle
Custom nonlinear programming solver function, specified as a string, character vector, or function handle. You can specify your custom solver function in one of the following ways:
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.
SolverOptions
— Solver options
options object for fmincon
(default) | options object for C/GMRES solver | []
Solver options, specified as an options object for
fmincon
, an options object for the C/GMRES solver, or
[]
.
If you have Optimization Toolbox software, by default SolverOptions
contains an
options object for the fmincon
solver.
If you do not have Optimization Toolbox, by default SolverOptions
is
[]
.
If you specify the Optimization.Solver
property of
msobj
as "cgmres"
,
SolverOptions
is an options object for the C/GMRES
solver.
For more information, see Configure Optimization Solver for Nonlinear MPC.
UseSuboptimalSolution
— Flag indicating whether a suboptimal solution is acceptable
false
(default) | true
Flag indicating whether a suboptimal solution is acceptable, specified as a
logical value. When the nonlinear programming solver reaches the maximum number of
iterations without finding a solution (the exit flag is 0
), the
controller:
Freezes the MV values if
UseSuboptimalSolution
isfalse
Applies the suboptimal solution found by the solver after the final iteration if
UseSuboptimalSolution
istrue
To specify the maximum number of iterations, use
Optimization.SolverOptions.MaxIter
.
PerturbationRatio
— Coefficient used to calculate perturbation sizes
1e-6
(default) | positive scalar
Coefficient used to calculate the perturbation sizes applied to the decision
variables when using forward finite differences to estimate derivatives. The
perturbation size vector for the decision variable vector z
is
PerturbationRatio*max(abs(z),1)
. The default value for this
parameter is 1e–6
. If your prediction model is stiff and your
cost/constraint terms are sensitive, use a smaller value such as
1e–8
.
Object Functions
generateJacobianFunction | Generate MATLAB Jacobian functions for multistage nonlinear MPC using automatic differentiation |
validateFcns | Examine prediction model and custom functions of nlmpc or
nlmpcMultistage objects for potential problems |
nlmpcmove | Compute optimal control action for nonlinear MPC controller |
getSimulationData | Create data structure to simulate multistage MPC controller with
nlmpcmove |
Examples
Create Multistage Nonlinear MPC object
Create a multistage nonlinear MPC object with a prediction horizon of
5
steps, 2
states, and 1
manipulated variable.
msobj = nlmpcMultistage(5,2,1);
Create Multistage Nonlinear MPC Object with Measured Disturbance Inputs
Create a multistage nonlinear MPC object with a prediction horizon of
5
steps, 2
states, and 2
inputs, where the first input is a measured disturbance and the second is a manipulated
variable.
msobj = nlmpcMultistage(5,2,MV=2,MD=1);
Create Multistage Nonlinear MPC Object with Unmeasured Disturbance Inputs
Create a multistage nonlinear MPC object with a prediction horizon of
5
steps, 2
states, and 2
inputs, where the first input is a manipulated variable and the second is an unmeasured
disturbance.
msobj = nlmpcMultistage(5,2,MV=1,UD=2);
Create Multistage Nonlinear MPC Object with Measured and Unmeasured Disturbance Inputs
Create a multistage nonlinear MPC object with a prediction horizon of
6
steps, 3
states, and 4
inputs, where the first two inputs are measured disturbances, the third is the manipulated
variable, and the fourth is an unmeasured disturbance.
msobj = nlmpcMultistage(6, 3, MV=3, MD=[1 2], UD=4);
Set a sampling time of 2
seconds and display the
msobj
object.
msobj.Ts = 2
msobj = nlmpcMultistage with properties: Ts: 2 PredictionHorizon: 6 UseMVRate: 0 Dimensions: [1×1 struct] Model: [1×1 struct] States: [1×3 struct] ManipulatedVariables: [1×1 struct] MeasuredDisturbances: [1×2 struct] Stages: [1×7 struct] Optimization: [1×1 struct]
Version History
Introduced in R2021a
See Also
Functions
generateJacobianFunction
|validateFcns
|nlmpcmove
|nlmpcmoveCodeGeneration
|getSimulationData
|getCodeGenerationData
Objects
Blocks
Commande MATLAB
Vous avez cliqué sur un lien qui correspond à cette commande MATLAB :
Pour exécuter la commande, saisissez-la dans la fenêtre de commande de MATLAB. Les navigateurs web ne supportent pas les commandes MATLAB.
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)