getSimulationData

Create data structure to simulate multistage MPC controller with nlmpcmove

Since R2021a

Syntax

simdata = getSimulationData(nlmpcMSobj)

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.

simdata = getSimulationData(nlmpcMSobj) creates an initial simulation data structure for use with 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_md columns, where N_md is the number of measured disturbances. If your multistage MPC object has any measured disturbance channel defined, you must specify 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_mv columns, where N_mv is the number of manipulated variables. 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_mv columns, where N_mv is the number of manipulated variables. 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_mv columns, where N_mv is the number of manipulated variables. 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_mv columns, where N_mv is the number of manipulated variables. 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_x columns, where N_x is the number of states. 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_x columns, where N_x is the number of states. 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