mpcmoveCodeGeneration

Compute optimal control moves with code generation support

Syntax

[mv,newStateData] = mpcmoveCodeGeneration(configData,stateData,onlineData)

[___,info] = mpcmoveCodeGeneration(___)

Description

[mv,newStateData] = mpcmoveCodeGeneration(configData,stateData,onlineData) computes optimal MPC control moves and supports code generation for deployment to real-time targets. The input data structures, generated using getCodeGenerationData, define the MPC controller to simulate.

mpcmoveCodeGeneration does not check input arguments for correct dimensions and data types.

[___,info] = mpcmoveCodeGeneration(___) returns additional information about the optimization result, including the number of iterations and the objective function cost.

Examples

Compute Optimal Control Moves Using Code Generation Data Structures

Create a proper plant model.

plant = rss(3,1,1);
plant.D = 0;

Specify the controller sample time.

Ts = 0.1;

Create an MPC controller.

mpcObj = mpc(plant,Ts);

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

Create code generation data structures.

[params,state,ins] = getCodeGenerationData(mpcObj);

-->Converting model to discrete time.
-->Assuming output disturbance added to measured output #1 is integrated white noise.
-->"Model.Noise" is empty. Assuming white noise on each measured output.
-->Converting model to discrete time.
-->Assuming output disturbance added to measured output #1 is integrated white noise.
-->"Model.Noise" is empty. Assuming white noise on each measured output.

Initialize the plant states to zero to match the default states used by the MPC controller.

Run a closed-loop simulation. At each control interval, update the online data structure and call mpcmoveCodeGeneration to compute the optimal control moves.

% Initialize plant states to zero (|mpcObj| default).
x = zeros(size(plant.B,1),1); Tsim = 20;

for i = 1:round(Tsim/Ts)+1

    % Update plant output.
    y = plant.C*x;
    
    % Update measured output in input structure (online data).
    ins.signals.ym = y;
    
    % Update reference signal in input structure.
    ins.signals.ref = 1;
    
    % Compute control actions.
    [u,state] = mpcmoveCodeGeneration(params,state,ins);
    
    % Update plant state.
    x = plant.A*x + plant.B*u;
end

Generate MEX function with MATLAB® Coder™, specifying configData as a constant.

cfg = coder.config('mex');
cfg.EnableDynamicMemoryAllocation = false;
mexfun = buildMEX(mpcObj,'mpcmoveMEX',params,state,ins,cfg);

Generating MEX function "mpcmoveMEX" from linear MPC to speed up simulation.
Code generation successful.

MEX function "mpcmoveMEX" successfully generated.

Input Arguments

configData — MPC configuration parameters

structure

MPC configuration parameters that are constant at run time, specified as a structure generated using getCodeGenerationData.

Note

When using codegen (MATLAB Coder), configData must be defined as coder.Constant (MATLAB Coder).

stateData — Controller state

structure

Controller state at run time, specified as a structure. Generate the initial state structure using getCodeGenerationData. For subsequent control intervals, use the updated controller state from the previous interval. In general, use the newStateData structure directly.

If custom state estimation is enabled, you must manually update the stateData structure during each control interval. For more information, see Custom State Estimation.

stateData has the following fields:

Plant — Plant model state estimates

mpcobj nominal plant states (default) | column vector of length n_xp

Plant model state estimates, specified as a column vector of length N_xp, where N_xp is the number of plant model states.

Note

If custom state estimation is enabled, update Plant at each control interval. Otherwise, do not change this field. Instead use the values returned by either getCodeGenerationData or mpcmoveCodeGeneration.

Disturbance — Unmeasured disturbance model state estimates

[] (default) | column vector

Unmeasured disturbance model state estimates, specified as a column vector of length N_xd, where N_xd is the number of unmeasured disturbance model states. Disturbance contains the input disturbance model states followed by the output disturbance model states.

To view the input and output disturbance models, use getindist and getoutdist respectively.

Note

If custom state estimation is enabled, update Disturbance at each control interval. Otherwise, do not change this field. Instead use the values returned by either getCodeGenerationData or mpcmoveCodeGeneration.

Noise — Output measurement noise model state estimates

[] (default) | column vector

Output measurement noise model state estimates, specified as a column vector of length N_xn, where N_xn is the number of noise model states.

