Main Content

Create data structure to simulate multistage MPC controller with
`nlmpcmove`

Use this function to create a default data structure to simulate a multistage MPC
controller with the `nlmpcmove`

function.

For information on generating data structures for `mpcmoveCodeGeneration`

, see `getCodeGenerationData`

.

creates initial simulation data structure for use with `simdata`

= getSimulationData(`nlmpcMSobj`

)`nlmpcmove`

.

This example shows how to create and simulate a very simple multistage MPC controller in closed loop.

**Create a Multistage MPC Controller**

Create a multistage mpc object with a 7 steps horizon, one state, one manipulated variable.

nlmsobj = nlmpcMultistage(7,1,1);

Specify the state transition function for the prediction model (`mystatefcn`

is defined at the end of the file).

nlmsobj.Model.StateFcn = @mystatefcn;

It is best practice to use Jacobians whenever they are available, otherwise the solver must compute it numerically.

Specify the jacobian of the state transition function (`mystatejacobian`

is defined at the end of the file).

nlmsobj.Model.StateJacFcn = @mystatejac;

Specify the cost functions for all stages except the first two (`mycostfcn`

is defined at the end of the file).

for i=3:8 nlmsobj.Stages(6).CostFcn = @mycostfcn; end

**Define Initial Conditions, Create Data Structure and Validate Functions**

Initialize plant state and input.

x=3; mv=0;

Create initial simulation data structure.

simdata = getSimulationData(nlmsobj)

`simdata = `*struct with fields:*
StateMin: []
StateMax: []
MVMin: []
MVMax: []
InitialGuess: []

Validate functions and data structure.

validateFcns(nlmsobj,x,mv,simdata);

Model.StateFcn is OK. Model.StateJacFcn is OK. "CostFcn" of the following stages 6 are OK. Analysis of user-provided model, cost, and constraint functions complete.

**Simulate the Controller in Closed Loop**

Simulate the control loop for 10 steps.

for k=1:10 [mv,simdata] = nlmpcmove(nlmsobj, x, mv, simdata); % calculate move x = x + (mv-sqrt(x))*1; % update x: x(t+1)=x(t)+xdot*Ts end

Display last value of the state and manipulated variables.

`disp(['Final value of x =' num2str(x)])`

Final value of x =1.6556

`disp(['Final value of mv =' num2str(mv)])`

Final value of mv =1.2816

**Support functions**

State transition function.

function xdot = mystatefcn(x,u) xdot = u-sqrt(x); end

Jacobian of the state transition function.

function [A,B] = mystatejac(x,~) A = -1/(2*x^(1/2)); B = 1; end

Stage cost functions.

function j = mycostfcn(s,x,u) j = abs(u)/s+s*x^2; end

`nlmpcMSobj`

— Nonlinear Multistage MPC controller`nlmpcMultistage`

objectMultistage nonlinear MPC controller, specified as an `nlmpcMultistage`

object.

`simdata`

— Run-time simulation data structurestructure

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

`MeasuredDisturbance`

— Measured disturbance values`[]`

(default) | row vector | arrayMeasured disturbance values, specified as a row vector of length
*N _{md}* or an array with

`MeasuredDisturbance`

. If your
controller has no measured disturbances, you can omit this field in the structure
or specify it as `[]`

.To use the same disturbance values across the prediction horizon, specify a row vector.

To vary the disturbance values over the prediction horizon from time
*k* to time *k*+*p*, specify
an array with up to *p*+1 rows. Here, *k* is the
current time and *p* is the prediction horizon. Each row contains
the disturbance values for one prediction horizon step. If you specify fewer than
*p* rows, the values in the final row are used for the
remaining steps of the prediction horizon.

`MVMin`

— Manipulated variable lower bounds`[]`

(default) | row vector | matrixManipulated variable lower bounds, specified as a row vector of length
*N _{mv}* or a matrix with

`MVMin(:,i)`

replaces the
`ManipulatedVariables(i).Min`

property of the controller at run
time.To use the same bounds across the prediction horizon, specify a row vector.

To vary the bounds over the prediction horizon from time *k*
to time *k*+*p*-1, specify a matrix with up to
*p* rows. Here, *k* is the current time and
*p* is the prediction horizon. Each row contains the bounds for
one prediction horizon step. If you specify fewer than *p* rows,
the final bounds are used for the remaining steps of the prediction
horizon.

`MVMax`

— Manipulated variable upper bounds`[]`

(default) | row vector | matrixManipulated variable upper bounds, specified as a row vector of length
*N _{mv}* or a matrix with

`MVMax(:,i)`

replaces the
`ManipulatedVariables(i).Max`

property of the controller at run
time.To use the same bounds across the prediction horizon, specify a row vector.

To vary the bounds over the prediction horizon from time *k*
to time *k*+*p*-1, specify a matrix with up to
*p* rows. Here, *k* is the current time and
*p* is the prediction horizon. Each row contains the bounds for
one prediction horizon step. If you specify fewer than *p* rows,
the final bounds are used for the remaining steps of the prediction
horizon.

`MVRateMin`

— Manipulated variable rate lower bounds`[]`

(default) | row vector | matrixManipulated variable rate lower bounds, specified as a row vector of length
*N _{mv}* or a matrix with

`MVRateMin(:,i)`

replaces the
`ManipulatedVariables(i).RateMin`

property of the controller at
run time. `MVRateMin`

