4. MathWorks MPC Toolbox Plugin¶
As a result of a longterm collaboration, MathWorks Inc. and Embotech AG developed a MATLAB® plugin for FORCES PRO. Users are now able to use the FORCES PRO solver in MATLAB® and Simulink® from within the MATLAB® Model Predictive Control Toolbox. The plugin leverages the powerful design capabilities of the MPC Toolbox™ and the computational performance of FORCES PRO. With FORCES PRO 2.0, toolbox users can now easily define challenging control problems and solve longhorizon MPC problems more efficiently.
Model Predictive Control Toolbox™ provides functions, an app, and Simulink® blocks for designing and simulating model predictive controllers. The toolbox lets users specify plant and disturbance models, horizons, constraints, and weights. Userfriendly control design capabilities of Model Predictive Control Toolbox™, combined with the powerful numerical algorithms of FORCES PRO, enables code deployment of the FORCES PRO solver on realtime hardware from within MATLAB® and Simulink®, in addition to the QP solvers shipped by MathWorks. The new FORCES PRO interface comes with various features such as Simulink blocks that can generate code runnable on embedded targets such as dSpace. The parameters of the MPC algorithm, such as plant and disturbance model, prediction horizon, constraints and moveblocking strategy can be specified directly. The toolbox allows users to run closedloop simulations and evaluation of controller performance. Userfriendly MPC design capabilities are combined with the powerful numerical algorithms of FORCES PRO. This combination of the MPC Toolbox™ and FORCES PRO enables code deployment on realtime hardware. The generated code is highly optimized for fast computations and low memory footprint.
The plugin mainly consists of the three following MATLAB commands which are described in details in this chapter:
mpcToForces
for generating a FORCES PRO solver from an MPC object designed by the MPC Toolbox
mpcmoveForces
for calling the generated solver on a specific MPC problem instance
mpcCustomSolver
for using the FORCES PRO dense QP solver as a custom solver
An auxiliary file is also exposed to the users for generating different solvers options, namely mpcToForcesOptions
.
The following LTI MPC features are supported:
Continuous and discrete time plant models
Move blocking
Measured disturbances
Unmeasured disturbances
Disturbance and noise models
Uniform or timevarying weights on outputs, manipulated variables, manipulated variables rates and ECR
Uniform or timevarying bounds on outputs, manipulated variables and manipulated variables rates
Soft constraints
Signal previewing on reference and measured disturbances
Scale factor
Nominal values
Online updates of weights and constraints
Builtin and custom state estimators
Currently, convex quadratic programs are supported by the MATLAB plugin. Extensions to adaptive, linear timevarying, nonlinear MPC are under development. The current limitations of the plugin are the following:
Mixed inputoutput constraints are not covered
Offdiagonal terms on the hessian of the objective cannot be implemented
Unconstrained problems are not supported
No singleprecision solvers
No suboptimal solutions
4.1. Different types of solvers¶
The plugin converts an MPC object (weights, bounds, horizons, references, output measurements) into a quadratic program (QP) formulated via the FORCES PRO API. One key design decision is to choose the decision variables in the quadratic program. There are two classic choices and they lead to two different formulations:
Dense QP, where only the manipulated variables \(MV\) or \(\Delta{}MV\) are decision variables. In this case, the hessian and linear constraints matrices are stored as dense matrices.
Sparse QP, where \(MV\), \(\Delta{}MV\), the outputs \(OV\) and the states \(X\) are decision variables. In this case, all matrices have a block sparse structure as in Lowlevel interface.
Typically, a dense QP has less optimization variables, zero equality constraints and many inequality constraints. Although the sparse QP is generally much larger than the dense QP its structure can be efficiently exploited to reduce the solve times. Besides, the dense formulation has an inherent flaw, which is that the condition number increases with the horizon length, especially when the plant states have large contributions to the plant inputs and outputs. Thus, the best solution is to allow users to switch to the sparse formulation, which prevents numerical blowups when the plant is unstable. Nevertheless, the dense formulation can be beneficial in terms of solve time when there is an important amount of moveblocking.
4.2. Generating a QP solver from an MPC object¶
Given an MPC object created by the mpc command, users can generate a QP solver tailored to their specific problem via the following command:
% mpcobj is the output of mpc(...) % options is the output of mpcToForcesOptions(...) [coredata, statedata, onlinedata, ~] = mpcToForces(mpcobj, options);
Two types of QP solvers can be generated via mpcToForces
: a sparse solver that corresponds to a multistage formulation as in Lowlevel interface and a dense solver that corresponds to a onestage QP with inequality constraints only.
The API of mpcToForces is described in more details in the tables below. The mpcToForces
command expects an MPC object mpcobj and a structure options as inputs.
Input 
Description 

