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.

example

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

[___] = getCodeGenerationData(___,field) adds the specified online weight and constraint field to the onlineData structure.

[___] = getCodeGenerationData(___,field1,...,fieldn) adds multiple online weight and constraint fields 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 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, 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 {}.

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 Tuning Weights

  • "OutputWeights" — Output variable weights

  • "MVWeights" — Manipulated variable weights

  • "MVRateWeights" — Manipulated variable rate weights

  • "ECRWeight" — Slack variable weight

Online Constraints

  • "OutputMin" — Output variable lower bounds

  • "OutputMax" — Output variable upper bounds

  • "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

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 nlmpcobj. When simulating your controller, pass coreData to nlmpcmoveCodeGeneration without changing any parameters.

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

Introduced in R2020a