mpcmoveCodeGeneration
Compute optimal control moves with code generation support
Syntax
Description
[
computes optimal MPC control moves and supports code generation for deployment to
real-time targets. The input data structures, generated using mv
,newStateData
]
= mpcmoveCodeGeneration(configData
,stateData
,onlineData
)getCodeGenerationData
, define the MPC controller to simulate.
mpcmoveCodeGeneration
does not check input arguments for
correct dimensions and data types.
[___,
returns additional information about the optimization result, including the number
of iterations and the objective function cost.info
] = mpcmoveCodeGeneration(___)
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
nxp
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
.
Disturbance
— Unmeasured disturbance model state estimates
[]
(default) | column vector
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
.
Noise
— Output measurement noise model state estimates
[]
(default) | column vector
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
.
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 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
— 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 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
.
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 Nym, where Nym 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 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.
md
— Measured disturbances
row vector | array
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
.
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 Nmv, where Nmv is the number of manipulated variables
[]
to use the default targets defined inconfigData.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 Nmv.
[]
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 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.
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 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.
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 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.
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
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.
ymax
— Output variable upper bounds
[]
(default) | column vector
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.
umin
— Manipulated variable lower bounds
[]
(default) | column vector
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.
umax
— Manipulated variable upper bounds
[]
(default) | column vector
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.
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) | Nc-by-Nmv
array
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.
F
— Controlled output constraint constant
[]
(default) | Nc-by-Ny
array
Controlled 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 constant
[]
(default) | column vector of length
Nc
Mixed input/output constraint constant, specified as a column vector of length Nc.
S
— Measured disturbance constraint constant
[]
(default) | Nc-by-Nv
array
Measured disturbance constraint constant, specified as an Nc-by-Nmd array, where Nmd 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
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, [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.
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
Nx-by-Nx
array | Nx-by-Nx-by-(p+1)
array
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.
B
— Input-to-state matrix of discrete-time state-space plant model
Nx-by-Nu
array | Nx-by-Nu-by-(p+1)
array
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.
C
— State-to-output matrix of discrete-time state-space plant model
Ny-by-Nx
array | Ny-by-Nx-by-(p+1)
array
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.
D
— Feedthrough matrix of discrete-time state-space plant model
Ny-by-Nu
array | Ny-by-Nu-by-(p+1)
array
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.
X
— Nominal plant states
column vector of length
Nx | Nx-by-1-by-(p+1)
array
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.
U
— Nominal plant inputs
column vector of length
Nu | Nu-by-1-by-(p+1)
array
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.
Y
— Nominal plant outputs
column vector of length
Ny | Ny-by-1-by-(p+1)
array
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.
DX
— Nominal plant state derivatives
column vector of length
Nx | Nx-by-1-by-(p+1)
array
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
mv
— Optimal manipulated variable moves
column vector
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 isfalse
.Is the suboptimal solution reached after the final iteration if the
Optimizer.UseSuboptimalSolution
property of the controller istrue
. 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:
Generate data structures from an MPC controller or explicit MPC controller using
getCodeGenerationData
.To verify that your controller produces the expected closed-loop results, simulate it using
mpcmoveCodeGeneration
in place ofmpcmove
.Generate code for
mpcmoveCodeGeneration
usingcodegen
(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
See Also
Functions
getCodeGenerationData
|mpcmove
|mpcmoveExplicit
|mpcmoveAdaptive
|buildMEX
|codegen
(MATLAB Coder)
Objects
mpc
|mpcmoveopt
|mpcstate
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)