Note

If custom state estimation is enabled, update Noise at each control interval. Otherwise, do not change this field. Instead use the values returned by either getCodeGenerationData or mpcmoveCodeGeneration.

LastMove — Manipulated variable control moves from previous control interval

mpcobj nominal MV values (default) | column vector

Manipulated variable control moves from previous control interval, specified as a column vector of length N_mv, where N_mv is the number of manipulated variables.

Note

Do not change the value of LastMove. Always use the values returned by either getCodeGenerationData or mpcmoveCodeGeneration.

Covariance — Covariance matrix for controller state estimates

symmetrical array

Covariance matrix for controller state estimates, specified as a symmetrical N-by-N array, where N is number of extended controller states; that is, the sum of N_xp, N_xd, and N_xn.

If the controller uses custom state estimation, Covariance is empty.

Note

Do not change the value of Covariance. Always use the values returned by either getCodeGenerationData or mpcmoveCodeGeneration.

iA — Active inequality constraints

false (default) | logical vector

Active inequality constraints, where the equal portion of the inequality is true, specified as a logical vector of length M. If iA(i) is true, then the ith inequality is active for the latest QP solver solution.

Note

Do not change the value of iA. Always use the values returned by either getCodeGenerationData or mpcmoveCodeGeneration.

onlineData — Online controller data

structure

Online controller data that you must update at run time, specified as a structure with the following fields. Generate the initial structure using getCodeGenerationData.

signals — Updated input and output signals

structure

Updated input and output signals, specified as a structure with the following fields:

ym — Measured outputs

vector

Measured outputs, specified as a vector of length N_ym, where N_ym is the number of measured outputs.

By default, getCodeGenerationData sets ym to the nominal measured output values from the controller.

ref — Output references

row vector | array

Output references, specified as one of the following:

• Row vector of length N_y, where N_y is the number of outputs.

• If you are using reference signal previewing with implicit or adaptive MPC, specify a p-by-N_y array, where p is the prediction horizon.

By default,getCodeGenerationData sets ref to the nominal output values from the controller.

md — Measured disturbances

row vector | array

Measured disturbances, specified as:

• A row vector of length N_md, where N_md is the number of measured disturbances.

• If you are using signal previewing with implicit or adaptive MPC, specify a p-by-N_md array.

By default, if your controller has measured disturbances,getCodeGenerationData sets md to the nominal measured disturbance values from the controller. Otherwise, this field is empty and ignored by mpcmoveCodeGeneration.

mvTarget — Targets for manipulated variables

[] (default) | vector

Targets for manipulated variables, which replace the targets defined in configData.uTarget, specified as one of the following:

• Vector of length N_mv, where N_mv is the number of manipulated variables

• [] to use the default targets defined in configData.uTarget

This field is ignored when using an explicit MPC controller.

externalMV — Manipulated variables externally applied to the plant

[] (default) | vector

Manipulated variables externally applied to the plant, specified as:

• A vector of length N_mv.

• [] to apply the optimal control moves to the plant.

weights — Updated QP optimization weights

structure

Updated QP optimization weights, specified as a structure. If you do not expect tuning weights to change at run time, ignore weights. This field is ignored when using an explicit MPC controller.

This structure contains the following fields:

y — Output variable tuning weights

[] (default) | row vector | array

Output variable tuning weights that replace the original controller output weights at run time at run time, specified as a row vector or array of nonnegative values.

To use the same weights across the prediction horizon, specify a row vector of length N_y, where N_y 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 N_y 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.

If y is empty, [], the default weights defined in the original MPC controller are used.

u — Manipulated variable tuning weights

[] (default) | row vector | array

Manipulated variable tuning weights that replace the original controller manipulated variable weights at run time, specified as a row vector or array of nonnegative values.

To use the same weights across the prediction horizon, specify a row vector of length N_mv, where N_mv 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 N_mv 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.

If u is empty, [], the default weights defined in the original MPC controller are used.

du — Manipulated variable rate tuning weights

[] (default) | row vector | array

Manipulated variable rate tuning weights that replace the original controller manipulated variable rate weights at run time, specified as a row vector or array of nonnegative values.

To use the same weights across the prediction horizon, specify a row vector of length N_mv, where N_mv 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 N_mv 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.

If du is empty, [], the default weights defined in the original MPC controller are used.

