Main Content

getCodeGenerationData

Create data structures for nlmpcmoveCodeGeneration

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.

example

[coreData,onlineData] = getCodeGenerationData(nlobj,x,lastMV,params) when nlobj is an nlmpc object then this syntax copies initial parameter values in the onlineData structure. 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.

Examples

collapse all

Create a nonlinear MPC controller with four states, two outputs, and one input.

nlobj = nlmpc(4,2,1);
In standard cost function, zero weights are applied by default 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

collapse all

Nonlinear model predictive controller, specified as an nlmpc or nlmpcMultistage object.

Initial states of the nonlinear prediction model, specified as a column vector of length Nx, where Nx is the number of prediction model states.

Initial manipulated variable control signals, specified as a column vector of length Nmv, where Nmv is the number of manipulated variables.

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.

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

Output Arguments

collapse all

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.

Run-time simulation data, specified as structure with the following fields.

Online nonlinear MPC controller data that you must update at each control interval, returned as a structure. The structure always contains the following fields.

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

onlineData can also contain the following fields, depending on the controller configuration and argument values.

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

Online nonlinear multistage MPC controller data that you must update at each control interval, returned as a structure. The structure always contains the InitialGuess field.

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

onlineData can also contain the following fields, depending on the controller configuration and argument values.

FieldDescription
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, specified 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 nlmpcmoveand nlmpcmoveCodeGeneration.

Introduced in R2020a