buildMEX

Build MEX file that solves an MPC control problem

Since R2020a

collapse all in page

Syntax

mexLinFcn = buildMEX(mpcobj,mexName,coreData,stateData,onlineData)

mexNlnFcn = buildMEX(nlobj,mexName,coreData,onlineData)

mexFcn = buildMEX(nlobj,mexName,coreData,onlineData,mexConfig)

Description

Linear MPC

mexLinFcn = buildMEX(mpcobj,mexName,coreData,stateData,onlineData) builds a MEX file that solves a linear MPC control problem faster than mpcmove. The MEX file is created in the current working folder.

example

Nonlinear MPC

mexNlnFcn = buildMEX(nlobj,mexName,coreData,onlineData) builds a MEX file that solves a nonlinear MPC control problem faster than nlmpcmove. The MEX file is created in the current working folder.

example

mexFcn = buildMEX(nlobj,mexName,coreData,onlineData,mexConfig) generates a MEX function using the code generation configuration object mexConfig. Use this syntax to customize your MEX code generation.

Examples

collapse all

Simulate Linear MPC Controller Using MEX File

Open Live Script

Create a plant model and design an MPC controller for the plant, with sample time 0.1.

plant = drss(1,1,1);plant.D = 0;
mpcobj = mpc(plant,0.1);

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

Simulate the plant using mpcmove for 5 steps.

x = 0;
xc = mpcstate(mpcobj);

-->No sample time in plant model. Assuming controller's sample time of 0.1.
-->Assuming output disturbance added to measured output #1 is integrated white noise.
-->"Model.Noise" is empty. Assuming white noise on each measured output.

for i=1:5
    % Update plant output.
    y = plant.C*x;
    % Compute control actions.
    u = mpcmove(mpcobj,xc,y,1);
    % Update plant state.
    x = plant.A*x + plant.B*u;
end

Display the final value of the plant output, input and next state.

[y u x]

ans = 1×3

    0.9999    0.3057   -2.3063

Generate data structures and build mex file.

[coreData,stateData,onlineData] = getCodeGenerationData(mpcobj);
mexfun = buildMEX(mpcobj, 'myMPCMex', coreData, stateData, onlineData);

Generating MEX function "myMPCMex" from linear MPC to speed up simulation.
Code generation successful.

MEX function "myMPCMex" successfully generated.

Simulate the plant using the mex file myMPCmex, which you just generated, for 5 steps.

x=0;
for i = 1:5
    % Update plant output.
    y = plant.C*x;
    % Update measured output in online data.
    onlineData.signals.ym = y;
    % Update reference signal in online data.
    onlineData.signals.ref = 1;
    % Compute control actions.
    [u,stateData] = myMPCMex(stateData,onlineData);
    % Update plant state.
    x = plant.A*x + plant.B*u;
end

Display the final value of the plant output, input and next state.

[y u x]

ans = 1×3

    0.9999    0.3057   -2.3063

Simulate Nonlinear MPC Controller Using MEX File

This example uses:

Open Live Script

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);

Specify the output reference value in the online data structure.

onlineData.ref = [0 0];

Build a MEX function for solving the nonlinear MPC control problem. The MEX function is created in the current working directory.

mexFcn = buildMEX(nlobj,"myController",coreData,onlineData);

Generating MEX function "myController" from nonlinear MPC to speed up simulation.
Code generation successful.

MEX function "myController" successfully generated.

Run the simulation for 10 seconds. During each control interval:

Correct the previous prediction using the current measurement.
Compute optimal control moves using the MEX function. This function returns the computed optimal sequences in onlineData. Passing the updated data structure to the MEX function in the next control interval provides initial guesses for the optimal sequences.
Predict the model states.
Apply the first computed optimal control move to the plant, updating the plant states.
Generate sensor data with white noise.
Save the plant states.