ecr — Weight on slack variable used for constraint softening

[] (default) | nonnegative scalar

Weight on slack variable used for constraint softening, specified as a nonnegative scalar.

If ecr is empty, [], the default weight defined in the original MPC controller are used.

limits — Updated input and output constraints

structure

Updated input and output constraints, specified as a structure. If you do not expect constraints to change at run time, ignore limits. This field is ignored when using an explicit MPC controller.

This structure contains the following fields:

ymin — Output variable lower bounds

[] (default) | column vector

Output variable lower bounds, specified as a column vector of length N_y. ymin(i) replaces the OutputVariables(i).Min constraint from the original controller. If the OutputVariables(i).Min property of the controller is specified as a vector, ymin(i) replaces the first finite entry in this vector, and the remaining values shift to retain the same constraint profile.

If ymin is empty, [], the default bounds defined in the original MPC controller are used.

ymax — Output variable upper bounds

[] (default) | column vector

Output variable upper bounds, specified as a column vector of length N_y. ymax(i) replaces the OutputVariables(i).Max constraint from the original controller. If the OutputVariables(i).Max property of the controller is specified as a vector, ymax(i) replaces the first finite entry in this vector, and the remaining values shift to retain the same constraint profile.

If ymax is empty, [], the default bounds defined in the original MPC controller are used.

umin — Manipulated variable lower bounds

[] (default) | column vector

Manipulated variable lower bounds, specified as a column vector of length N_mv. umin(i) replaces the ManipulatedVariables(i).Min constraint from the original controller. If the ManipulatedVariables(i).Min property of the controller is specified as a vector, umin(i) replaces the first finite entry in this vector, and the remaining values shift to retain the same constraint profile.

If umin is empty, [], the default bounds defined in the original MPC controller are used.

umax — Manipulated variable upper bounds

[] (default) | column vector

Manipulated variable upper bounds, specified as a column vector of length N_mv. umax(i) replaces the ManipulatedVariables(i).Max constraint from the original controller. If the ManipulatedVariables(i).Max property of the controller is specified as a vector, umax(i) replaces the first finite entry in this vector, and the remaining values shift to retain the same constraint profile.

If umax is empty, [], the default bounds defined in the original MPC controller are used.

customconstraints — Updated custom mixed input/output constraints

structure

Updated custom mixed input/output constraints, specified as a structure. This field is ignored when using an explicit MPC controller.

This structure has the following fields:

E — Manipulated variable constraint constant

[] (default) | N_c-by-N_mv array

Manipulated variable constraint constant, specified as an N_c-by-N_mv array, where N_c is the number of constraints, and N_mv is the number of manipulated variables.

If E is empty, [], the corresponding constraint defined in the original MPC controller are used.

F — Controlled output constraint constant

[] (default) | N_c-by-N_y array

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

G — Mixed input/output constraint constant

[] (default) | column vector of length N_c

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

S — Measured disturbance constraint constant

[] (default) | N_c-by-N_v array

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

horizons — Updated controller horizons

structure

Updated controller horizons, specified as a structure. To vary horizons at run time, first create your data structures using getCodeGenerationData setting the UseVariableHorizon name-value pair to true. When you vary the horizons, you must specify both the prediction horizon and the control horizon. For more information, see Adjust Horizons at Run Time.

This field is ignored when using an explicit MPC controller.

This structure has the following fields:

p — Prediction horizon

[] (default) | positive integer

Prediction horizon, which replaces the value of configData.p at run time, specified as a positive integer.

Specifying p changes the:

• Number of rows in the optimal sequences returned in info

• The maximum dimensions of the fields in model when configData.IsLTV is true

m — Control horizon

[] (default) | positive integer | vector of positive integers

Control horizon, which replaces the value of configData.m at run time, specified as one of the following:

• Positive integer, m, between 1 and p, inclusive, where p is the prediction horizon (horizons.p). 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, [m₁, m₂, …], 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 control horizon vector. The first free move applies to times k through k+m₁-1, the second free move applies from time k+m₁ through k+m₁+m₂-1, and so on. Using block moves can improve the robustness of your controller compared to the default case.

model — Updated plant and nominal values

structure

Updated plant and nominal values for adaptive MPC and time-varying MPC, specified as a structure. model is only available if you specify isAdaptive or isLTV as true when creating code generation data structures.

