Option set for mpcmove
function
To specify options for the mpcmove
, mpcmoveAdaptive
, and mpcmoveMultiple
functions, use an mpcmoveopt
object.
Using this object, you can specify run-time values for a subset of controller properties,
such as tuning weights and constraints. If you do not specify a value for one of the
mpcmoveopt
properties, the value of the corresponding controller option
is used instead.
creates a default set
of options for the options
= mpcmoveoptmpcmove
function. To modify the property values,
use dot notation.
OutputWeights
— Output variable tuning weights[]
(default) | vector | arrayOutput variable tuning weights that replace the
Weights.OutputVariables
property of the controller at run time,
specified as a vector or array of nonnegative values.
To use the same weights across the prediction horizon, specify a row vector of length Ny, where Ny is the number of output variables.
To vary the tuning weights over the prediction horizon from time k+1 to time k+p, specify an array with Ny columns and up to p rows. Here, k is the current time and p is the prediction horizon. Each row contains the output variable tuning weights for one prediction horizon step. If you specify fewer than p rows, the weights in the final row are used for the remaining steps of the prediction horizon.
The format of OutputWeights
must match the format of the
Weights.OutputVariables
property of the controller object. For
example, you cannot specify constant weights across the prediction horizon in the
controller object, and then specify time-varying weights using
mpcmoveopt
.
MVWeights
— Manipulated variable tuning weights[]
(default) | vector | arrayManipulated variable tuning weights that replace the
Weights.ManipulatedVariables
property of the controller at run
time, specified as a vector or array of nonnegative values.
To use the same weights across the prediction horizon, specify a row vector of length Nmv, where Nmv is the number of manipulated variables.
To vary the tuning weights over the prediction horizon from time k to time k+p-1, specify an array with Nmv columns and up to p rows. Here, k is the current time and p is the prediction horizon. Each row contains the manipulated variable tuning weights for one prediction horizon step. If you specify fewer than p rows, the weights in the final row are used for the remaining steps of the prediction horizon.
The format of MVWeights
must match the format of the
Weights.ManipulatedVariables
property of the controller object. For
example, you cannot specify constant weights across the prediction horizon in the
controller object, and then specify time-varying weights using
mpcmoveopt
.
MVRateWeights
— Manipulated variable rate tuning weights[]
(default) | vector | arrayManipulated variable rate tuning weights that replace the
Weights.ManipulatedVariablesRate
property of the controller at run
time, specified as a vector or array of nonnegative values.
To use the same weights across the prediction horizon, specify a row vector of length Nmv, where Nmv is the number of manipulated variables.
To vary the tuning weights over the prediction horizon from time k to time k+p-1, specify an array with Nmv columns and up to p rows. Here, k is the current time and p is the prediction horizon. Each row contains the manipulated variable rate tuning weights for one prediction horizon step. If you specify fewer than p rows, the weights in the final row are used for the remaining steps of the prediction horizon.
The format of MVRateWeights
must match the format of the
Weights.ManipulatedVariablesRate
property of the controller object.
For example, you cannot specify constant weights across the prediction horizon in the
controller object, and then specify time-varying weights using
mpcmoveopt
.
ECRWeight
— Slack variable tuning weight[]
(default) | positive scalarSlack variable tuning weight that replaces the Weights.ECR
property of the controller at run time, specified as a positive scalar.
OutputMin
— Output variable lower bounds[]
(default) | row vector | matrixOutput variable lower bounds, specified as a row vector of length Ny or as a matrix with Ny columns, where Ny is the number of output variables.
If you did not specify the OutputVariables(i).Min
property of the
mpc
object, then specifying OutputMin
results in an error
when you execute mpcmove
.
To change the bounds over the prediction horizon from time k+1 to time k+p, specify a matrix with Ny columns and up to p rows. Here, Ny is the number of plant outputs, k is the current time, and p is the prediction horizon. Each row contains the bounds for one prediction horizon step. If you specify fewer than p rows, the bounds in the final row are used for the remaining steps of the prediction horizon.
OutputMin(:,i)
replaces the
OutputVariables(i).Min
property of the mpc
object at run time. The replacement behavior depends on the dimensions
of both variables.
Scalar OutputVariables(i).Min
in the mpc
object (a constant bound for the i
th plant output to be applied to
all prediction steps)
OutputMin Dimension | Replacement Behavior |
---|---|
Scalar OutputMin (single output, constant bound) | OutputMin replaces the constant bound defined in
OutputVariables(i).Min |
Column vector OutputMin (single output, time-varying
bound) | OutputMin replaces the constant bound defined in
OutputVariables(i).Min with a time-varying bound. |
Row vector OutputMin (multiple outputs, constant
bounds) | OutputMin(i) replaces the constant bound defined in
OutputVariables(i).Min |
Matrix OutputMin (multiple outputs, time-varying
bounds) | OutputMin(:,i) replaces the constant bound defined in
OutputVariables(i).Min with a time-varying bound. |
Vector OutputVariables(i).Min
in the mpc
object (a time-varying bound for the i
th plant output with
different values at different prediction steps)
OutputMin Dimension | Replacement Behavior |
---|---|
Scalar OutputMin (single output, constant bound) | OutputMin replaces the first finite entry
in OutputVariables.Min and the remaining entries in
OutputVariables.Min shift up or down with the same amount
of displacement to retain the profile defined by the original
OutputVariables.Min vector. |
Column vector OutputMin (single output, time-varying
bound) | OutputMin replaces the time-varying bound defined in
OutputVariables(i).Min , and the original bound profile is
discarded. |
Row vector OutputMin (multiple outputs, constant
bounds) | OutputMin(i) replaces the first finite entry
in OutputVariables(i).Min and the remaining entries in
OutputVariables(i).Min shift up or down with the same
amount of displacement to retain the profile defined by the original
OutputVariables(i).Min vector. |
Matrix OutputMin (multiple outputs, time-varying
bounds). | OutputMin(:,i) replaces the time-varying bound defined
in OutputVariables(i).Min , and the original bound profile is
discarded. |
OutputMax
— Output variable upper bounds[]
(default) | row vector | matrixOutput variable upper bounds, specified as a row vector of length Ny or as a matrix with Ny columns, where Ny is the number of output variables.
If you did not specify the OutputVariables(i).Max
property of the
mpc
object, then specifying OutputMax
results in an error
when you execute mpcmove
.
To change the bounds over the prediction horizon from time k+1 to time k+p, specify a matrix with Ny columns and up to p rows. Here, Ny is the number of plant outputs, k is the current time, and p is the prediction horizon. Each row contains the bounds for one prediction horizon step. If you specify fewer than p rows, the bounds in the final row are used for the remaining steps of the prediction horizon.
OutputMax(:,i)
replaces the
OutputVariables(i).Max
property of the mpc
object at run time. The replacement behavior depends on the dimensions
of both variables.
Scalar OutputVariables(i).Max
in the mpc
object (a constant bound for the i
th plant output to be applied to
all prediction steps)
OutputMax Dimension | Replacement Behavior |
---|---|
Scalar OutputMax (single output, constant bound) | OutputMax replaces the constant bound defined in
OutputVariables(i).Max |
Column vector OutputMax (single output, time-varying
bound) | OutputMax replaces the constant bound defined in
OutputVariables(i).Max with a time-varying bound. |
Row vector OutputMax (multiple outputs, constant
bounds) | OutputMax(i) replaces the constant bound defined in
OutputVariables(i).Max |
Matrix OutputMax (multiple outputs, time-varying
bounds) | OutputMax(:,i) replaces the constant bound defined in
OutputVariables(i).Max with a time-varying bound. |
Vector OutputVariables(i).Max
in the mpc
object (a time-varying bound for the i
th plant output with
different values at different prediction steps)
OutputMax Dimension | Replacement Behavior |
---|---|
Scalar OutputMax (single output, constant bound) | OutputMax replaces the first finite entry
in OutputVariables.Max and the remaining entries in
OutputVariables.Max shift up or down with the same amount
of displacement to retain the profile defined by the original
OutputVariables.Max vector. |
Column vector OutputMax (single output, time-varying
bound) | OutputMax replaces the time-varying bound defined in
OutputVariables(i).Max , and the original bound profile is
discarded. |
Row vector OutputMax (multiple outputs, constant
bounds) | OutputMax(i) replaces the first finite entry
in OutputVariables(i).Max and the remaining entries in
OutputVariables(i).Max shift up or down with the same
amount of displacement to retain the profile defined by the original
OutputVariables(i).Max vector. |
Matrix OutputMax (multiple outputs, time-varying
bounds). | OutputMax(:,i) replaces the time-varying bound defined
in OutputVariables(i).Max , and the original bound profile is
discarded. |
MVMin
— Manipulated variable lower bounds[]
(default) | row vector | matrixManipulated variable lower bounds, specified as a row vector of length Nmv or as a matrix with Nmv columns, where Nmv is the number of output variables.
If you did not specify the ManipulatedVariables(i).Min
property
of the mpc
object, then specifying
MVMin
results in an error when you execute mpcmove
.
To change the bounds over the prediction horizon from time k to time k+p-1, specify a matrix with Nmv columns and up to p rows. Here, Nmv is the number of manipulated variables, k is the current time, and p is the prediction horizon. Each row contains the bounds for one prediction horizon step. If you specify fewer than p rows, the bounds in the final row are used for the remaining steps of the prediction horizon.
MVMin(:,i)
replaces the
ManipulatedVariables(i).Min
property of the mpc
object at run time. The replacement behavior depends on the dimensions
of both variables.
Scalar ManipulatedVariables(i).Min
in the mpc
object (a constant bound for the i
th manipulated variable to be
applied to all prediction steps)
MVMin Dimension | Replacement Behavior |
---|---|
Scalar MVMin (single output, constant bound) | MVMin replaces the constant bound defined in
ManipulatedVariables(i).Min |
Column vector MVMin (single output, time-varying
bound) | MVMin replaces the constant bound defined in
ManipulatedVariables(i).Min with a time-varying
bound. |
Row vector MVMin (multiple outputs, constant
bounds) | MVMin(i) replaces the constant bound defined in
ManipulatedVariables(i).Min |
Matrix MVMin (multiple outputs, time-varying
bounds) | MVMin(:,i) replaces the constant bound defined in
ManipulatedVariables(i).Min with a time-varying
bound. |
Vector ManipulatedVariables(i).Min
in the mpc
object (a time-varying bound for the i
th manipulated variable with
different values at different prediction steps)
MVMin Dimension | Replacement Behavior |
---|---|
Scalar MVMin (single output, constant bound) | MVMin replaces the first finite entry
in ManipulatedVariables.Min and the remaining entries in
ManipulatedVariables.Min shift up or down with the same
amount of displacement to retain the profile defined by the original
ManipulatedVariables.Min vector. |
Column vector MVMin (single output, time-varying
bound) | MVMin replaces the time-varying bound defined in
ManipulatedVariables(i).Min , and the original bound profile
is discarded. |
Row vector MVMin (multiple outputs, constant
bounds) | MVMin(i) replaces the first finite entry
in ManipulatedVariables(i).Min and the remaining entries in
ManipulatedVariables(i).Min shift up or down with the same
amount of displacement to retain the profile defined by the original
ManipulatedVariables(i).Min vector. |
Matrix MVMin (multiple outputs, time-varying
bounds). | MVMin(:,i) replaces the time-varying bound defined in
ManipulatedVariables(i).Min , and the original bound profile
is discarded. |
MVMax
— Manipulated variable upper bounds[]
(default) | row vector | matrixManipulated variable upper bounds, specified as a row vector of length Nmv or as a matrix with Nmv columns, where Nmv is the number of output variables.
If you did not specify the ManipulatedVariables(i).Max
property
of the mpc
object, then specifying
MVMax
results in an error when you execute mpcmove
.
To change the bounds over the prediction horizon from time k to time k+p-1, specify a matrix with Nmv columns and up to p rows. Here, Nmv is the number of manipulated variables, k is the current time, and p is the prediction horizon. Each row contains the bounds for one prediction horizon step. If you specify fewer than p rows, the bounds in the final row are used for the remaining steps of the prediction horizon.
MVMax(:,i)
replaces the
ManipulatedVariables(i).Max
property of the mpc
object at run time. The replacement behavior depends on the dimensions
of both variables.
Scalar ManipulatedVariables(i).Max
in the mpc
object (a constant bound for the i
th manipulated variable to be
applied to all prediction steps)
MVMax Dimension | Replacement Behavior |
---|---|
Scalar MVMax (single output, constant bound) | MVMax replaces the constant bound defined in
ManipulatedVariables(i).Max |
Column vector MVMax (single output, time-varying
bound) | MVMax replaces the constant bound defined in
ManipulatedVariables(i).Max with a time-varying
bound. |
Row vector MVMax (multiple outputs, constant
bounds) | MVMax(i) replaces the constant bound defined in
ManipulatedVariables(i).Max |
Matrix MVMax (multiple outputs, time-varying
bounds) | MVMax(:,i) replaces the constant bound defined in
ManipulatedVariables(i).Max with a time-varying
bound. |
Vector ManipulatedVariables(i).Max
in the mpc
object (a time-varying bound for the i
th manipulated variable with
different values at different prediction steps)
MVMax Dimension | Replacement Behavior |
---|---|
Scalar MVMax (single output, constant bound) | MVMax replaces the first finite entry
in ManipulatedVariables.Max and the remaining entries in
ManipulatedVariables.Max shift up or down with the same
amount of displacement to retain the profile defined by the original
ManipulatedVariables.Max vector. |
Column vector MVMax (single output, time-varying
bound) | MVMax replaces the time-varying bound defined in
ManipulatedVariables(i).Max , and the original bound profile
is discarded. |
Row vector MVMax (multiple outputs, constant
bounds) | MVMax(i) replaces the first finite entry
in ManipulatedVariables(i).Max and the remaining entries in
ManipulatedVariables(i).Max shift up or down with the same
amount of displacement to retain the profile defined by the original
ManipulatedVariables(i).Max vector. |
Matrix MVMax (multiple outputs, time-varying
bounds). | MVMax(:,i) replaces the time-varying bound defined in
ManipulatedVariables(i).Max , and the original bound profile
is discarded. |
CustomConstraint
— Custom mixed input/output constraints[]
(default) | structureCustom mixed input/output constraints, specified as a structure with the following
fields. These constraints replace the mixed input/output constraints previously set
using setconstraint
.
E
— Manipulated variable constraint constantManipulated variable constraint constant, specified as an Nc-by-Nmv array, where Nc is the number of constraints, and Nmv is the number of manipulated variables.
F
— Controlled output constraint constantControlled output constraint constant, specified as an Nc-by-Ny array, where Ny is the number of controlled outputs (measured and unmeasured).
G
— Mixed input/output constraint constantMixed input/output constraint constant, specified as a column vector of length Nc.
S
— Measured disturbance constraint constantMeasured disturbance constraint constant, specified as an Nc-by-Nmd array, where Nmd is the number of measured disturbances.
OnlyComputeCost
— Flag indicating whether to calculate the optimal control sequence0
(default) | 1
Flag indicating whether to calculate the optimal control sequence, specified as one of the following:
0
— Controller returns the predicted optimal control moves in
addition to the objective function cost value.
1
— Controller returns the objective function cost only,
which saves computational effort.
MVused
— Manipulated variable values used in the plant during the previous control interval[]
(default) | row vectorManipulated variable values used in the plant during the previous control interval,
specified as a row vector of length Nmv, where
Nmv is the number of manipulated
variables. If you do not specify MVused
, the
mpvmove
uses the LastMove
property of its
current controller state input argument, x
.
MVTarget
— Manipulated variable targets[]
(default) | row vectorManipulated variable targets, specified as a row vector of length
Nmv, where
Nmv is the number of manipulated
variables. MVTarget(i)
replaces the
ManipulatedVariables(i).Target
property of the controller at run
time.
PredictionHorizon
— Prediction horizon[]
(default) | positive integerPrediction horizon, which replaces the PredictionHorizon
property
of the controller at run time, specified as a positive integer. If you specify
PredictionHorizon
, you must also specify
ControlHorizon
.
Specifying PredictionHorizon
changes the:
Number of rows in the optimal sequences returned by the
mpcmove
and mpcmoveAdaptive
functions
Maximum dimensions of the Plant
and
Nominal
input arguments of
mpcmoveAdaptive
This parameter is ignored by the mpcmoveMultiple
function.
ControlHorizon
— Control horizon[]
(default) | positive integer | vector of positive integersControl horizon, which replaces the ControlHorizon
property of
the controller at run time, specified as one of the following:
Positive integer, m, between 1
and
p, inclusive, where p is equal to
PredictionHorizon
. In this case, the controller computes
m free control moves occurring at times k
through k+m-1, and holds the controller output
constant for the remaining prediction horizon steps from
k+m through
k+p-1. Here, k is the
current control interval. For optimal trajectory planning set m
equal to p.
Vector of positive integers, [m1,
m2, …], where the sum of the integers
equals the prediction horizon, p. In this case, the controller
computes M blocks of free moves, where M is
the length of the ControlHorizon
vector. The first free move
applies to times k through
k+m1-1, the second
free move applies from time
k+m1 through
k+m1+m2-1,
and so on. Using block moves can improve the robustness of your controller compared
to the default case.
If you specify ControlHorizon
, you must also specify
PredictionHorizon
.
This parameter is ignored by the mpcmoveMultiple
function.
mpcmove | Compute optimal control action |
mpcmoveAdaptive | Compute optimal control with prediction model updating |
mpcmoveMultiple | Compute gain-scheduling MPC control action at a single time instant |
Vary a manipulated variable upper bound during a simulation.
Define the plant, which includes a 4-second input delay. Convert to a delay-free, discrete, state-space model using a 2-second control interval. Create the corresponding default controller, and specify MV bounds at +/-2.
Ts = 2;
Plant = absorbDelay(c2d(ss(tf(0.8,[5 1],'InputDelay',4)),Ts));
MPCobj = mpc(Plant,Ts);
-->The "PredictionHorizon" property of "mpc" object is empty. Trying PredictionHorizon = 10. -->The "ControlHorizon" property of the "mpc" object is empty. Assuming 2. -->The "Weights.ManipulatedVariables" property of "mpc" object is empty. Assuming default 0.00000. -->The "Weights.ManipulatedVariablesRate" property of "mpc" object is empty. Assuming default 0.10000. -->The "Weights.OutputVariables" property of "mpc" object is empty. Assuming default 1.00000.
MPCobj.MV(1).Min = -2; MPCobj.MV(1).Max = 2;
Create an empty mpcmoveopt
object. During simulation, you can set properties of the object to specify controller parameters.
options = mpcmoveopt;
Pre-allocate storage and initialize the controller state.
v = []; t = [0:Ts:20]; N = length(t); y = zeros(N,1); u = zeros(N,1); x = mpcstate(MPCobj);
-->Assuming output disturbance added to measured output channel #1 is integrated white noise. -->The "Model.Noise" property of the "mpc" object is empty. Assuming white noise on each measured output channel.
Use mpcmove
to simulate the following:
Reference (setpoint) step change from initial condition r = 0 to r = 1 (servo response)
MV upper bound step decrease from 2 to 1, occurring at t = 10
r = 1; for i = 1:N y(i) = Plant.C*x.Plant; if t(i) >= 10 options.MVMax = 1; end [u(i),Info] = mpcmove(MPCobj,x,y(i),r,v,options); end
As the loop executes, the value of options.MVMax
is reset to 1 for all iterations that occur after t = 10. Prior to that iteration, options.MVMax
is empty. Therefore, the controller's value for MVMax
is used, MPCobj.MV(1).Max = 2
.
Plot the results of the simulation.
[Ts,us] = stairs(t,u); plot(Ts,us,'b-',t,y,'r-') legend('MV','OV') xlabel(sprintf('Time, %s',Plant.TimeUnit))
From the plot, you can observe that the original MV upper bound is active until t = 4. After the input delay of 4 seconds, the output variable (OV) moves smoothly to its new target of r = 1. reaching the target at t = 10. The new MV bound imposed at t = 10 becomes active immediately. This forces the OV below its target, after the input delay elapses.
Now assume that you want to impose an OV upper bound at a specified location relative to the OV target. Consider the following constraint design command:
MPCobj.OV(1).Max = [Inf,Inf,0.4,0.3,0.2];
This is a horizon-varying constraint. The known input delay makes it impossible for the controller to satisfy an OV constraint prior to the third prediction-horizon step. Therefore, a finite constraint during the first two steps would be poor practice. For illustrative purposes, the previous constraint also decreases from 0.4 at step 3 to 0.2 at step 5 and thereafter.
The following commands produce the same results shown in the previous plot. The OV constraint is never active because it is being varied in concert with the setpoint, r.
x = mpcstate(MPCobj);
-->Assuming output disturbance added to measured output channel #1 is integrated white noise. -->The "Model.Noise" property of the "mpc" object is empty. Assuming white noise on each measured output channel.
OPTobj = mpcmoveopt; for i = 1:N y(i) = Plant.C*x.Plant; if t(i) >= 10 OPTobj.MVMax = 1; end OPTobj.OutputMax = r + 0.4; [u(i),Info] = mpcmove(MPCobj,x,y(i),r,v,OPTobj); end
The scalar value r + 0.4 replaces the first finite value in the MPCobj.OV(1).Max
vector, and the remaining finite values adjust to maintain the original profile, that is, the numerical difference between these values is unchanged. r = 1 for the simulation, so the previous use of the mpcmoveopt
object is equivalent to the command
MPCobj.OV(1).Max = [Inf, Inf, 1.4, 1.3, 1.2];
However, using the mpcmoveopt
object involves much less computational overhead.
If a variable is unconstrained in the initial controller design, you cannot constrain
it using mpcmoveopt
. The controller ignores any such
specifications.
You cannot remove a constraint from a variable that is constrained in the initial controller design. However, you can change it to a large (or small) value such that it is unlikely to become active.
mpc
| mpcmove
| setconstraint
| setterminal
You have a modified version of this example. Do you want to open this example with your edits?