getCodeGenerationData
Syntax
Description
Use this function to create data structures for the nlmpcmoveCodeGeneration
function, which computes optimal control moves
for nonlinear MPC controllers.
For information on generating data structures for mpcmoveCodeGeneration
, see getCodeGenerationData
.
[
creates data structures for use with coreData
,onlineData
]
= getCodeGenerationData(nlobj
,x
,lastMV
)nlmpcmoveCodeGeneration
.
[
copies initial parameter values in the coreData
,onlineData
]
= getCodeGenerationData(nlobj
,x
,lastMV
,params
)onlineData
structure if
nlobj
is an nlmpc
object. If
nlobj
is an nlmpcMultistage
object then
passing the params
argument is not allowed and you have to
manually specify the initial guesses in the InitialGuess
field of
onlineData
instead.
[___] = getCodeGenerationData(___,
enables the specified online weight or constraint field by adding it to the
field
)onlineData
structure.
[___] = getCodeGenerationData(___,field1,...,fieldn)
enables multiple online weight or constraint fields by adding them to the
onlineData
structure.
[___] = getCodeGenerationData(___,
when Name=Value
)nlobj
is a nlmpcMultistage
object, you
can specify measured disturbance inputs or the state and stage functions parameters
using one or more namevalue arguments. For example,
StageParameter=PV
adds the PV vector to
onlineData
.
Examples
Create Nonlinear MPC Code Generation Structures
Create a nonlinear MPC controller with four states, two outputs, and one input.
nlobj = nlmpc(4,2,1);
Zero weights are applied to one or more OVs because there are fewer MVs than OVs.
Specify the sample time and horizons of the controller.
Ts = 0.1; nlobj.Ts = Ts; nlobj.PredictionHorizon = 10; nlobj.ControlHorizon = 5;
Specify the state function for the controller, which is in the file pendulumDT0.m
. This discretetime model integrates the continuoustime model defined in pendulumCT0.m
using a multistep forward Euler method.
nlobj.Model.StateFcn = "pendulumDT0";
nlobj.Model.IsContinuousTime = false;
The prediction model uses an optional parameter Ts
to represent the sample time. Specify the number of parameters and create a parameter vector.
nlobj.Model.NumberOfParameters = 1; params = {Ts};
Specify the output function of the model, passing the sample time parameter as an input argument.
nlobj.Model.OutputFcn = "pendulumOutputFcn";
Define standard constraints for the controller.
nlobj.Weights.OutputVariables = [3 3]; nlobj.Weights.ManipulatedVariablesRate = 0.1; nlobj.OV(1).Min = 10; nlobj.OV(1).Max = 10; nlobj.MV.Min = 100; nlobj.MV.Max = 100;
Validate the prediction model functions.
x0 = [0.1;0.2;pi/2;0.3]; u0 = 0.4; validateFcns(nlobj,x0,u0,[],params);
Model.StateFcn is OK. Model.OutputFcn is OK. Analysis of userprovided model, cost, and constraint functions complete.
Only two of the plant states are measurable. Therefore, create an extended Kalman filter for estimating the four plant states. Its state transition function is defined in pendulumStateFcn.m
and its measurement function is defined in pendulumMeasurementFcn.m
.
EKF = extendedKalmanFilter(@pendulumStateFcn,@pendulumMeasurementFcn);
Define initial conditions for the simulation, initialize the extended Kalman filter state, and specify a zero initial manipulated variable value.
x0 = [0;0;pi;0]; y0 = [x0(1);x0(3)]; EKF.State = x0; mv0 = 0;
Create code generation data structures for the controller, specifying the initial conditions and parameters.
[coreData,onlineData] = getCodeGenerationData(nlobj,x0,mv0,params);
View the online data structure.
onlineData
onlineData = struct with fields:
ref: [0 0]
MVTarget: 0
Parameters: {[0.1000]}
X0: [10x4 double]
MV0: [10x1 double]
Slack0: [0]
If your application uses online weights or constraints, you must add corresponding fields to the code generation data structures. For example, the following syntax creates data structures that include fields for output variable tuning weights, manipulated variable tuning weights, and manipulated variable bounds.
[coreData2,onlineData2] = getCodeGenerationData(nlobj,x0,mv0,params,... 'OutputWeights','MVWeights','MVMin','MVMax');
View the online data structure. At run time, specify the online weights and constraints in the added structure fields.
onlineData2
onlineData2 = struct with fields:
ref: [0 0]
MVTarget: 0
Parameters: {[0.1000]}
X0: [10x4 double]
MV0: [10x1 double]
Slack0: [0]
OutputWeights: [3 3]
MVWeights: [0]
MVMin: [10x1 double]
MVMax: [10x1 double]
Input Arguments
nlobj
— Nonlinear model predictive controller
nlmpc
object  nlmpcMultistage
object
Nonlinear model predictive controller, specified as an nlmpc
or nlmpcMultistage
object.
x
— Initial states of nonlinear prediction model
column vector of length
N_{x}
Initial states of the nonlinear prediction model, specified as a column vector of length N_{x}, where N_{x} is the number of prediction model states.
lastMV
— Initial manipulated variable control signals
column vector of length
N_{mv}
Initial manipulated variable control signals, specified as a column vector of length N_{mv}, where N_{mv} is the number of manipulated variables.
params
— Initial parameter values for non multistage MPC
cell vector
Initial parameter values for non multistage MPC, specified as a cell
vector with length equal to
nlobj.Model.NumberOfParameters
, which is the number
of optional parameters in the controller prediction model. If the controller
has no optional parameters, specify params
as
{}
.
If nlobj
is an nlmpc
object then the
initial values specified in params
are copied into the
onlineData
structure. If nlobj
is an nlmpcMultistage
object then the
params
argument is not allowed and you have to
manually specify the initial guesses in the InitialGuess
field of onlineData
instead.
For more information on optional prediction model parameters, see Specify Prediction Model for Nonlinear MPC.
field
— Online weight or constraint field name
string  character vector
Online weight or constraint field name, specified as a string or character
vector. When creating data structures for
nlmpcmoveCodeGeneration
, you can add any of the
following fields to the onlineData
output structure.
Add a given field to the online data structure only if you expect the
corresponding weight or constraint to vary at run time.
Online Constraints
"StateMin"
— State lower bounds"StateMax"
— State upper bounds"MVMin"
— Manipulated variable lower bounds"MVMax"
— Manipulated variable upper bounds"MVRateMin"
— Manipulated variable rate of change lower bound"MVRateMax"
— Manipulated variable rate of change upper bound
Online constraints and Tuning Weights for nonMultistage MPC
"OutputWeights"
— Output variable weights"MVWeights"
— Manipulated variable weights"MVRateWeights"
— Manipulated variable rate weights"ECRWeight"
— Slack variable weight"OutputMin"
— Output variable lower bounds"OutputMax"
— Output variable upper bounds
Disturbances, Parameters, and Initial Guesses for Multistage MPC
"MeasuredDistrubance"
— Measured disturbances"StateParameter"
— Parameter vector for state function and Jacobians"StageParameter"
— Parameter vector for stage cost, constraints, and Jacobians"TerminalState"
— Terminal state constraint"InitialGuess"
— Initial guesses for decision variables
NameValue Arguments
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Namevalue arguments must appear after other arguments, but the order of the
pairs does not matter.
Example: StateFcnParameter=PM
MeasuredDisturbance
— Measured disturbances
zeros(1,length(nlobj.Dimensions.MDIndex))
(default)  vector
Measured disturbances, specified as a vector. Use this argument to specify initial measured disturbances.
If your model has measured disturbances, this property sets the
initial value of the MeasuredDisturbance
field that
is added to onlinedata
. If your model does not have
measured disturbances the MeasuredDisturbance
field
is not added to onlinedata
, and you cannot set this
argument.
Example: MeasuredDisturbance=[0.2
0.3]'
StateFcnParameter
— State function parameters
vector
State function parameters, specified as a vector. Use this argument to specify a vector containing the initial parameters for the state function.
If your model has parameters, this property sets the initial value of
the StageParameter
field that is added to
onlinedata
. If your model does not have
parameters, the StateFcnParameter
field is not added
to onlinedata
, and you cannot set this
argument.
If the Optimization.Solver
property of
nlobj
is set to fmincon
(default value) and you do not specify the
StateFcnParameter
, then the default value of
this parameter is
zeros(length(nlobj.Model.ParameterLength),1)
.
Note
If you specify the Optimization.Solver
property of nlobj
as cgmres
,
and your model has parameters, you must specify
StateFcnParameter
.
Example: StateFcnParameter=[1 2.2 3
5]
StageParameter
— Stage parameters
vector
Stage parameters, specified as a vector. Use this argument to specify a vector containing the initial parameters for the different stages.
If your stage functions have parameters, this property sets the
initial values of the StageParameter
field that is
added to onlinedata
. If your stage functions do not
have parameters, the StageParameter
field is not
added to onlinedata
, and cannot to set this
argument.
If the Optimization.Solver
property of
nlobj
is set to fmincon
(default value) and you do not specify the
StageParameter
, then the default value of this
parameter is
zeros(sum([msobj.Stages.ParameterLength]),1)
.
Note
If you specify the Optimization.Solver
property of nlobj
as cgmres
,
and your stage functions have parameters, you must specify
StageFcnParameter
.
Example: StageParameter=[0 2 0 1]
Output Arguments
coreData
— Nonlinear MPC configuration parameters
structure
Nonlinear MPC configuration parameters that are constant at run time,
returned as a structure. These parameters are derived from the controller
settings in nlobj
. When simulating your controller,
pass coreData
to nlmpcmoveCodeGeneration
without changing any
parameters.
onlineData
— Online nonlinear MPC controller data
structure
Runtime simulation data, returned as a structure. The fields in the
structure depend on whether nlobj
is an
nlmpc
object or an nlmpcMultistage
object. During a simulation, you must supply this structure as an input to
nlmpcmoveCodeGeneration
at every control interval. nlmpcmoveCodeGeneration
then returns as output the updated
structure that you will need to supply as input in the following control
interval.
NonMultistage MPC
— Structure for generic MPC controllers
structure
For nlmpc
objects, the structure always
contains the following fields.
Field  Description 

