Documentation |
Create MPC controller
MPCobj = mpc(plant)
MPCobj=mpc(plant,Ts)
MPCobj = mpc(plant,ts,p,m,W,MV,OV,DV)
MPCobj=mpc(models,ts,p,m,W,MV,OV,DV)
MPCobj = mpc(plant) creates a Model Predictive Controller object based on a discrete-time prediction model. The prediction model plant can be either an LTI model with a specified sampling period, or an object in System Identification Toolbox™ format (see Identify Plant from Data). The controller, MPCobj, inherits its control interval from plant.Ts, and its time unit from plant.TimeUnit. All other controller properties are default values. Once you have created the MPC controller, you can set its properties using MPCobj.Property = Value.
MPCobj=mpc(plant,Ts) sets the control interval to Ts. In this case, plant may be any valid LTI model or a System Identification Toolbox model. If plant is a discrete-time LTI model with an unspecified sampling period (plant.Ts = –1), it inherits sampling period Ts when used for predictions.
MPCobj = mpc(plant,ts,p,m,W,MV,OV,DV) specifies the prediction horizon p, and control horizon m. You can also provide a structure W of input, input increments, and output weights. You can also specify limits on manipulated variables (MV) and output variables (OV), as well as equal concern relaxation values, units, etc. Names and units of input disturbances can be also specified in the optional input DV. If any of these values are omitted or empty, the default values apply.
MPCobj=mpc(models,ts,p,m,W,MV,OV,DV) sets, in addition to the plant model, all other model properties used by the controller, e.g., disturbance and measurement noise models and the nominal values at which the models were obtained.
plant |
Plant model to be used in predictions, specified as an LTI model (tf, ss, or zpk) or a System Identification Toolbox model. If the Ts input argument is unspecified, plant must be a discrete-time LTI object with a specified sampling time, or a System Identification Toolbox model. Unless you specify otherwise, controller design assumes that all plant inputs are manipulated variables and all plant outputs are measured. Use the setmpcsignals command or the LTI InputGroup and OutputGroup properties to designate other signal types. |
Ts |
Controller sampling period (control interval), specified as a positive scalar value. |
p |
Prediction horizon, specified as a positive integer. |
m |
Control horizon, specified as a scalar integer, 1 ≤ m ≤ p, or as a vector of blocking factors such that sum(m) ≤ p. |
W |
Controller tuning weights, specified as a structure. For details about how to specify this structure, see Weights. |
MV |
Bounds and other properties of manipulated variables, specified as a 1-by-nu structure array, where nu is the number of manipulated variable inputs defined in the plant model. For details about how to specify this structure, see ManipulatedVariables. |
OV |
Bounds and other properties of the output variables, specified as a 1-by-ny structure array, where ny is the number of output variables defined in the plant model. For details about how to specify this structure, see OutputVariables. |
DV |
Scale factors and other properties of the disturbance inputs, specified as a 1-by-nd structure array, where nd is the number of disturbance inputs (measured + unmeasured) defined in the plant model. For details about how to specify this structure, see DisturbanceVariables. |
models |
To minimize computational overhead, Model Predictive Controller creation occurs in two phases. The first happens at construction when you invoke the mpc command, or when you change a controller property. Construction involves simple validity and consistency checks, such as signal dimensions, non-negativity of weights, etc.
The second phase is initialization, when you use the object for the first time in a simulation or analytical procedure. Initialization computes all constant properties required for efficient numerical performance, such as matrices defining the optimal control problem and state estimator gains. Additional, diagnostic checks occur during initialization, such as verification that the controller states are observable.
By default, both phases display informative messages in the command window. You can turn these on or off using the mpcverbosity command.
All the parameters defining the traditional (implicit) MPC control law (prediction horizon, weights, constraints, etc.) are stored in an MPC object, whose properties are listed in the following table.
MPC Controller Object
Property | Description |
---|---|
ManipulatedVariables (or MV or Manipulated or Input ) | Scale factors, input and input-rate upper and lower bounds, corresponding ECR values, target values, signal names and units. |
OutputVariables (or OV or Controlled or Output ) | Scale factors, input and input-rate upper and lower bounds, corresponding ECR values, target values, signal names and units. |
DisturbanceVariables (or DV or Disturbance ) | Disturbance scale factors, names, and units |
Weights | Weights used in computing the performance (cost) function |
Model | Plant, input disturbance, and output noise models, and nominal conditions. |
Ts | Controller's sampling time |
Optimizer | Parameters controlling the QP solver |
PredictionHorizon | Prediction horizon |
ControlHorizon | Number of free control moves or vector of blocking moves |
History | Creation time |
Notes | Text or comments about the MPC controller object |
UserData | Any additional data |
MPCData (private) | Matrices for the QP problem and other accessorial data |
Version (private) | Model Predictive Control Toolbox version number |
ManipulatedVariables (or MV or Manipulated or Input) is an n_{u}-dimensional array of structures (n_{u} = number of manipulated variables), one per manipulated variable. Each structure has the fields described in the following table, where p denotes the prediction horizon. Unless indicated otherwise, numerical values are in engineering units.
Structure ManipulatedVariables
Field Name | Content | Default |
---|---|---|
ScaleFactor | Non-negative scale factor for this MV | 1 |
Min | 1 to p length vector of lower bounds on this MV | -Inf |
Max | 1 to p length vector of upper bounds on this MV | Inf |
MinECR | 1 to p length vector of nonnegative parameters specifying the Min bound softness (0 = hard). | 0 (dimensionless) |
MaxECR | 1 to p length vector of nonnegative parameters specifying the Max bound softness (0 = hard). | 0 (dimensionless) |
Target | 1 to p length vector of target values for this MV | 'nominal' |
RateMin | 1 to p length vector of lower bounds on the interval-to-interval change for this MV | -Inf if problem is unconstrained, otherwise -10 |
RateMax | 1 to p length vector of upper bounds on the interval-to-interval change for this MV | Inf |
RateMinECR | 1 to p length vector of nonnegative parameters specifying the RateMin bound softness (0 = hard). | 0 (dimensionless) |
RateMaxECR | 1 to p length vector of nonnegative parameters specifying the RateMax bound softness (0 = hard). | 0 (dimensionless) |
Name | Read-only MV signal name (character string) | InputName of LTI plant model |
Units | Read-only MV signal units (character string) | InputUnit of LTI plant model |
Note Rates refer to the difference Δu(k)=u(k)-u(k-1). Constraints and weights based on derivatives du/dt of continuous-time input signals must be properly reformulated for the discrete-time difference Δu(k), using the approximation du/dt ≅ Δu(k)/T_{s}. |
OutputVariables (or OV or Controlled or Output) is an n_{y}-dimensional array of structures (n_{y} = number of outputs), one per output signal. Each structure has the fields described in the following table. p denotes the prediction horizon. Unless specified otherwise, values are in engineering units.
Structure OutputVariables
Field Name | Content | Default |
---|---|---|
ScaleFactor | Non-negative scale factor for this OV | 1 |
Min | 1 to p length vector of lower bounds on this OV | -Inf |
Max | 1 to p length vector of upper bounds on this OV | Inf |
MinECR | 1 to p length vector of nonnegative parameters specifying the Min bound softness (0 = hard). | 1 (dimensionless) |
MaxECR | 1 to p length vector of nonnegative parameters specifying the Max bound softness (0 = hard). | 1 (dimensionless) |
Name | Read-only OV signal name (character string) | OutputName of LTI plant model |
Units | Read-only OV signal units (character string) | OutputUnit of LTI plant model |
Integrator | Magnitude of integrated white noise on the output channel (0 = no integrator) | [] |
In order to reject constant disturbances due for instance to gain nonlinearities, the default output disturbance model used in Model Predictive Control Toolbox™ software is a collection of integrators driven by white noise on measured outputs (see Output Disturbance Model). By default, OutputVariables.Integrators is empty on all outputs. This specifies that the default behavior applies to each output variable.
DisturbanceVariables (or DV or Disturbance) is an (n_{v}+n_{d})-dimensional array of structures (n_{v} = number of measured input disturbances, n_{d} = number of unmeasured input disturbances), one per input disturbance. Each structure has the fields described in the following table.
Structure DisturbanceVariables
Field Name | Content | Default |
---|---|---|
ScaleFactor | Non-negative scale factor for this DV | 1 |
Name | Read-only DV signal name (character string) | InputName of LTI plant model |
Units | Read-only DV signal units (character string) | InputUnit of LTI plant model |
The order of the disturbance signals within the array DisturbanceVariables is the following: the first n_{v} entries relate to measured input disturbances, the last n_{d} entries relate to unmeasured input disturbances.
Weights is the structure defining the QP weighting matrices. It contains four fields. The values of these fields depend on whether you are using the standard quadratic cost function (see Standard Cost Function) or the alternative cost function (see Alternative Cost Function).
The table below lists the content of the four fields. In the table, p denotes the prediction horizon, n_{u} the number of manipulated variables, n_{y} the number of output variables.
For the MV, MVRate and OV weights, if you specify fewer than p rows, the last row repeats automatically to form a matrix containing p rows.
Weights for the Standard Cost Function (MATLAB Structure)
Field Name | Content | Default |
---|---|---|
ManipulatedVariables (or MV or Manipulated or Input) | (1 to p)-by-n_{u} dimensional array of nonnegative MV weights | zeros(1,nu) |
ManipulatedVariablesRate (or MVRate or ManipulatedRate or InputRate) | (1 to p)-by-n_{u} dimensional array of of MV-increment weights | 0.1*ones(1,nu) |
OutputVariables (or OV or Controlled or Output) | (1 to p)-by-n_{y} dimensional array of OV weights | 1 (The default for output weights is the following: if n_{u}≥n_{y}, all outputs are weighted with unit weight; if n_{u}<n_{y}, n_{u} outputs default to 1 (with preference given to measured outputs), and the rest default to 0. |
ECR | Scalar weight on the slack variable ɛ used for constraint softening | 1e5*(max weight) |
Note If all MVRate weights are strictly positive, the resulting QP problem is strictly convex. If some MVRate weights are zero, the QP Hessian might be positive semidefinite. In order to keep the QP problem strictly convex, when the condition number of the Hessian matrix K_{ΔU} is larger than 10^{12}, the quantity 10*sqrt(eps) is added to each diagonal term. See Cost Function. |
You can specify off-diagonal Q and R weight matrices in the cost function. To accomplish this, you must define the fields ManipulatedVariables, ManipulatedVariablesRate, and OutputVariables as cell arrays, each containing a single positive-semi-definite matrix of the appropriate size. Specifically, OutputVariables must be a cell array containing the n_{y}-by-n_{y} Q matrix, ManipulatedVariables must be a cell array containing the n_{u}-by-n_{u} R_{u} matrix, and ManipulatedVariablesRate must be a cell array containing the n_{u}-by-n_{u} R_{Δ}_{u} matrix (see Alternative Cost Function) and the mpcweightsdemo example). You can abbreviate the field names as shown in Weights. You can also use diagonal weights (as defined in Weights) for one or more of these fields. If you omit a field, the object constructor uses the defaults shown in Weights.
For example, you can specify off-diagonal weights, as follows
MPCobj.Weights.OutputVariables = {Q}; MPCobj.Weights.ManipulatedVariables = {Ru}; MPCobj.Weights.ManipulatedVariablesRate = {Rdu};
where Q = Q. Ru=R_{u}, and Rdu = R_{Δ}_{u} are positive semidefinite matrices.
Note You cannot specify non-diagonal weights that vary at each prediction horizon step. The same Q, Ru, and Rdu weights apply at each step. |
The property Model specifies plant, input disturbance, and output noise models, and nominal conditions, according to the model setup described in Controller State Estimation. It is a 1-D structure containing the following fields.
Structure Model Describing the Models Used by MPC
Field Name | Content | Default |
---|---|---|
Plant | LTI model or identified linear model of the plant | No default |
Disturbance | LTI model describing color of unmeasured input disturbances | Integrated white noise generating each such plant disturbance input (unless this violates controller state observability). |
Noise | LTI model describing color of plant output measurement noise | Unit white noise on each measured output = identity static gain |
Nominal | Structure containing the state, input, and output values where Model.Plant is linearized |
Note Direct feedthrough from manipulated variables to any output in Model.Plant is not allowed. See MPC Modeling. |
Specify input and output signal types via the InputGroup and OutputGroup properties of Model.Plant, or, more conveniently, use the setmpcsignals command. Valid signal types are listed in the following tables.
Input Groups in Plant Model
Name | Value |
---|---|
ManipulatedVariables (or MV or Manipulated or Input) | Indices of manipulated variables in Model.Plant |
MeasuredDisturbances (or MD or Measured) | Indices of measured disturbances in Model.Plant |
UnmeasuredDisturbances (or UD or Unmeasured) | Indices of unmeasured disturbances in Model.Plant |
Output Groups in Plant Model
Name | Value |
---|---|
MeasuredOutputs (or MO or Measured) | Indices of measured outputs in Model.Plant |
UnmeasuredOutputs (or UO or Unmeasured) | Indices of unmeasured outputs in Model.Plant |
By default, all Model.Plant inputs are manipulated variables, and all outputs are measured.
The structure Nominal contains the values (in engineering units) for states, inputs, outputs and state derivatives/differences at the operating point where Model.Plant applies, which is typically a linearization point. was linearized. The fields are reported in the following table (see also MPC Modeling).
Nominal Values at Operating Point
Field | Description | Default |
---|---|---|
X | Plant state at operating point | 0 |
U | Plant input at operating point, including manipulated variables, measured and unmeasured disturbances | 0 |
Y | Plant output at operating point | 0 |
DX | For continuous-time models, DX is the state derivative at operating point: DX=f(X,U). For discrete-time models, DX=x(k+1)-x(k)=f(X,U)-X. | 0 |
Sampling time of the MPC controller. By default, if Model.Plant is a discrete-time model, Ts = Model.Plant.ts. For continuous-time plant models, you must specify a controller Ts. Its measurement unit is inherited from Model.Plant.TimeUnit.
Parameters for the QP optimization. Optimizer is a structure with the fields reported in the following table.
Optimizer Properties
Field | Description | Default |
---|---|---|
MaxIter | Maximum number of iterations allowed in the QP solver | 200 |
Trace | On/off | 'off' |
Solver | QP solver used (only 'ActiveSet') | 'ActiveSet' |
MinOutputECR | Minimum positive value allowed for OutputMinECR and OutputMaxECR | 1e-10 |
MinOutputECR is a positive scalar used to specify the minimum allowed ECR for output constraints. If values smaller than MinOutputECR are provided in the OutputVariables property of the MPC objects, a warning message is issued and the value is raised to MinOutputECR.
PredictionHorizon is the integer number of prediction horizon steps. The control interval, Ts, determines the duration of each step. The default value is 10 + maximum intervals of delay (if any).
ControlHorizon is either a number of free control moves, or a vector of blocking moves (see Optimization Variables). The default value is 2.
History stores the time the MPC controller was created (read only).
Notes stores text or comments as a cell array of strings.
Any additional data stored within the MPC controller object.
MPCData is a private property of the MPC object used for storing intermediate operations, QP matrices, internal flags, etc.
Version is a private property indicating the Model Predictive Control Toolbox version number.
get | mpcprops | mpcverbosity | set | setmpcsignals