Main Content

getSimulationData

Create data structure to simulate multistage MPC controller with nlmpcmove

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.

example

simdata = getSimulationData(nlmpcMSobj) creates initial simulation data structure for use with nlmpcmove.

Examples

collapse all

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

Input Arguments

collapse all

Multistage nonlinear MPC controller, specified as an nlmpcMultistage object.

Output Arguments

collapse all

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

Measured disturbance values, specified as a row vector of length Nmd or an array with Nmd columns, where Nmd 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, the values in the final row are used for the remaining steps of the prediction horizon.

Manipulated variable lower bounds, specified as a row vector of length Nmv or a matrix with Nmv columns, where Nmv 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.

Manipulated variable upper bounds, specified as a row vector of length Nmv or a matrix with Nmv columns, where Nmv 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.

Manipulated variable rate lower bounds, specified as a row vector of length Nmv or a matrix with Nmv columns, where Nmv 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.

Manipulated variable rate upper bounds, specified as a row vector of length Nmv or a matrix with Nmv columns, where Nmv 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.

State lower bounds, specified as a row vector of length Nx or a matrix with Nx columns, where Nx 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.

State upper bounds, specified as a row vector of length Nx or a matrix with Nx columns, where Nx 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.

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

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

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

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

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.

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.

Introduced in R2021a