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
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, 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
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.
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
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.
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
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.
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
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.
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
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.
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
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.
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-Befehl
Sie haben auf einen Link geklickt, der diesem MATLAB-Befehl entspricht:
Führen Sie den Befehl durch Eingabe in das MATLAB-Befehlsfenster aus. Webbrowser unterstützen keine MATLAB-Befehle.
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)