Main Content

mpcmoveCodeGeneration

Compute optimal control moves with code generation support

Description

example

[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

collapse all

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.

[configData,stateData,onlineData] = 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.

x = zeros(size(plant.B,1),1); % Initialize plant states to zero (|mpcObj| default).
Tsim = 20;
for i = 1:round(Tsim/Ts)+1
    % Update plant output.
    y = plant.C*x;
    % Update measured output in online data.
    onlineData.signals.ym = y;
    % Update reference signal in online data.
    onlineData.signals.ref = 1;
    % Compute control actions.
    [u,statedata] = mpcmoveCodeGeneration(configData,stateData,onlineData);
    % 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', configData, stateData, onlineData, cfg);
Generating MEX function "mpcmoveMEX" from linear MPC to speed up simulation.
Code generation successful.

MEX function "mpcmoveMEX" successfully generated.

Input Arguments

collapse all

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

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 model state estimates, specified as a column vector of length Nxp, where Nxp 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.

Unmeasured disturbance model state estimates, specified as a column vector of length Nxd, where Nxd 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.

Output measurement noise model state estimates, specified as a column vector of length Nxn, where Nxn 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.

Manipulated variable control moves from previous control interval, specified as a column vector of length Nmv, where Nmv 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 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 Nxp, Nxd, and Nxn.

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.

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.

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

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

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

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

Output references, specified as one of the following:

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

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

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

Measured disturbances, specified as:

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

  • If you are using signal previewing with implicit or adaptive MPC, specify a p-by-Nmd 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.

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

  • Vector of length Nmv, where Nmv 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.

Manipulated variables externally applied to the plant, specified as:

  • A vector of length Nmv.

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

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:

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

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

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

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

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

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

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.

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:

Output variable lower bounds, specified as a column vector of length Ny. 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.

Output variable upper bounds, specified as a column vector of length Ny. 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.

Manipulated variable lower bounds, specified as a column vector of length Nmv. 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.

Manipulated variable upper bounds, specified as a column vector of length Nmv. 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.

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:

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.

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

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.

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:

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

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, [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 control horizon 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.

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:

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

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

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

where Nx is the number of plant states.

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

  • Nx-by-Nu array when using adaptive MPC,

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

where Nu is the number of plant inputs.

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

  • Ny-by-Nx array when using adaptive MPC.

  • Ny-by-Nx-by-(p+1) array when using time-varying MPC.

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

  • Ny-by-Nu array when using adaptive MPC.

  • Ny-by-Nu-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.

Nominal plant states, specified as:

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

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

Nominal plant inputs, specified as:

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

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

Nominal plant outputs, specified as:

  • A column vector of length Nywhen using adaptive MPC.

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

Nominal plant state derivatives, specified as:

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

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

Output Arguments

collapse all

Optimal manipulated variable moves, returned as a column vector of length Nmv, where Nmv 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.

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.

Controller optimization information, returned as a structure.

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

FieldDescription
IterationsNumber of QP solver iterations
QPCodeQP solver status code
CostObjective function cost
UoptOptimal manipulated variable adjustments
YoptOptimal predicted output variable sequence
XoptOptimal predicted state variable sequence
ToptTime horizon intervals
SlackSlack 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:

FieldDescription
RegionRegion in which the optimal solution was found
ExitCodeSolution status code

For more information, see mpcmoveExplicit.

Extended Capabilities

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

Version History

Introduced in R2016a