Specify Constraints for Generic Nonlinear MPC
When you create a nonlinear MPC controller using an nlmpc
object, you
can define any of the following constraints:
Standard linear constraints on states, outputs, manipulated variables, and manipulated variable rates of change
Custom equality constraints, specified as linear or nonlinear functions of the prediction model system states and inputs
Custom inequality constraints, specified as linear or nonlinear functions of the prediction model system states and inputs
Passivity inequality constraints, specified as linear or nonlinear functions of the prediction model states and inputs
The controller optimizes its control moves to satisfy all of these constraints; that is, the custom constraints supplement the standard linear constraints.
To improve computational efficiency, you can also specify analytical Jacobians for your custom equality and inequality constraints.
By specifying custom equality or inequality constraints, you can, for example:
Require the plant to reach a target state at the end of the prediction horizon
Require cumulative resource consumption to stay within specified limits
If your plant is passive, enforcing controller passivity guarantees that the resulting closed loop system is stable. You can enforce controller passivity by specifying passivity constraints.
For a multistage MPC controller, each stage has its own constraints, and each constraint
for a specific stage is function only of the decision variables and parameters at that stage.
Passivity constraints are not supported for nlmpcMultistage
objects.
Before simulating your controller, it is best practice to validate your custom functions,
including the constraint functions and their Jacobians, using the validateFcns
command.
Linear MPC controllers have properties for defining custom constraints on linear combinations of inputs and outputs, as discussed in Constraints on Linear Combinations of Inputs and Outputs. These properties are not available for nonlinear MPC controllers. Instead, you implement such constraints within your custom equality or inequality constraint functions.
Standard Linear Constraints
The following table shows the standard linear constraints supported by nonlinear MPC
controllers. For each of these constraints, you can specify a single bound that applies
across the entire prediction horizon, or you can vary each constraint over the prediction
horizon. For more information on setting controller linear constraint properties, see
nlmpc
.
Constraint  Controller Property  Constraint Softening 

Lower bounds on state i  States(i).Min > Inf  Not applicable. State bounds are always hard. 
Upper bounds on state i  States(i).Max < Inf  Not applicable. State bounds are always hard. 
Lower bounds on output variable i  OutputVariables(i).Min > Inf 
Default:

Upper bounds on output variable i  OutputVariables(i).Max < Inf 
Default:

Lower bounds on manipulated variable i  ManipulatedVariables(i).Min > Inf 
Default:

Upper bounds on manipulated variable i  ManipulatedVariables(i).Max < Inf 
Default:

Lower bounds on manipulated variable i rate of
change  ManipulatedVariables(i).RateMin > Inf 
Default:

Lower bounds on manipulated variable i rate of
change  ManipulatedVariables(i).RateMax < Inf 
Default:

Custom Constraints
You can specify custom equality and inequality constraints for a nonlinear MPC
controller. To configure your nonlinear MPC controller to use custom equality or inequality
constraints, set its Optimization.CustomEqConFcn
or
Optimization.CustomIneqConFcn
respectively. To do so, specify the
custom functions as one of the following.
Name of a function in the current working folder or on the MATLAB^{®} path, specified as a string or character vector
Optimization.CustomEqConFcn = "myEqConFunction"; Optimization.CustomIneqConFcn = "myIneqConFunction";
Handle to a function in the current working folder or on the MATLAB path
Optimization.CustomEqConFcn = @myEqConFunction; Optimization.CustomIneqConFcn = @myIneqConFunction;
For more information on local functions, see Local Functions.
Anonymous function
Optimization.CustomEqConFcn = ... @(X,U,data,params) myEqConFunction(X,U,data,params); Optimization.CustomIneqConFcn = ... @(X,U,e,data,params) myIneqConFunction(X,U,e,data,params);
For more information on anonymous functions, see Anonymous 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, output, cost, or constraint functions (or their Jacobians) as local or anonymous functions is not recommended.
Your constraint functions must have one of the following signatures.
If your controller does not use optional parameters:
function ceq = myEqConFunction(X,U,data) function cineq = myIneqConFunction(X,U,e,data)
If your controller uses parameters. Here,
params
is a commaseparated list of parameters:function ceq = myEqConFunction(X,U,data,params) function cineq = myIneqConFunction(X,U,e,data,params)
This table describes the inputs and outputs of these functions, where:
N_{x} is the number of states and is equal to the
Dimensions.NumberOfStates
property of the controller.N_{u} is the number of inputs, including all manipulated variables, measured disturbances, and unmeasured disturbances, and is equal to the
Dimensions.NumberOfInputs
property of the controller.N_{ceq} is the number of equality constraints.
N_{cineq} is the number of inequality constraints.
p is the prediction horizon.
k is the current time.
Argument  Input/Output  Description  