mv = mv0;
y = y0;
x = x0;
Duration = 10;
xHistory = x0;
for ct = 1:(Duration/Ts)
    % Correct previous prediction
    xk = correct(EKF,y);
    % Compute optimal control move
    [mv,onlineData] = myController(xk,mv,onlineData);
    % Predict prediction model states for the next iteration
    predict(EKF,[mv; Ts]);
    % Implement first optimal control move
    x = pendulumDT0(x,mv,Ts);
    % Generate sensor data
    y = x([1 3]) + randn(2,1)*0.01;
    % Save plant states
    xHistory = [xHistory x];
end

Plot the resulting state trajectories.

figure
subplot(2,2,1)
plot(0:Ts:Duration,xHistory(1,:))
xlabel('time')
ylabel('z')
title('cart position')
subplot(2,2,2)
plot(0:Ts:Duration,xHistory(2,:))
xlabel('time')
ylabel('zdot')
title('cart velocity')
subplot(2,2,3)
plot(0:Ts:Duration,xHistory(3,:))
xlabel('time')
ylabel('theta')
title('pendulum angle')
subplot(2,2,4)
plot(0:Ts:Duration,xHistory(4,:))
xlabel('time')
ylabel('thetadot')
title('pendulum velocity')

Input Arguments

collapse all

`mpcobj` — Model predictive controller
`mpc` object | `explicitMPC` object

Model predictive controller, specified as one of the following:

mpc object — Implicit MPC controller
explicitMPC object — Explicit MPC controller created using generateExplicitMPC.

`nlobj` — Nonlinear model predictive controller
`nlmpc` object | `nlmpcMultistage` object

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

Your controller must use the default fmincon solver with the SQP algorithm. Also, your controller must not use anonymous functions for its prediction model, custom cost function, or custom constraint functions.

`mexName` — MEX function name
string | character vector

MEX function name, specified as a string or character vector.

`coreData` — Controller configuration parameters
structure

Nonlinear MPC configuration parameters that are constant at run time, specified as a structure generated using getCodeGenerationData.

`stateData` — Linear controller state data structure
structure

Linear controller state data structure at run time, specified as a structure generated using getCodeGenerationData.

`onlineData` — Initial online controller data
structure

Initial online controller data, specified as a structure generated using getCodeGenerationData. For more information on setting the fields of onlineData, see nlmpcmoveCodeGeneration.

`mexConfig` — Code generation configuration object
`MexCodeConfig` object

Code generation configuration object, specified as a MexCodeConfig object.

To create the configuration object, use the following code.

mexConfig = coder.config('mex');

To customize your MEX code generation, modify the settings of this object. For example, to detect run-time memory access violations during debugging, set IntegrityChecks to true.

mexConfig.IntegrityChecks = true;

By default, to improve the performance of the generated code, checks such as IntegrityChecks and ResponsivenessChecks are disabled by buildMEX.

buildMEX overwrites the following configuration settings with the values indicated.

Configuration Setting	Value
`cfg.DynamicMemoryAllocation`	`'AllVariableSizeArrays'`
`cfg.ConstantInputs`	`'Remove'`

Output Arguments

collapse all

`mexLinFcn` — Generated MEX function for linear MPC
function handle

Generated MEX function for linear MPC, returned as a function handle. This MEX function has the following signature.

[mv,newStateData,info] = mexLinFcn(stateData,onlineData)

The MEX function has the following input arguments, which are the same as the corresponding input arguments of mpcmoveCodeGeneration, except configData, which is embedded in mexLinFcn.

Input Argument	Description
`stateData`	Current state data. Structure containing the state of the linear MPC controller. For more information on setting the fields of `onlineData`, see `mpcmoveCodeGeneration`.
`onlineData`	Online controller data that you must update at run time, specified as a structure. Generate the initial structure using `getCodeGenerationData`. For more information on setting the fields of `onlineData`, see `mpcmoveCodeGeneration`.

The MEX function has the following output arguments, which are the same as the output arguments of mpcmoveCodeGeneration.