ref  Output reference values, returned as a
column vector of zeros with length

mvTarget  Manipulated variable reference values, returned as a column vector of zeros with length N_{mv}, where N_{mv} is the number of manipulated variables. 
X0  Initial guess for the state trajectory,
returned as a column vector equal to

MV0  Initial guess for the manipulated
variable trajectory, returned as a column vector
equal to

Slack0  Initial guess for the slack variable, returned as zero. 
For nlmpc
objects,
onlineData
can also contain the
following fields, depending on the controller configuration and
argument values.
Field  Description 

md  Measured disturbance values — This
field is returned only when the controller has
measured disturbance inputs, that is, when

Parameters  Parameter values — This field is
returned only when the controller uses optional
model parameters. 
 Weight and constraint values — Each field is
returned only when the corresponding field name is
specified using the field
argument. The value of each field is equal to the
corresponding default value defined in the
controller, as returned in
coreData . 
For more information on configuring
onlineData
fields, see nlmpcmove
and nlmpcmoveCodeGeneration
.
Multistage MPC
— Structure for multistage MPC controllers
structure
For nlmpcMultistage
objects, the returned
onlineData
structure always contains
the InitialGuess
field.
Field  Description 

InitialGuess  Initial guess for the decision
variables, returned as a column vector of length
equal to the sum of the lengths of all the
decision variable vectors for each stage. For more
information, see 
For nlmpcMultistage
objects,
onlineData
can also contain the
following fields, depending on the controller configuration and
argument values.
Field  Description 

MeasuredDisturbances  Measured disturbance values — This
field is returned only when the controller has
measured disturbance inputs, that is, when

StateFcnParameters  Parameter values for state functions
and Jacobians — This field is returned only when
the controller state prediction function or its
Jacobian use model parameters, that is when

StageFcnParameters  Parameter values for stage cost and
constraints functions and their Jacobians— This
field is returned only when any stage cost or
constraint function, or its Jacobian, uses
parameters, that is when there is at least one
stage 
 Constraint values — Each field is returned
only when the corresponding field name is
specified using the field
argument. The value of each field is equal to the
corresponding default value defined in the
controller, as returned in
coreData . 
TerminalState  Terminal state, returned as a column
vector with as many elements as the number of
states. The terminal state is the desired state at
the last prediction step. To specify desired
terminal states at runtime via this field, you
must specify finite values in the

For more information on configuring
onlineData
fields, see nlmpcmove
and nlmpcmoveCodeGeneration
.
Version History
Introduced in R2020a
See Also
Functions
validateFcns
nlmpcmove
getSimulationData
nlmpcmoveCodeGeneration
buildMEX
codegen
(MATLAB Coder)
Objects
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)