bounds must be nonpositive.To use the same bounds across the prediction horizon, specify a row vector.

To vary the bounds over the prediction horizon from time *k*
to time *k*+*p*-1, specify a matrix with up to
*p* rows. Here, *k* is the current time and
*p* is the prediction horizon. Each row contains the bounds for
one prediction horizon step. If you specify fewer than *p* rows,
the final bounds are used for the remaining steps of the prediction
horizon.

`MVRateMax`

— Manipulated variable rate upper bounds`[]`

(default) | row vector | matrixManipulated variable rate upper bounds, specified as a row vector of length
*N _{mv}* or a matrix with

`MVRateMax(:,i)`

replaces the
`ManipulatedVariables(i).RateMax`

property of the controller at
run time. `MVRateMax`

bounds must be nonnegative.To use the same bounds across the prediction horizon, specify a row vector.

*k*
to time *k*+*p*-1, specify a matrix with up to
*p* rows. Here, *k* is the current time and
*p* is the prediction horizon. Each row contains the bounds for
one prediction horizon step. If you specify fewer than *p* rows,
the final bounds are used for the remaining steps of the prediction
horizon.

`StateMin`

— State lower bounds`[]`

(default) | row vector | matrixState lower bounds, specified as a row vector of length
*N _{x}* or a matrix with

`StateMin(:,i)`

replaces the `States(i).Min`

property of the controller at run time.To use the same bounds across the prediction horizon, specify a row vector.

To vary the bounds over the prediction horizon from time
*k*+1 to time *k*+*p*, specify
a matrix with up to *p* rows. Here, *k* is the
current time and *p* is the prediction horizon. Each row contains
the bounds for one prediction horizon step. If you specify fewer than
*p* rows, the final bounds are used for the remaining steps of
the prediction horizon.

`StateMax`

— State upper bounds`[]`

(default) | row vector | matrixState upper bounds, specified as a row vector of length
*N _{x}* or a matrix with

`StateMax(:,i)`

replaces the `States(i).Max`

property of the controller at run time.To use the same bounds across the prediction horizon, specify a row vector.

To vary the bounds over the prediction horizon from time
*k*+1 to time *k*+*p*, specify
a matrix with up to *p* rows. Here, *k* is the
current time and *p* is the prediction horizon. Each row contains
the bounds for one prediction horizon step. If you specify fewer than
*p* rows, the final bounds are used for the remaining steps of
the prediction horizon.

`StateFcnParameters`

— State function parameter values`[]`

(default) | vectorState function parameter values, specified as a vector with length equal to
the value of the `Model.ParameterLength`

property of the
multistage controller object. If `Model.StateFcn`

needs a
parameter vector, you must provide its value at runtime using this field,
otherwise you can omit this field or set it to `[]`

.

`StateFcnParameters`

— State function parameter values`[]`

(default) | vectorStage functions parameter values, specified as a vector with length equal to
the sum of all the values in the `Stages(i).ParameterLength`

properties of the multistage controller object. If any cost or constraint function
defined in the `Stages`

property needs a parameter vector, you
must provide all the parameter vectors at runtime (stacked in a single column)
using this field, otherwise you can omit this field or set it to
`[]`

.

The parameter vectors for all stages must be stacked in the column vector
`StateFcnParameters`

as:

[parameter vector for stage 1; parameter vector for stage 2; ... parameter vector for stage p+1; ]

`TerminalState`

— Terminal state`[]`

(default) | vectorTerminal 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 `nlmpcMSobj`

. Specify
`inf`

for the states that do not need to be constrained to a
terminal value. At run time, `nlmpcmove`

ignores any values in the
`TerminalState`

field of `simdata`

that
correspond to `inf`

values in `nlmpcMSobj`

. If
you do not specify any terminal value condition in
`nlmpcMSobj`

, this field is not created in
`simdata`

.

If there is no `TerminalState`

in
`simdata`

then the terminal state constraint (if present)
does not change at run time.

`InitialGuess`

— Initial guesses for the decision variables`[]`

(default) | vectorInitial guesses for the decision variables, specified as a row vector of length equal to the sum of the lengths of all the decision variable vectors for each stages.

The initial guesses for all stages must be stacked in the column vector
`InitialGuess`

as:

[state vector guess for stage 1; manipulated variable vector guess for stage 1; manipulated variable vector rate guess for stage 1; % if used slack variable vector guess for stage 1; % if used state vector guess for stage 2; manipulated variable vector guess for stage 2; manipulated variable vector rate guess for stage 2; % if used slack variable vector guess for stage 2; % if used ... state vector guess for stage p+1; manipulated variable vector guess for stage p+1; manipulated variable vector rate guess for stage p+1; % if used slack variable vector guess for stage p+1; % if used ]

If `InitialGuess`

is `[]`

, the default
initial guesses are calculated from the `x`

and
`lastmv`

arguments passed to
`nlmpcmove`

).

In general, during closed-loop simulation, you do not specify
`InitialGuess`

yourself. Instead, when calling `nlmpcmove`

, return the `simdata`

output argument,
which contains the calculated initial guesses for the next control interval. You
can then pass `simdata`

as an input argument to
`nlmpcmove`

for the next control interval. These steps are a
best practice, even if you do not specify any other run-time options.

You have a modified version of this example. Do you want to open this example with your edits?

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

Select web siteYou can also select a web site from the following list:

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

- América Latina (Español)
- Canada (English)
- United States (English)

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)