Output Argument	Description
`mv`	Optimal manipulated variable control action, returned as a column vector of length N_mv, where N_mv is the number of manipulated variables.
`newStateData`	Updated state data. Structure containing the updated state of the linear MPC controller. For more information on setting the fields of `onlineData`, see `mpcmoveCodeGeneration`.
`info`	Solution details, returned as a structure.

To simulate a controller using the generated MEX function, use the initial online data structure onlineData for the first control interval. For subsequent control intervals, modify the online data in newOnlineData and pass the updated structure to the MEX function as onlineData.

`mexNlnFcn` — Generated MEX function for nonlinear MPC
function handle

Generated MEX function for nonlinear MPC, returned as a function handle. This MEX function has the following signature.

[mv,newOnlineData,info] = mexNlnFcn(x,lastMV,onlineData)

The MEX function has the following input arguments, which are the same as the corresponding input arguments of nlmpcmoveCodeGeneration.

Input Argument	Description
`x`	Current prediction model states, specified as a vector of length N_x, where N_x is the number of prediction model states.
`lastMV`	Control signals used in plant at previous control interval, specified as a vector of length N_mv, where N_mv is the number of manipulated variables.
`onlineData`	Online controller data that you must update at run time, specified as a structure. Generate the initial structure using `getCodeGenerationData`. For more information on setting the fields of `onlineData`, see `nlmpcmoveCodeGeneration`.

The MEX function has the following output arguments, which are the same as the output arguments of nlmpcmoveCodeGeneration.

Output Argument	Description
`mv`	Optimal manipulated variable control action, returned as a column vector of length N_mv, where N_mv is the number of manipulated variables.
`newOnlineData`	Updated online controller data, returned as a structure. This structure is the same as `onlineData`, except that the decision variable initial guesses are updated.
`info`	Solution details, returned as a structure.

Version History

Introduced in R2020a

buildMEX

Syntax

Description

Linear MPC

Nonlinear MPC

Examples

Simulate Linear MPC Controller Using MEX File

Simulate Nonlinear MPC Controller Using MEX File

Input Arguments

`mpcobj` — Model predictive controller
`mpc` object | `explicitMPC` object

`nlobj` — Nonlinear model predictive controller
`nlmpc` object | `nlmpcMultistage` object

`mexName` — MEX function name
string | character vector

`coreData` — Controller configuration parameters
structure

`stateData` — Linear controller state data structure
structure

`onlineData` — Initial online controller data
structure

`mexConfig` — Code generation configuration object
`MexCodeConfig` object

Output Arguments

`mexLinFcn` — Generated MEX function for linear MPC
function handle

`mexNlnFcn` — Generated MEX function for nonlinear MPC
function handle

Version History

See Also

Functions

Objects

Topics

buildMEX

Syntax

Description

Linear MPC

Nonlinear MPC

Examples

Simulate Linear MPC Controller Using MEX File

Simulate Nonlinear MPC Controller Using MEX File

Input Arguments

mpcobj — Model predictive controller mpc object | explicitMPC object

nlobj — Nonlinear model predictive controller nlmpc object | nlmpcMultistage object

mexName — MEX function name string | character vector

coreData — Controller configuration parameters structure

stateData — Linear controller state data structure structure

onlineData — Initial online controller data structure

mexConfig — Code generation configuration object MexCodeConfig object

Output Arguments

mexLinFcn — Generated MEX function for linear MPC function handle

mexNlnFcn — Generated MEX function for nonlinear MPC function handle

Version History

See Also

Functions

Objects

Topics

`mpcobj` — Model predictive controller
`mpc` object | `explicitMPC` object

`nlobj` — Nonlinear model predictive controller
`nlmpc` object | `nlmpcMultistage` object

`mexName` — MEX function name
string | character vector

`coreData` — Controller configuration parameters
structure

`stateData` — Linear controller state data structure
structure

`onlineData` — Initial online controller data
structure

`mexConfig` — Code generation configuration object
`MexCodeConfig` object

`mexLinFcn` — Generated MEX function for linear MPC
function handle

`mexNlnFcn` — Generated MEX function for nonlinear MPC
function handle