getCodeGenerationData

Create data structures for nlmpcmoveCodeGeneration

Since R2020a

Syntax

[coreData,onlineData] = getCodeGenerationData(nlobj,x,lastMV)

[coreData,onlineData] = getCodeGenerationData(nlobj,x,lastMV,params)

[___] = getCodeGenerationData(___,field)

[___] = getCodeGenerationData(___,field1,...,fieldn)

[___] = getCodeGenerationData(___,Name=Value)

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.

[coreData,onlineData] = getCodeGenerationData(nlobj,x,lastMV) creates data structures for use with nlmpcmoveCodeGeneration.

[coreData,onlineData] = getCodeGenerationData(nlobj,x,lastMV,params) copies initial parameter values in the 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(___,field) enables the specified online weight or constraint field by adding it to the onlineData structure.

[___] = getCodeGenerationData(___,field1,...,fieldn) enables multiple online weight or constraint fields by adding them to the onlineData structure.

[___] = getCodeGenerationData(___,Name=Value) when nlobj is a nlmpcMultistage object, you can specify measured disturbance inputs or the state and stage functions parameters using one or more name-value 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 discrete-time model integrates the continuous-time 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 user-provided 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 non-Multistage 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

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value 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

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

Non-Multistage 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 Ny, where Ny is the number of prediction model outputs.
mvTarget	Manipulated variable reference values, returned as a column vector of zeros with length Nmv, where Nmv is the number of manipulated variables.
X0	Initial guess for the state trajectory, returned as a column vector equal to x.
MV0	Initial guess for the manipulated variable trajectory, returned as a column vector equal to lastMV.
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 nlobj.Dimensions.MDIndex is nonzero. md is returned as a column vector of zeros with length Nmd, where Nmd is the number of measured disturbances.
Parameters	Parameter values — This field is returned only when the controller uses optional model parameters. Parameters is returned as a cell vector equal to params.
OutputWeights MVWeights MVRateWeights ECRWeight OutputMin OutputMax StateMin StateMax MVMin MVMax MVRateMin MVRateMax	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 nlmpcmove.

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 nlobj.Dimensions.MDIndex is nonzero. md is returned as a column vector of zeros with length Nmd, where Nmd is the number of measured disturbances.
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 Model.ParameterLength is greater than zero. StateFcnParameter is returned as a vector.
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 i for which Stages(i).ParameterLength is greater than zero. StageFcnParameter is returned as a vector.
StateMin StateMax MVMin MVMax MVRateMin MVRateMax	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 run-time via this field, you must specify finite values in the TerminalState field of the Model property of nlobj. Specify inf for the states that do not need to be constrained to a terminal value. At run time, nlmpcmoveCodeGeneration ignores any values in the TerminalState field of simdata that correspond to inf values in nlobj. If you do not specify any terminal value condition in nlobj, this field is not created in onlinedata.

For more information on configuring onlineData fields, see nlmpcmove and nlmpcmoveCodeGeneration.

Version History

Introduced in R2020a