mpcmove

Compute optimal control action and update controller states

Syntax

mv = mpcmove(mpcobj,xc,ym,r,v)

[mv,info] = mpcmove(mpcobj,xc,ym,r,v)

[___] = mpcmove(___,options)

mv = mpcmove(ddobj,xc,uk1,yk1,r)

[mv,info] = mpcmove(mpcobj,xc,uk1,yk1,r)

[___] = mpcmove(___,MVTarget=dataUref)

Description

Use this command to simulate an MPC controller in closed-loop with a plant model. Call mpcmove repeatedly in a for-loop to calculate the manipulated variable and update the controller states at each time step.

Classical MPC

mv = mpcmove(mpcobj,xc,ym,r,v) returns the optimal move mv and updates the states xc of the classical MPC controller mpcobj.

The manipulated variable mv at the current time is calculated given:

• Classical MPC controller object, mpcobj

• State object pointing to the current estimated extended state, xc

• Measured plant outputs, ym

• Output references, r

• Measured disturbance input, v

If ym, r, or v is specified as [], or if it is missing as a last input argument, mpcmove uses the appropriate mpcobj.Model.Nominal value instead.

When you use default state estimation, mpcmove also updates the controller state referenced by the handle object xc. Therefore, when you use default state estimation, xc always points to the updated controller state. When you use custom state estimation, update xc prior to each mpcmove call.

[mv,info] = mpcmove(mpcobj,xc,ym,r,v) returns additional information about the optimization problem solved to calculate mv.

[___] = mpcmove(___,options) overrides default constraints and weights in mpcobj with the values specified in options, an mpcmoveopt object. Use this syntax with any of the input or output arguments in the previous syntaxes. Use options to provide run-time adjustment of constraints and weights during the closed-loop simulation.

Data-Driven MPC

mv = mpcmove(ddobj,xc,uk1,yk1,r) returns the optimal move mv and updates the states xc of the data-driven MPC controller ddobj.

The manipulated variable mv at the current time is calculated given:

• Data-driven MPC controller object, ddobj

• State object pointing to the past trajectory, xc

• Plant input measured at the previous control interval, uk1

• Plant output measured at the previous control interval, yk1

• Output reference data r for the control intervals from the current time k to the time k + ddobj.FutureSteps - 1. r must be a matrix with ddobj.FutureSteps rows and as many columns as the number of outputs. It defaults to zero if omitted. Use this syntax with any of the input or output arguments in the previous syntaxes.

[mv,info] = mpcmove(mpcobj,xc,uk1,yk1,r) returns additional information about the optimization problem solved to calculate mv.

[___] = mpcmove(___,MVTarget=dataUref) additionally specifies the input reference data dataUref for the control intervals from the current time k to the time k + ddobj.FutureSteps - 1. It must be a matrix with ddobj.FutureSteps rows and as many columns as the number of inputs. It defaults to zero if omitted.

Examples

Simulate Closed-Loop Response Using mpcmove

Perform closed-loop simulation of a plant with one MV and one measured OV.

Define a plant model and create a model predictive controller with MV constraints.

ts = 2;
Plant = ss(0.8,0.5,0.25,0,ts);
mpcobj = mpc(Plant);

-->"PredictionHorizon" is empty. Assuming default 10.
-->"ControlHorizon" is empty. Assuming default 2.
-->"Weights.ManipulatedVariables" is empty. Assuming default 0.00000.
-->"Weights.ManipulatedVariablesRate" is empty. Assuming default 0.10000.
-->"Weights.OutputVariables" is empty. Assuming default 1.00000.

mpcobj.MV(1).Min = -2;
mpcobj.MV(1).Max = 2;

Obtain a handle object pointing to the controller state.

xc = mpcstate(mpcobj)

-->Integrator added as output disturbance model for measured output #1.
-->"Model.Noise" is empty. Assuming white noise on each measured output.
MPCSTATE object with fields
          Plant: 0
    Disturbance: 0
          Noise: [1×0 double]
       LastMove: 0
     Covariance: [2×2 double]