X  Input  State trajectory from time k to time
k+p, specified as a
(p+1)byN_{x} array.
The first row of X contains the current state values, which means
that the solver does not use the values in X(1,:) as decision
variables during optimization.  
U  Input  Input trajectory from time k to time
k+p, specified as a
(p+1)byN_{u} array.
The final row of U is always a duplicate of the preceding row;
that is, U(end,:) = U(end1,:) . Therefore, the
values in the final row of U are not independent decision
variables during optimization.  
e  Input  Slack variable for constraint softening, specified as a positive scalar. Since all equality constraints are hard, this input argument applies to only the inequality constraint function.  
data  Input  Additional signals, specified as a structure with the following fields:
 
params  Input  Optional parameters, specified as a commaseparated list (for example
If your model uses optional
parameters, you must specify the number of parameters using
 
ceq  Output  Computed equality constraint values, returned as a column vector of length
N_{ceq}. An equality constraint is
satisfied when the corresponding output is 0 .  
cineq  Output  Computed inequality constraint values, returned as a column vector of length
N_{cineq}. An inequality constraint is
satisfied when the corresponding output is less than or equal to
0 . 
To use output variable values in your constraint functions, you must first derive them
from the state and input arguments using the prediction model output function, as specified
in the Model.OutputFcn
property of the controller. For example, to
compute the output trajectory Y
from time k to time
k+p, use:
p = data.PredictionHorizon; for i=1:p+1 Y(i,:) = myOutputFunction(X(i,:)',U(i,:)',params)'; end
For more information on the prediction model output function, see Specify Prediction Model for Nonlinear MPC.
In general:
All equality constraints are hard.
To define soft inequality constraints, use the slack variable input argument,
e
. For more information on constraint softening in MPC, see Constraint Softening.Equality constraints should be continuous and have continuous first derivatives with respect to the decision variables.
You can define custom constraints that apply across the entire prediction horizon. For example, suppose that you want to satisfy the following inequality constraints across the prediction horizon, where u_{1} is the first manipulated variable:
$$\begin{array}{l}2{x}_{1}^{2}3{x}_{2}10\le 0\\ {u}_{1}^{2}5\le 0\end{array}$$
To define the constraint values across the prediction horizon, use:
p = data.PredictionHorizon; U1 = U(1:p,data.MVIndex(1)); X1 = X(2:p+1,1); X2 = X(2:p+1,2); cineq = [2*X1.^2  3*X2  10; U1.^2  5];
Applying these two constraints across p prediction horizon steps
produces a column vector with 2*p inequality constraints. These
inequality constraints are satisfied when the corresponding element of
cineq
is less than or equal to zero.
Alternatively, you can define constraints that apply at specific prediction horizon steps. For example, suppose that you want the states of a thirdorder plant to be:
$$\begin{array}{l}{x}_{1}=5\\ {x}_{2}=3\\ {x}_{3}=0\end{array}$$
To specify these state values as constraints on only the final prediction horizon step, use:
ceq = [X(p+1,1)  5; X(p+1,2) + 3; X(p+1,3)];
These equality constraints are satisfied when the corresponding element of
ceq
is equal to zero.
For relatively simple constraints, you can specify the constraint function using an anonymous function handle. For example, to specify an anonymous function that implements the equality constraints, use:
Optimization.CustomEqConFcn = @(X,U,data) [X(p+1,1)  5; X(p+1,2) + 3; X(p+1,3)];
Custom Constraint Jacobians
To improve computational efficiency, it is best practice to specify analytical Jacobians for your custom constraint functions. If you do not specify Jacobians, the controller computes the Jacobians using numerical perturbation.
To specify a Jacobian for your equality or inequality constraint functions, set the
respective Jacobian.CustomEqConFcn
or
Jacobian.CustomIneqConFcn
property of the controller to one of the
following.
Name of a function in the current working folder or on the MATLAB path, specified as a string or character vector
Jacobian.CustomEqConFcn = "myEqConJacobian"; Jacobian.CustomIneqConFcn = "myIneqConJacobian";
Handle to a local function, or a function defined in the current working folder or on the MATLAB path
Jacobian.CustomEqConFcn = @myEqConJacobian; Jacobian.CustomIneqConFcn = @myIneqConJacobian;
For more information on local functions, see Local Functions.
Anonymous function
Jacobian.CustomEqConFcn = @(X,U,data,params) myEqConJacobian(X,U,data,params); Jacobian.CustomInqConFcn = @(X,U,e,data,params) myIneqConJacobian(X,U,e,data,params);
For more information on anonymous functions, see Anonymous 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, output, cost, or constraint functions (or their Jacobians) as local or anonymous functions is not recommended.
Your constraint Jacobian functions must have one of the following signatures.
If your controller does not use optional parameters:
function [Geq,Gmv] = myEqConJacobian(X,U,data) function [Geq,Gmv,Ge] = myIneqConJacobian(X,U,e,data)
If your controller uses parameters. Here,
params
is a commaseparated list of parameters:function [Geq,Gmv] = myEqConJacobian(X,U,data,params) function [Geq,Gmv,Ge] = myIneqConJacobian(X,U,e,data,params)
The input arguments of the constraint Jacobian functions are the same as the inputs of their respective custom constraint functions. This table describes the outputs of the Jacobian functions, where:
N_{x} is the number of states and is equal to the
Dimensions.NumberOfStates
property of the controller.N_{mv} is the number of manipulated variables.
N_{c} is the number of constraints (either equality or inequality constraints, depending on the constraint function).
p is the prediction horizon.
Argument  Description 

G  Jacobian of the equality or inequality constraints with respect to the state
trajectories, returned as a
pbyN_{x}byN_{c}
array, where $$\text{G}\left(i,j,l\right)=\partial \text{c}\left(l\right)/\partial \text{X}\left(i+1,j\right)$$. Compute G based on X from
the second row to row p+1, ignoring the first row. 
Gmv  Jacobian of the equality or inequality constraints with respect to the
manipulated variable trajectories, returned as a
pbyN_{mv}byN_{c}
array, where $$\text{Gmv}\left(i,j,l\right)=\partial \text{c}\left(l\right)/\partial \text{U}\left(i,MV\left(j\right)\right)$$ and MV(j) is the
jth MV index in
Since the controller forces

Ge  Jacobian of the inequality constraints with respect to the slack variable,
e , returned as a row vector of length
N_{c}, where $$\text{Ge}\left(l\right)=\partial \text{c}\left(l\right)/\partial \text{e}$$ 
To use output variable Jacobians in your constraint Jacobian functions, you must first
derive them from the state and input arguments using the Jacobian of the prediction model
output function, as specified in the Jacobian.OutputFcn
property of the
controller. For example, to compute the output variable Jacobians Yjacob
from time k to time k+p,
use:
p = data.PredictionHorizon; for i=1:p+1 Y(i,:) = myOutputFunction(X(i,:)',U(i,:)',params)'; end for i=1:p+1 Yjacob(i,:) = myOutputJacobian(X(i,:)',U(i,:)',params)'; end
Since prediction model output functions do not support direct feedthrough from inputs to
outputs, the output function Jacobian contains partial derivatives with respect to only the
states in X
. For more information on the output function Jacobian, see
Specify Prediction Model for Nonlinear MPC.
To find the Jacobians, compute the partial derivatives of the constraint functions with respect to the state trajectories, manipulated variable trajectories, and slack variable. For example, suppose that your constraint function is as follows, where u_{1} is the first manipulated variable.
$$\begin{array}{l}2{x}_{1}^{2}3{x}_{2}10\le 0\\ {u}_{1}^{2}5\le 0\end{array}$$
To compute the Jacobian with respect to the state trajectories, use:
Nx = data.NumOfStates; Nc = 2*p; G = zeros(p,Nx,Nc); G(1:p,2,1:p) = diag(2*X1  3);
To compute the Jacobian with respect to the manipulated variable trajectories, use:
Nmv = length(data.MVIndex); Gmv = zeros(p,Nmv,Nc); Gmv(1:p,1,p+1:2*p) = diag(2*u(1:p,data.MVIndex(1)));
In this case, the derivative with respect to the slack variable is Ge =
zeros(20,1)
.
Note
For multistage nonlinear MPC, you can automatically generate a stage constraint
Jacobian function using generateJacobianFunction
.
Passivity Constraints
You can specify passivity inequality constraints for a general nonlinear MPC controller
(multistage MPC controllers do not support passivity constraints). To use passivity
constraints, set these properties of your nlmpc
object as follows:
Passivity.EnforceConstraint
—true
Passivity.OutputPassivityIndex
— A desired nonnegative scalarPassivity.InputPassivityIndex
— A desired nonnegative scalarPassivity.OutputFcn
— Name of the desired passivity output function y_{p}(x,u)Passivity.InputFcn
— Name of the desired passivity input function u_{p}(x,u)
When your nonlinear MPC controller is configured to use passivity constraints, at each step the optimization algorithm tries to enforce the inequality constraint:
$${y}_{p}{(x,u)}^{T}{u}_{p}(x,u)\text{\hspace{0.17em}}+{\nu}_{y}\text{\hspace{0.17em}}{y}_{p}{(x,u)}^{T}{y}_{p}(x,u)+{\nu}_{u}\text{\hspace{0.17em}}{u}_{p}{(x,u)}^{T}{u}_{p}(x,u)\le \text{\hspace{0.17em}}0$$.
Here, ν_{y} is the output passivity index, ν_{u} is the input passivity index, u_{p}(x,u) is the passivity input function, and y_{p}(x,u) is the passivity output function. The variables x and u are the current state and input of the prediction model.
Assuming that the plant is already passive with respect to the inputoutput pair u_{p} and y_{p}, if these two inequalities are verified, then (under mild conditions) the resulting closed loop system tends to dissipate energy over time, and therefore has a stable equilibrium. For more information on passivity in the context of linear systems, see About Passivity and Passivity Indices.
To improve computational efficiency, you can specify analytical Jacobians for your
passivity constraint functions. To do so, specify the
Passivity.OutputJacobianFcn
and
Passivity.InputJacobianFcn
properties.
You can specify the passivity functions and their Jacobians as one of the following:
Name of a function in the current working folder or on the MATLAB path, specified as a string or character vector.
Handle to a local function, or a function defined in the current working folder or on the MATLAB path. For more information on local functions, see Local Functions.
Anonymous function. For more information on anonymous functions, see Anonymous 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, output, cost, or constraint functions (or their Jacobians) as local or anonymous functions is not recommended.
The passivity functions and their Jacobians must accept as first and second input
arguments the current state and input of the prediction model, respectively. After the first
two input arguments, you can also pass an optional comma separated list of parameters (for
example p1,p2,p3
) that might be needed by the function you
specify.
If any of your functions use optional parameters, you must specify the number of
parameters using Model.NumberOfParameters
. At run time, in Simulink, you then pass these parameters to the Nonlinear MPC Controller block. In MATLAB, you pass the parameters to a simulation function (such as nlmpcmove
, using
an nlmpcmoveopt
option
set object).
The function specified in Passivity.OutputJacobianFcn
(if any) must
return as a first output argument the Jacobian matrix of the output passivity function with
respect to the current state (an
N_{yp}byN_{x}
matrix) and as a second output argument the Jacobian matrix of the output passivity function
with respect to the manipulated variables (an
N_{yp} by
N_{mv} matrix).
Similarly, the function specified in Passivity.InputJacobianFcn
(if
any) must return as a first output argument the Jacobian of the input passivity function
with respect to the current state (an
N_{up}byN_{x}
matrix) and as a second output argument the Jacobian of the input passivity function with
respect to the manipulated variables (an
N_{up} by
N_{mv} matrix).
Here, N_{x} is the number of state variables of the prediction model, N_{mv} is the number of manipulated variables, N_{yp} is the number of outputs of the passivity output function, and N_{up} is the number of outputs of the passivity input function.
For more detail, see the Passivity
property of nlmpc
. For
examples, see Control QuadrupleTank Using PassivityBased Nonlinear MPC and Control Robot Manipulator Using PassivityBased Nonlinear MPC.
See Also
Functions
Objects
Blocks
Related Examples
 Control of Quadrotor Using Nonlinear Model Predictive Control
 Control QuadrupleTank Using PassivityBased Nonlinear MPC