mpcobj 
LTI MPC controller designed by MPC Toolbox 
options 
Object that provides solver generation options. 
The outputs of mpcToForces
consist of three structures coredata, statedata and onlinedata. The FORCES PRO server generates two types of solvers:
customForcesSparseQP when the option ‘sparse’ is set. An m file named `customForcesSparseQP.m` with the corresponding mex interface as well as the solver libraries and header in the `customForcesSparseQP` folder.
customForcesDenseQP when the option ‘dense’ is set. An m file named `customForcesDenseQP.m` with the corresponding mex interface as well as the solver libraries and header in the `customForcesDenseQP` folder.
The user is not allowed to change the generated solver name.
Output 
Type 
Description 

coredata 
Structure 
Store constant Store constant data needed to construct quadratic progam at runtime 
statedata 
Structure 
Represent prediction model states and last optimal MV. The index \(k\) stands for the current simulation time. It contains 4 fields: When builtin state estimation is used:
In this case, users should not manually change any field at runtime. When custom state estimation is used:
In this case, user should manually change Plant, Disturbance (if used), Noise (if used) fields at runtime but leave LastMove alone. 
onlinedata 
Structure 
Represent online signals It contains up to three fields:
ref (references of Output Variables) mvTarget (references of Manipulated Variables) md (when Measured Disturbance is present) ym (when using the builtin estimator) externalMV (when UseExternalMV is true in the options object)
y (when UseOnlineWeightOV is enabled) u (when UseOnlineWeightMV is enabled) du (when UseOnlineWeightMVRate is enabled) ecr (when UseOnlineWeightECR is enabled)
vmin (when UseOnlineConstraintOVMin is enabled) vmax (when UseOnlineConstraintOVMax is enabled) umin (when UseOnlineConstraintMVMin) umax (when UseOnlineConstraintMVMax) dumin (when UseOnlineConstraintMVRateMin) dumax (when UseOnlineConstraintMVRateMax) 
In order to provide the codegeneration options to mpcToForces
, the user needs to run the command mpcToForcesOptions
with one of the following two arguments as input:
“dense” for generating a onestage dense QP solvers
“sparse” for generating a multistage QP solver.
The structures provided by the mpcToForcesOptions
command have the following MPC related fields in common both in the “dense” and “sparse” case:
SkipSolverGeneration. When set to True, only structures are returned. If set to False, a solver mex interface is generated and the structures are returned. Default value is False.
UseOnlineWeightOV. When set to True, it allows Output Variables weights to vary at run time. Default is False.
UseOnlineWeightMV. When set to True, it allows Manipulated Variables weights to vary at run time. Default is False.
UseOnlineWeightMVRate. When set to True, it allows weights on the Manipulated Variables rates to vary at run time. Default is False.
UseOnlineWeightECR. When set to True, it allows weights on the ECR to change at run time. Default is False.
UseOnlineConstraintOVMax. When set to True, it allows updating the upper bounds on Output Variables at run time. Default is False.
UseOnlineConstraintOVMin. When set to True, it allows updating the lower bounds on Output Variables at run time. Default is False.
UseOnlineConstraintMVMax. When set to True, it allows updating the upper bounds on Manipulated Variables at run time. Default is False.
UseOnlineConstraintMVMin. When set to True, it allows updating the lower bounds on Manipulated Variables at run time. Default is False.
UseExternalMV. When set to True, the actual Manipulated Variable applied to the plant at time \(k1\) is provided as output. Default is False.
UseMVTarget. When set to True, an MV reference signal is provided via the
onlinedata
structure. In this case, MW weights should be positive for proper tracking. When false, the MV reference is the nominal value by default. In this case, MV weights should be zero to avoid unexpected behaviour.
Both the “dense” and “sparse” options structures have the following solver related fields in common:
ForcesServer is the FORCES PRO server url. Default is forces.embotech.com.
ForcesMaxIteration is the maximum number of iterations in a FORCES PRO solver. Default value is \(50\).
ForcesPrintLevel is the logging level of the FORCES PRO solver. If equal to \(0\), there is no output. If equal to \(1\), a summary line is printed after each solve. If equal to \(2\), a summary line is printed at every iteration. Default value is 0.
ForcesInitMethod is the initialization strategy used for the FORCES PRO interior point algorithm. If equal to \(0\), the solver is coldstarted. If equal to \(1\), a centered start is computed.
ForcesMu0 is the initial barrier parameter. It must be finite and positive. Its default value is equal to \(10\). A small value close to \(0.1\) generally leads to faster convergence but may be less reliable.
ForcesTolerance is the tolerance on the infinity norm of the residuals of the inequality constraints. It must be positive and finite. Its default value is \(10^{6}\).
4.3. Solving a QP from MPC online data¶
Once a QP solver has been generated it can be used to solve online MPC problems via the MATLAB command mpcmoveForces
as follows
% the coredata, statedata and onlinedata structures are outputs of mpcToForces [mv,statedata,info] = mpcmoveForces(coredata,statedata,onlinedata);
The outputs of the mpcmoveForces command are described below. In the table below \(n_m\) denotes the number of manipulated variables, \(n_x\) stands for the state dimension of the system implemented in the MPC object, \(p\) is the prediction horizon and \(k\) is the current solve time instant.
Output 
Type 
Description 

