# getSimulationData

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

*Since R2021a*

## Description

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 an initial simulation data structure for use with `simdata`

= getSimulationData(`nlmpcMSobj`

)`nlmpcmove`

.

## Examples

### Simulate Multistage Nonlinear MPC Controller Using Initial Guesses

This example shows how to create and simulate a simple multistage MPC controller in closed loop using initial guesses, with the MATLAB® function `nlmpcmove`

.

**Create Multistage MPC Controller**

Create a multistage MPC object with a seven-steps horizon, one state, and one manipulated variable.

msobj = nlmpcMultistage(7,1,1);

Defining your state and cost functions as separate files in the current folder on in a folder on the MATLAB path is recommended, as local functions are not supported for the generation of C/C++ deployment code. However, for this example, the state, cost, and state Jacobian functions are defined as local functions at the end of the example.

Specify the state transition function for the prediction model.

msobj.Model.StateFcn = @mystatefcn;

As a best practice, use Jacobians whenever they are available, otherwise the solver must compute it numerically. You can also automatically generate a Jacobian function using `generateJacobianFunction`

.

Specify the Jacobian of the state transition function.

msobj.Model.StateJacFcn = @mystatejac;

Specify the cost functions for all stages except the first.

for i=2:8 msobj.Stages(i).CostFcn = @mycostfcn; end

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

Initialize the plant state and input.

x=3; mv=0;

Create the initial simulation data structure.

simdata = getSimulationData(msobj)

`simdata = `*struct with fields:*
InitialGuess: []

Validate functions and the data structure.

validateFcns(msobj,x,mv,simdata);

Model.StateFcn is OK. Model.StateJacFcn is OK. "CostFcn" of the following stages [2 3 4 5 6 7 8] are OK. Analysis of user-provided model, cost, and constraint functions complete.

**Simulate Controller in Closed Loop**

Simulate the control loop for 5 steps.

for k=1:5 % calculate move and update simdata [mv,simdata] = nlmpcmove(msobj, x, mv, simdata); % simulate plant for one sample time [~,xhist] = ode45(@(t,xode) mystatefcn(xode,mv),[0 msobj.Ts],x); % update plant state x = xhist(end); end

Since updated initial guesses are supplied as an input argument within the `simdata`

structure, `nlmpcmove`

does not need to recalculate them at each time step, which saves computation time and improves performance. Updating initial guesses at every time step is a best practice.

Display the last values of the state and manipulated variables.

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

Final value of x =-0.039868

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

Final value of mv =-0.067044

**Support Functions**

State transition function.

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

Jacobian of the state transition function.

function [A,B] = mystatejac(x,~) A = -cos(x); B = 1; end

Stage cost functions.

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

## Input Arguments

`nlmpcMSobj`

— Nonlinear Multistage MPC controller

`nlmpcMultistage`

object

Multistage nonlinear MPC controller, specified as an `nlmpcMultistage`

object.

## Output Arguments

`simdata`

— Run-time simulation data structure

structure

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

`MeasuredDisturbance`

— Measured disturbance values

`[]`

(default) | row vector | array

Measured disturbance values, specified as a row vector of length
*N _{md}* or an array with

*N*columns, where

_{md}*N*is the number of measured disturbances. If your multistage MPC object has any measured disturbance channel defined, you must specify

_{md}`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, `nlmpcmove`

uses the values in the
final row for the remaining steps of the prediction horizon.

If you define measured disturbances in the input object, you must provide them
via `simdata`

at run-time.

`MVMin`

— Manipulated variable lower bounds

`[]`

(default) | row vector | matrix

Manipulated variable lower bounds, specified as a row vector of length
*N _{mv}* or a matrix with

*N*columns, where

_{mv}*N*is the number of manipulated variables.

_{mv}`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.

If `simdata`

does not contain a `MVMin`

field, then the manipulated variable lower bound (if present in the input object)
does not change at run time.

`MVMax`

— Manipulated variable upper bounds

`[]`

(default) | row vector | matrix

Manipulated variable upper bounds, specified as a row vector of length
*N _{mv}* or a matrix with

*N*columns, where

_{mv}*N*is the number of manipulated variables.

_{mv}`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.

If `simdata`

does not contain a `MVMax`

field, then the manipulated variable upper bound (if present in the input object)
does not change at run time.

`MVRateMin`

— Manipulated variable rate lower bounds

`[]`

(default) | row vector | matrix

Manipulated variable rate lower bounds, specified as a row vector of length
*N _{mv}* or a matrix with

*N*columns, where

_{mv}*N*is the number of manipulated variables.

_{mv}`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.

If `simdata`

does not contain a
`MVRateMin`

field, then the manipulated variable rate lower
bound (if present in the input object) does not change at run time.

`MVRateMax`

— Manipulated variable rate upper bounds

`[]`

(default) | row vector | matrix

Manipulated variable rate upper bounds, specified as a row vector of length
*N _{mv}* or a matrix with

*N*columns, where

_{mv}*N*is the number of manipulated variables.

_{mv}`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.

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.

If `simdata`

does not contain a
`MVRateMax`

field, then the manipulated variable rate upper
bound (if present in the input object) does not change at run time.

`StateMin`

— State lower bounds

`[]`

(default) | row vector | matrix

State lower bounds, specified as a row vector of length
*N _{x}* or a matrix with

*N*columns, where

_{x}*N*is the number of states.

_{x}`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.

If `simdata`

does not contain a
`StateMin`

field, then the state lower bound (if present in
the input object) does not change at run time.

`StateMax`

— State upper bounds

`[]`

(default) | row vector | matrix

State upper bounds, specified as a row vector of length
*N _{x}* or a matrix with

*N*columns, where

_{x}*N*is the number of states.

_{x}`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.

If `simdata`

does not contain a
`StateMax`

field, then the state upper bound (if present in
the input object) does not change at run time.

`StateFcnParameters`

— State function parameter values

`[]`

(default) | vector

State 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 `[]`

.

`StageParameters`

— Stage functions parameter values

`[]`

(default) | vector

Stage 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
`[]`

.

You must stack the parameter vectors for all stages in the column vector
`StageParameters`

as
follows.

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

`TerminalState`

— Terminal state

`[]`

(default) | vector

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 `nlmpcMSobj`

. Specify
`inf`

for the states that you do not need to constrain 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 `simdata`

does not contain a
`TerminalState`

field, then the terminal state constraint (if
present in the input object) does not change at run time.

`InitialGuess`

— Initial guesses for the decision variables

`[]`

(default) | vector

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

You must be stack the initial guesses for all stages in the column vector
`InitialGuess`

as
follows.

[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 `[]`

, then
`nlmpcmove`

calculates the initial guesses from its
`x`

and `lastmv`

arguments.

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.

## Version History

**Introduced in R2021a**

## MATLAB Command

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.

Select a Web Site

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

You can also select a web site from the following list:

## How to Get Best Site Performance

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

### Americas

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

### Europe

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