The controller has one state for the internal plant model, one for the disturbance model, and one to hold the last value of the manipulated variable. All these three states are initialized to zero.

Set the reference signal. There is no measured disturbance.

r = 1;

Simulate the closed-loop response by calling mpcmove iteratively. In the simulation, assume that the simulated plant is identical to the predictive model. Therefore the plant state x in this case is identical to xc.Plant and the plant output is y = C*x + D*u = 0.25*x = 0.25*xc.Plant. Here, mpcmove updates the controller state referenced by xc (therefore including xc.Plant), and returns the manipulated variable in u(i), which is used just for plotting.

t = 0:ts:40;
N = length(t);
y = zeros(N,1); 
u = zeros(N,1); 
for i = 1:N
    y(i) = 0.25*xc.Plant;
    u(i) = mpcmove(mpcobj,xc,y(i),r);
end

Analyze the result.

[ts,us] = stairs(t,u);
plot(ts,us,'r-',t,y,'b--')
legend('MV','OV')

Modify the MV upper bound as the simulation proceeds using an mpcmoveopt object. Because the options argument overrides selected mpcobj properties, specify MV constraints again.

MPCopt = mpcmoveopt;
MPCopt.MVMin = -2;
MPCopt.MVMax = 2;

Simulate the closed-loop response and introduce the real-time upper limit change at eight seconds (the fifth iteration step).

xc = mpcstate(mpcobj);
y = zeros(N,1);
u = zeros(N,1);
for i = 1:N
    y(i) = 0.25*xc.Plant;
    if i == 5
    	MPCopt.MVMax = 1;
    end
    u(i) = mpcmove(mpcobj,xc,y(i),r,[],MPCopt);
end

Analyze the results.

[ts,us] = stairs(t,u);
plot(ts,us,'r-',t,y,'b--')
legend('MV','OV')

Evaluate Scenario at Specific Time Instant

Define a plant model.

ts = 2;
Plant = ss(0.8,0.5,0.25,0,ts);

Create a model predictive controller with constraints on both the manipulated variable and the rate of change of the manipulated variable. The prediction horizon is 10 intervals, and the control horizon is blocked.

mpcobj = mpc(Plant,ts,10,[2 3 5]);

-->"Weights.ManipulatedVariables" is empty. Assuming default 0.00000.
-->"Weights.ManipulatedVariablesRate" is empty. Assuming default 0.10000.
-->"Weights.OutputVariables" is empty. Assuming default 1.00000.

mpcobj.MV(1).Min = -2;
mpcobj.MV(1).Max = 2;
mpcobj.MV(1).RateMin = -1;
mpcobj.MV(1).RateMax = 1;

Initialize (and return a handle to) the controller internal state for simulation.

xc = mpcstate(mpcobj);

-->Integrator added as output disturbance model for measured output #1.
-->"Model.Noise" is empty. Assuming white noise on each measured output.

xc.Plant = 2.8;
xc.LastMove = 0.85;

Compute the optimal control move at the current time.

y = 0.25*xc.Plant;
r = 1;
[u,Info] = mpcmove(mpcobj,xc,y,r);

Analyze the predicted optimal sequences.

[ts,us] = stairs(Info.Topt,Info.Uopt);
plot(ts,us,"r-",Info.Topt,Info.Yopt,"b--")
legend("MV","OV")

plot ignores Info.Uopt(end) as it is NaN.

Examine the optimal cost.

Info.Cost

ans = 
0.0793

Input Arguments

mpcobj — Model predictive controller

mpc object

Model predictive controller, specified as an MPC controller object. To create an MPC controller, use mpc.

ddobj — Data-driven model predictive controller

DataDrivenMPC object

Data-driven model predictive controller, specified as a DataDrivenMPC object. To create a data-driven MPC controller, use DataDrivenMPC.