This structure contains the following fields:

A — State matrix of discrete-time state-space plant model

N_x-by-N_x array | N_x-by-N_x-by-(p+1) array

State matrix of discrete-time state-space plant model, specified as an:

• N_x-by-N_x array when using adaptive MPC,

• N_x-by-N_x-by-(p+1) array when using time-varying MPC,

where N_x is the number of plant states.

B — Input-to-state matrix of discrete-time state-space plant model

N_x-by-N_u array | N_x-by-N_u-by-(p+1) array

Input-to-state matrix of discrete-time state-space plant model, specified as an:

• N_x-by-N_u array when using adaptive MPC,

• N_x-by-N_u-by-(p+1) array when using time-varying MPC,

where N_u is the number of plant inputs.

C — State-to-output matrix of discrete-time state-space plant model

N_y-by-N_x array | N_y-by-N_x-by-(p+1) array

State-to-output matrix of discrete-time state-space plant model, specified as an:

• N_y-by-N_x array when using adaptive MPC.

• N_y-by-N_x-by-(p+1) array when using time-varying MPC.

D — Feedthrough matrix of discrete-time state-space plant model

N_y-by-N_u array | N_y-by-N_u-by-(p+1) array

Feedthrough matrix of discrete-time state-space plant model, specified as an:

• N_y-by-N_u array when using adaptive MPC.

• N_y-by-N_u-by-(p+1) array when using time-varying MPC.

Since MPC controllers do not support plants with direct feedthrough, specify D as an array of zeros.

X — Nominal plant states

column vector of length N_x | N_x-by-1-by-(p+1) array

Nominal plant states, specified as:

• A column vector of length N_x when using adaptive MPC.

• An N_x-by-1-by-(p+1) array when using time-varying MPC.

U — Nominal plant inputs

column vector of length N_u | N_u-by-1-by-(p+1) array

Nominal plant inputs, specified as:

• A column vector of length N_u when using adaptive MPC.

• An N_u-by-1-by-(p+1) array when using time-varying MPC.

Y — Nominal plant outputs

column vector of length N_y | N_y-by-1-by-(p+1) array

Nominal plant outputs, specified as:

• A column vector of length N_ywhen using adaptive MPC.

• An N_y-by-1-by-(p+1) array when using time-varying MPC.

DX — Nominal plant state derivatives

column vector of length N_x | N_x-by-1-by-(p+1) array

Nominal plant state derivatives, specified as:

• A column vector of length N_x when using adaptive MPC.

• An N_x-by-1-by-(p+1) array when using time-varying MPC.

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.

newStateData — Updated controller state

structure

Updated controller state, returned as a structure. For subsequent control intervals, pass newStateData to mpcmoveCodeGeneration as stateData.

If custom state estimation is enabled, use newStateData to manually update the state structure before the next control interval. For more information, see Custom State Estimation.

info — Controller optimization information

structure

Controller optimization information, returned as a structure.

If you are using implicit or adaptive MPC, info contains the following fields:

Field	Description
Iterations	Number of QP solver iterations
QPCode	QP solver status code
Cost	Objective function cost
Uopt	Optimal manipulated variable adjustments
Yopt	Optimal predicted output variable sequence
Xopt	Optimal predicted state variable sequence
Topt	Time horizon intervals
Slack	Slack variable used in constraint softening

If configData.OnlyComputeCost is true, the optimal sequence information, Uopt, Yopt, Xopt, Topt, and Slack, is not available:

For more information, see mpcmove and mpcmoveAdaptive.

If you are using explicit MPC, info contains the following fields:

Field	Description
Region	Region in which the optimal solution was found
ExitCode	Solution status code

For more information, see mpcmoveExplicit.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• You can generate code for both implicit and explicit MPC controllers.

• To generate code for computing optimal MPC control moves:

  1. Generate data structures from an MPC controller or explicit MPC controller using getCodeGenerationData.

  2. To verify that your controller produces the expected closed-loop results, simulate it using mpcmoveCodeGeneration in place of mpcmove.

  3. Generate code for mpcmoveCodeGeneration using codegen (MATLAB Coder). This step requires MATLAB^® Coder™ software.

GPU Code Generation
Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Version History

Introduced in R2016a