mv 
Vector of size 
Optimal manipulated variables at current solve time instant 
statedata 
Structure 
Initialized by 
info 
Structure 
Information about the FORCES solve

4.4. Using the FORCES PRO MPC Simulink block¶
Both the FORCES PRO sparse and dense solvers can be used inside Simulink. The dense QP formulation is usable from the shipped MPC controller block directly. For this, the following steps are needed:
Generate a custom dense FORCES PRO solver
options = mpcToForcesOptions('dense'); mpcToForces(mpcobj, options);
Set the following settings in the MPC object
mpcobj.Optimizer.CustomSolver = true; mpcobj.Optimizer.CustomSolverCodeGeneration = true;
The FORCES PRO sparse QP solver is also available via the MPC Toolbox in Simulink. A dedicated block has been implemented for this purpose. All features of the MATLAB plugin are available through this Simulink block, namely measured disturbances, external manipulated variables, references for manipulated variables, custom state estimation as well as online weights and constraints. Configuring the block is done via the user interface shown in Figure 4.1 below. Currently only the sparse QP solver can be used via the Simulink API.
In order to run an MPC simulation using the FORCES PRO block, a solver first needs to be generated via the following code for instance:
%% Generate FORCES PRO sparse QP solver options = mpcToForcesOptions('sparse'); % For this example we need to specify that online weights on the outputs, % the input rates and the ECR slacks are used options.UseOnlineWeightOV = true; options.UseOnlineWeightMVRate = true; options.UseOnlineWeightECR = true; [coredata, statedata, onlinedata] = mpcToForces(mpcobj, options);
The structures coredata and statedate needed by the FORCES PRO solver are then provided to the Simulink block via the window shown in Figure 4.1.
coredata is the variable name of the core data structure generated by mpcToForces in the base workspace.
initial state data is the variable name of the state data structure generated by mpcToForces in the base workspace. The user is expected to populate this structure with initial states of the plant and disturbances.
md checkbox should be selected if MD channels exist in the MPC object.
x[kk] checkbox needs to be selected for using a custom state estimator.
Optional outputs provide more information. It is recommended to monitor the qp.status port to check whether the MPC block produces a feasible solution.
The integration of the FORCES PRO MPC block in a Simulink model is shown in Figure 4.2 below.
The Simulink model can be run from MATLAB in the usual way.
% Start simulation. mdl = 'forcesmpc_onlinetuning'; open_system(mdl); % Open Simulink(R) Model sim(mdl); % Start Simulation
Finally, the FORCES PRO MPC block is available via the Library browser once the user has updated his client to the latest version of FORCES, as shown in Figure 4.3 below.
4.5. Deploy to dSpace MicroAutoBox II using the FORCES PRO MPC Simulink block¶
The FORCES PRO sparse solvers can be used inside Simulink to deploy to dSpace MicroAutoBox II. All features of the MATLAB plugin are available through this Simulink block, namely measured disturbances, external manipulated variables, references for manipulated variables, custom state estimation as well as online weights and constraints. Configuring the block is done via the user interface shown in Figure 4.4 below.
In order to run an MPC simulation in dSPACE using the FORCES PRO block, a solver first needs to be generated via the following code:
%% Generate FORCES PRO sparse QP solver options = mpcToForcesOptions('sparse'); % For this example we need to specify that online weights on the outputs, % the input rates and the ECR slacks are used options.UseOnlineWeightOV = true; options.UseOnlineWeightMVRate = true; options.UseOnlineWeightECR = true; options.ForcesTargetPlatform = 'dSPACEMABII'; [coredata, statedata, onlinedata] = mpcToForces(mpcobj, options);
Note that the option ForcesTargetPlatform needs to be specified. The structures coredata and statedate needed by the FORCES PRO solver are then provided to the Simulink block via the window shown in Figure 4.4. The integration of the FORCES PRO MPC block in a Simulink model is shown in Figure 4.5 below.
When creating the Simulink Model, in the Configurations, in the “Code Generation” tab, set the options (see Figure 4.6 below):
System target file:
rti1401.tlc
Language: C
Generate makefile: On
Template makefile:
rti1401.tmf
Make command:
make_rti
The Simulink model can be used for Code Generation from MATLAB in the usual way.
% Start Code Generation. mdl = 'forcesmpc_onlinetuning_dSpace_MicroAutoBoxII'; open_system(mdl); % Open Simulink(R) Model load_system(mdl); % Load Simulink(R) Model rtwbuild(mdl); % Start Code Generation
After code generation the dspace compiler (Microtec PowerPC) generated files to use to run your model on the MicroAutoBox II (see Figure 4.7).
Open dSpace Control Desk and select create new project (see Figure 4.8).
Name the project and the experiment (see Figure 4.9 and Figure 4.10).
Select the platform to which you will deploy the generated executable (see Figure 4.11).
Import the variable description file
forcesmpc_onlinetuning_dSpace_MicroAutoBoxII.sdf
in order to have access to the model variables and see the results of the execution (see Figure 4.12 and Figure 4.13).Click Finish to create the project (see Figure 4.14).
On the project layout select the tab
Variables
and on theforcesmpc_onlinetuning_dSpace_MicroAutoBoxII
category expandModel Root
(see Figure 4.15).Select
FORCES MPC (Sparse QP)
and Drag & Drop all the output variables together to the Layout. In the opened menu selectTime Plotter
(see Figure 4.16).Drag & Drop the output variables again and now choose
Display
(see Figure 4.17).To see all the plots concurrently rightclick on the left of the Yaxis and select
YAxesview
>Horizontal stacked
(see Figure 4.18).
Select the
Platforms/Devices
tab. RightClick on your platform and selectRealTime Application
>Load
. Choose the executable fileforcesmpc_onlinetuning_dSpace_MicroAutoBoxII.ppc
(see Figure 4.19 and Figure 4.20).Select
Go Online
andStart Measuring
to see the results. (see Figure 4.21 and Figure 4.22).
4.6. Examples¶
The plugin comes with several examples to demonstrate its functionalities and flexibility.
The packaged examples are the following ones:
forcesmpc_cstr.m
is a linear timeinvariant (LTI) MPC example with unmeasured outputs. It also shows how to use the MATLAB Coder for generating and running mpcmoveForces as a mex interface, which results in lower simulation times.Code is available
here
.forcesmpc_targets.m
is an LTI MPC example with a reference on one manipulated variablesCode is available
here
.forcesmpc_preview.m
is an LTI MPC example with previewing on the output reference and the measured disturbanceCode is available
here
.forcesmpc_motor.m
is an LTI MPC example with state and input constraintsCode is available
here
.forcesmpc_miso.m
is an LTI MPC example with one measured output, one manipulated variable, one measured disturbance, and one unmeasured disturbanceCode is available
here
.forcesmpc_simplelti.m
demonstrates a simple LTI MPC designedCode is available
here
.forcesmpc_linearize.m
is an example of linear MPC around an operating point of a nonlinear system.Code is available
here
.forcesmpc_customqp.m
shows how to use the FORCES PRO dense QP solver as a custom solver in an MPC objectCode is available
here
.forcesmpc_run_onlinetuning.m
demonstrates how to run the MPC Simulink block.Code is available
here
.forcesmpc_run_onlinetuning_dSpace_MicroAutoBoxII.m
demonstrates how to generate code for dSpace MicroAutoBox II using the MPC Simulink block.Code is available
here
.
The forcesmpc_linearize.m
example is described in more details below. First, the linearized model and the operating point are defined.
%% Load plant model linearized at its nominal operating point (x0, u0, y0) load('nomConditionsLinearize.mat');
An MPC controller object is then created with a prediction horizon of length \(p = 20\), a control horizon \(m = 3\) and a sampling period \(T_s = 0.1\) seconds as explained here.
%% Design MPC Controller % Create an MPC controller object with a specified sample time Ts, % prediction horizon p, and control horizon m. Ts = 0.1; p = 20; m = 3; mpcobj = mpc(plant,Ts,p,m);
Nominal values need to be set in the MPC object.
% Set the nominal values in the controller. mpcobj.Model.Nominal = struct('X',x0,'U',u0,'Y',y0);
Constraints are set on the manipulated variables and an output reference signal is provided.
% Set the manipulated variable constraint. mpcobj.MV.Max = 0.2; % Specify the reference value for the output signal. r0 = 1.5*y0;
From the MPC object and a structure of options, a FORCES PRO solver can be generated.
% Create options structure for the FORCES PRO sparse QP solver options = mpcToForcesOptions(); % Generates the FORCES PRO QP solver [coredata, statedata, onlinedata] = mpcToForces(mpcobj, options);
Once a reference signal has been constructed, the simulation can be run using mpcmoveForces
.
for t = 1:Tf % A measurement noise is simulated Y(:, t) = dPlant.C * (X(:, t)  x0) + dPlant.D * (U(:, t)  u0) + y0 + 0.01 * randn; % Prepare inputs of mpcmoveForces onlinedata.signals.ref = r(t:min(t+mpcobj.PredictionHorizon1,Tf),:); onlinedata.signals.ym = Y(:, t); % Call FORCES PRO solver [mv, statedata, info] = mpcmoveForces(coredata, statedata, onlinedata); if info.ExitFlag < 0 warning('Internal problem in FORCES PRO solver'); end U(:, t) = mv; X(:, t+1) = dPlant.A * (X(:, t)  x0) + dPlant.B * (U(:, t)  u0) + x0; end
The resulting input and output signals are shown in Figure Figure 4.23 and Figure Figure 4.24 respectively.