Example: ddobj = DataDrivenMPC((0.5-rand(100,1))*2,lsim(tf(1,[1 1]),(0.5-rand(100,1))*2,0.1*(1:100)',0),0.1); creates the DataDrivenMPC object ddobj from the input signal (0.5-rand(100,1))*2, and the output signal obtained by supplying the input signal to the LTI plant tf(1,[1 1]), with a time vector 0.1*(1:100)', a sample time of 0.1 seconds, and an initial state of 0.

xc — Handle object pointing to current controller state

mpcstate object | DataDrivenMPCState object

Handle object pointing to current controller state, specified as:

• An mpcstate object — if the first argument of mpcmove, mpcobj, is an mpc object (representing a classical MPC controller).

  In this case, before you begin a simulation with mpcmove, initialize the controller and return a handle to its state using xc = mpcstate(mpcobj). Then, modify the default properties of xc as appropriate. mpcmove modifies the controller state. The handle object xc always reflect the current (updated) state of the controller.

  If you are using default state estimation, mpcmove expects xc to represent xc[n|n-1]. The mpcmove command updates the state values in the previous control interval with that information. Therefore, do not programmatically update xc at all. The default state estimator employs a steady-state Kalman filter.

  If you are using custom state estimation, mpcmove expects xc to represent xc[n|n]. Therefore, prior to each mpcmove command, you must set xc.Plant, xc.Disturbance, and xc.Noise to the best estimates of these states (using the latest measurements) at the current control interval.

• A DataDrivenMPCState object — if the first argument of mpcmove, ddobj, is a DataDrivenMPC object (representing a data-driven MPC controller).

  In this case, before calling mpcmove, create a handle to the data-driven controller state object using xc = DataDrivenMPCState(ddobj) and make sure the PastInputBuffer and PastOutputBuffer properties of xc are populated with the correct values that reflect the plant inputs and outputs before the simulation (their default values are zero). When mpcmove executes, it then updates xc accordingly.

.

Note

Because xc is a handle object, if you copy it to a new variable, the new variable still points to the current state of the same mpc object. If this state changes, the change is reflected in both xc and its copy. To preserve the original state for later use, you can save xc to a MAT file. During simulation, mpcmove also updates xc when a new control move is calculated. For more information about handle objects, see Handle Object Behavior.

ym — Current measured output values

column vector of length N_ym

Current measured output values at time k, specified as a column vector of length N_ym, where N_ym is the number of measured outputs.

If you are using custom state estimation, set ym = [].

yk1 — Output values in the previous control interval

column vector of length N_y

Output values in the previous control interval, specified as a column vector with as many elements as the number of measured outputs.

uk1 — Input values in the previous control interval

column vector of length N_ym

Input values in the previous control interval, specified as a column vector with as many elements as the number of measured inputs.

r — Plant output reference values

p-by-N_y array

Plant output reference values, specified as a p-by-N_y array, where N_y is the number of outputs and the horizon p is defined as follows.

• If the first argument of mpcmove, mpcobj, is an mpc object, then p is the prediction horizon of mpcobj.

  In this case, row r(i,:) defines the reference values at step i of the prediction horizon. r must contain at least one row. If r contains fewer than p rows, mpcmove duplicates the last row to fill the p-by-N_y array. If you supply exactly one row, therefore, a constant reference applies for the entire prediction horizon.

  To implement reference previewing, which can improve tracking when a reference varies in a predictable manner, r must contain the anticipated variations, ideally for p steps.

• If the first argument of mpcmove, ddobj, is a DataDrivenMPC object, then p is the value of ddobj.Futuresteps.

  In this case, the rows of r represent the output reference data for the intervals from time k to time k+ddobj.FutureSteps. It must be a matrix with ddobj.FutureSteps rows and as many columns as the number of outputs. The value of r defaults to zero if omitted.

v — Current and anticipated measured disturbances

(p+1)-by-N_md array

Current and anticipated measured disturbances, specified as a (p+1)-by-N_md array, where p is the prediction horizon of mpcobj and N_md is the number of measured disturbances. The first row of v specifies the current measured disturbance values. Row v(i+1,:) defines the anticipated disturbance values at step i of the prediction horizon.

Modeling of measured disturbances provides feedforward control action. If your plant model does not include measured disturbances, use v = [].

If your model includes measured disturbances, v must contain at least one row. If v contains fewer than p+1 rows, mpcmove duplicates the last row to fill the (p+1)-by-N_md array. If you supply exactly one row, a constant measured disturbance applies for the entire prediction horizon.

To implement disturbance previewing, which can improve tracking when a disturbance varies in a predictable manner, v must contain the anticipated variations, ideally for p steps.

options — Run-time options

mpcmoveopt object

Run-time options, specified as an mpcmoveopt object. Use options to override selected properties of mpcobj during simulation. These options apply to the current mpcmove time instant only. Using options yields the same result as redefining or modifying mpcobj before each call to mpcmove, but involves considerably less overhead. Using options is equivalent to using an MPC Controller Simulink^® block in combination with optional input signals that modify controller settings, such as manipulated variables and output variables constraints.

dataUref — Plant input reference values for data-driven MPC

p-by-N_u array

Plant input reference values for data-driven MPC, specified as a p-by-N_u array, where N_u is the number of inputs and the horizon p is the value of ddobj.Futuresteps.

The rows of dataUref represent the input target values for the intervals from the current time k to the time k+ddobj.FutureSteps–1.

Output Arguments

mv — Optimal manipulated variable moves

column vector

Optimal manipulated variable moves, returned as a column vector of length N_mv, where N_mv is the number of manipulated variables.

If the controller detects an infeasible optimization problem or encounters numerical difficulties in solving an ill-conditioned optimization problem, mv remains at its most recent successful solution, xc.LastMove.

Otherwise, if the optimization problem is feasible and the solver reaches the specified maximum number of iterations without finding an optimal solution, mv:

• Remains at its most recent successful solution if the Optimizer.UseSuboptimalSolution property of the controller is false.

• Is the suboptimal solution reached after the final iteration if the Optimizer.UseSuboptimalSolution property of the controller is true. For more information, see Suboptimal QP Solution.

info — Solution details

structure

Solution details, returned as a structure with the following fields.

Uopt — Optimal manipulated variable sequence

(p+1)-by-N_mv array

Predicted optimal manipulated variable adjustments (moves), returned as a (p+1)-by-N_mv array.

Here p is the prediction horizon if mpcmove operates on an mpc object, or ddobj.FutureSteps-1 if mpcmove operates on the DataDrivenMPC object ddobj. N_mv is the number of manipulated variables.

Uopt(i,:) contains the calculated optimal values at time k+i-1, for i = 1, ...,p, where k is the current time.

The first row of Info.Uopt contains the same manipulated variable values as output argument mv.

When the solver finds the optimal solution (info.iterations is positive), or when it finds a feasible suboptimal solution (info.Iterations is zero) and a suboptimal solution is acceptable (the Optimization.UseSuboptimalSolution property of the controller object is true), then the function sets its output argument mv to Uopt(1,:). If the solver fails (info.Iterations is negative), then mv contains lastmv.

Because the function does not calculate optimal control moves at time k+p, Uopt(p+1,:) is equal to Uopt(p,:).

Yopt — Optimal output variable sequence

(p+1)-by-N_y array

Optimal output variable sequence, returned as a (p+1)-by-N_y array.

Here p is the prediction horizon if mpcmove operates on an mpc object, or ddobj.FutureSteps-1 if mpcmove operates on the DataDrivenMPC object ddobj. N_y is the number of plant outputs.

The first row of Info.Yopt contains the calculated outputs at time k based on the estimated states and measured disturbances; it is not the measured output at time k. Yopt(i,:) contains the predicted output values at time k+i-1, for i = 1, ...,p+1.

Yopt(i,:) contains the calculated output values at time k+i-1, for i = 2, ...,p+1, where k is the current time. Yopt(1,:) is computed based on the estimated states and measured disturbances.

Xopt — Optimal prediction model state sequence

(p+1)-by-N_x array

Optimal prediction model state sequence, returned as a (p+1)-by-N_x array. when mpcmove operates on an mpc object. Here p is the prediction horizon and N_x is the number of states in the plant and unmeasured disturbance models (states from noise models are not included).

Xopt(i,:) contains the calculated state values at time k+i-1, for i = 2, ...,p+1, where k is the current time. Xopt(1,:) is the same as the current states state values.

Note

When mpcmove operates on an DataDrivenMPC object this field not returned.

Topt — Time intervals

column vector of length p+1

Time intervals, returned as a column vector of length p+1.

Here p is the prediction horizon if mpcmove operates on an mpc object, or ddobj.FutureSteps-1 if mpcmove operates on the DataDrivenMPC object ddobj.

Topt(1) = 0, representing the current time. Subsequent time steps Topt(i) are given by Ts*(i-1), where Ts = mpcobj.Ts is the controller sample time.

Use Topt when plotting the Uopt, Xopt, or Yopt sequences.

Slack — Slack variable

nonnegative scalar

Slack variable, ε, used in constraint softening, returned as 0 or a positive scalar value.

• ε = 0 — All constraints were satisfied for the entire prediction horizon.

• ε > 0 — At least one soft constraint is violated. When more than one constraint is violated, ε represents the worst-case soft constraint violation (scaled by your ECR values for each constraint).

See QP Optimization Problem for Linear MPC for more information.

Iterations — Number of solver iterations

positive integer | 0 | -1 | -2

Number of solver iterations, returned as one of the following:

• Positive integer — Number of iterations needed to solve the optimization problem that determines the optimal sequences.

• 0 — Optimization problem could not be solved in the specified maximum number of iterations.

• –1 — Optimization problem was infeasible. An optimization problem is infeasible if no solution can satisfy all the hard constraints.

• –2 — Numerical error occurred when solving the optimization problem.

QPCode — Optimization solution status

'feasible' | 'infeasible' | 'unrealiable'

Optimization solution status, returned as one of the following:

• 'feasible' — Optimal solution was obtained (Iterations > 0)

• 'infeasible' — Solver detected a problem with no feasible solution (Iterations = –1) or a numerical error occurred (Iterations = –2)

• 'unreliable' — Solver failed to converge (Iterations = 0). In this case, if mpcobj.Optimizer.UseSuboptimalSolution is false, u freezes at the most recent successful solution. Otherwise, it uses the suboptimal solution found during the last solver iteration.

Cost — Objective function cost

nonnegative scalar

Objective function cost, returned as a nonnegative scalar value. The cost quantifies the degree to which the controller has achieved its objectives. For more information, see QP Optimization Problem for Linear MPC.

The cost value is only meaningful when QPCode is 'feasible', or when QPCode is 'unreliable', and mpcobj.Optimizer.UseSuboptimalSolution is true.

Tips

• mpcmove updates xc, even though it is an input argument.

• If ym, r, or v is specified as [], or if it is missing as a last input argument, mpcmove uses the appropriate mpcobj.Model.Nominal value instead.

• To view the predicted optimal behavior for the entire prediction horizon, plot the appropriate sequences provided in Info.

• To determine the optimization status, check Info.Iterations and Info.QPCode.

Alternatives

• Use sim for plant mismatch and noise simulation when not using run-time constraints or weight changes.

• Use the MPC Designer app to interactively design and simulate model predictive controllers.

• Use the MPC Controller block in Simulink and for code generation.

• Use mpcmoveCodeGeneration to simulate an MPC controller prior to code generation.

Version History

Introduced before R2006a