mpcmoveopt

Option set for mpcmove function

expand all in page

Description

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.

Creation

Syntax

options = mpcmoveopt

Description

example

options = mpcmoveopt creates a default set of options for the mpcmove function. To modify the property values, use dot notation.

Properties

expand all

Output 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.

Manipulated 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.

Manipulated 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.

Slack variable tuning weight that replaces the Weights.ECR property of the controller at run time, specified as a positive scalar.

Output variable lower bounds, specified as a row vector of length Ny, where Ny is the number of output variables. OutputMin(i) replaces the OutputVariables(i).Min property of the controller at run time.

If the OutputVariables(i).Min property of the controller is specified as a vector (that is, the constraint varies over the prediction horizon), OutputMin(i) replaces the first finite entry in this vector, and the remaining values shift to retain the same constraint profile.

Output variable upper bounds, specified as a row vector of length Ny, where Ny is the number of output variables. OutputMax(i) replaces the OutputVariables(i).Max property of the controller at run time.

If the OutputVariables(i).Max property of the controller is specified as a vector (that is, the constraint varies over the prediction horizon), OutputMax(i) replaces the first finite entry in this vector, and the remaining values shift to retain the same constraint profile.

Manipulated variable lower bounds, specified as a row vector of length Nmv , where Nmv is the number of manipulated variables. MVMin(i) replaces the ManipulatedVariables(i).Min property of the controller at run time.

If the ManipulatedVariables(i).Min property of the controller is specified as a vector (that is, the constraint varies over the prediction horizon), MVMin(i) replaces the first finite entry in this vector, and the remaining values shift to retain the same constraint profile.

Manipulated variable upper bounds, specified as a row vector of length Nmv, where Nmv is the number of manipulated variables. MVMax(i) replaces the ManipulatedVariables(i).Max property of the controller at run time.

If the ManipulatedVariables(i).Max property of the controller is specified as a vector (that is, the constraint varies over the prediction horizon), MVMax(i) replaces the first finite entry in this vector, and the remaining values shift to retain the same constraint profile.

Custom mixed input/output constraints, specified as a structure with the following fields. These constraints replace the mixed input/output constraints previously set using setconstraint.

Manipulated 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.

Controlled output constraint constant, specified as an Nc-by-Ny array, where Ny is the number of controlled outputs (measured and unmeasured).

Mixed input/output constraint constant, specified as a column vector of length Nc.

Measured disturbance constraint constant, specified as an Nc-by-Nmd array, where Nmd is the number of measured disturbances.

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.

Manipulated 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.

Manipulated 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.

Prediction 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.

Control 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.

Object Functions

mpcmoveCompute optimal control action
mpcmoveAdaptiveCompute optimal control with prediction model updating
mpcmoveMultipleCompute gain-scheduling MPC control action at a single time instant

Examples

collapse all

Open Live Script

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.

Tips

  • 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.

See Also

| | |

Introduced in R2018b

Model Predictive Control Toolbox Documentation
Support