nlmpcmoveopt

Option set for nlmpcmove function

Description

To specify options for the nlmpcmove function, use an nlmpcmoveopt option set.

Using this option set, you can specify run-time values for a subset of controller properties, such as tuning weights and constraints. If you do not specify a value for one of the nlmpcmoveopt properties, the corresponding value defined in the nlmpc controller object is used instead.

Creation

Syntax

options = nlmpcmoveopt

Description

options = nlmpcmoveopt creates a default set of options for the nlmpcmove function. To modify the property values, use dot notation.

Properties

OutputWeights — Output variable tuning weights

[] (default) | row vector | matrix

Output variable tuning weights that replace the Weights.OutputVariables property of the controller at run time, specified as a row vector or matrix of nonnegative values.

To use the same weights across the prediction horizon, specify a row vector of length N_y, where N_y is the number of output variables.

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

MVWeights — Manipulated variable tuning weights

[] (default) | row vector | matrix

Manipulated variable tuning weights that replace the Weights.ManipulatedVariables property of the controller at run time, specified as a row vector or matrix of nonnegative values.

To use the same weights across the prediction horizon, specify a row vector of length N_mv, where N_mv is the number of manipulated variables.

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

MVRateWeights — Manipulated variable rate tuning weights

[] (default) | row vector | matrix

Manipulated variable rate tuning weights that replace the Weights.ManipulatedVariablesRate property of the controller at run time, specified as a row vector or matrix of nonnegative values.

To use the same weights across the prediction horizon, specify a row vector of length N_mv, where N_mv is the number of manipulated variables.

To vary the tuning weights over the prediction horizon from time k to time k+p-1, specify an array with N_mv columns and up to p rows. Here, k is the current time and p is the prediction horizon. Each row contains the manipulated variable rate tuning weights for one prediction horizon step. If you specify fewer than p rows, the weights in the final row are used for the remaining steps of the prediction horizon.

ECR Weight — Slack variable tuning weight

[] (default) | positive scalar

Slack variable tuning weight that replaces the Weights.ECR property of the controller at run time, specified as a positive scalar.

OutputMin — Output variable lower bounds

[] (default) | row vector | matrix

Output variable lower bounds, specified as a row vector of length N_y or a matrix with N_y columns, where N_y is the number of output variables. OutputMin(:,i) replaces the OutputVariables(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.

OutputMax — Output variable upper bounds

[] (default) | row vector | matrix

Output variable upper bounds, specified as a row vector of length N_y or a matrix with N_y columns, where N_y is the number of output variables. OutputMax(:,i) replaces the OutputVariables(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.

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.

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.

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.

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.

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.

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.

MVTarget — Manipulated variable targets

[] (default) | row vector | matrix

Manipulated variable targets, 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.

To use the same manipulated variable targets across the prediction horizon, specify a row vector.

To vary the targets over the prediction horizon (previewing) 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 targets for one prediction horizon step. If you specify fewer than p rows, the final targets are used for the remaining steps of the prediction horizon.

Parameters — Parameter values

{} (default) | cell vector

Parameter values used by the prediction model, custom cost function, and custom constraints, specified as a cell vector with length equal to the Model.NumberOfParameters property of the controller. If the controller has no parameters, then Parameters must be {}.

The controller, nlmpcobj, passes these parameters to the:

• Model functions in nlmpcobj.Model (StateFcn and OutputFcn)

• Cost function nlmpcobj.Optimization.CustomCostFcn

• Constraint functions in nlmpcobj.Optimization (CustomEqConFcn and CustomIneqConFcn)

• Jacobian functions in nlmpcobj.Jacobian

• Passivity functions and their Jacobians in nlmpcobj.Passivity

The order of the parameters must match the order defined for these functions.

X0 — Initial guesses for the optimal state solutions

[] (default) | vector | matrix

Initial guesses for the optimal state solutions, specified as a row vector of length N_x or a matrix with N_x columns, where N_x is the number of states.

To use the same initial guesses across the prediction horizon, specify a row vector.

To vary the initial guesses 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 initial guesses for one prediction horizon step. If you specify fewer than p rows, the final guesses are used for the remaining steps of the prediction horizon.

If X0 is [], the default initial guesses are the current states of the prediction model (x input argument to nlmpcmove).

In general, during closed-loop simulation, you do not specify X0 yourself. Instead, when calling nlmpcmove, return the opt output argument, which is an nlmpcmoveopt object. opt.X0 contains the calculated optimal state trajectories as initial guesses. You can then pass opt in as the options 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.

MV0 — Initial guesses for the optimal manipulated variable solutions

[] (default) | vector | matrix

Initial guesses for the optimal manipulated variable solutions, 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.

To use the same initial guesses across the prediction horizon, specify a row vector.

To vary the initial guesses 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 initial guesses for one prediction horizon step. If you specify fewer than p rows, the final guesses are used for the remaining steps of the prediction horizon.

If MV0 is [], the default initial guesses are the control signals used in the plant at the previous control interval (lastmv input argument to nlmpcmove).

In general, during closed-loop simulation, you do not specify MV0 yourself. Instead, when calling nlmpcmove, return the opt output argument, which is an nlmpcmoveopt object. opt.MV0 contains the calculated optimal manipulated variable trajectories as initial guesses. You can then pass opt in as the options 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.

Slack0 — Initial guess for the slack variable at the solution

[] (default) | nonnegative scalar

Initial guess for the slack variable at the solution, specified as a nonnegative scalar. If Slack0 is [], the default initial guess is 0.

In general, during closed-loop simulation, you do not specify Slack0 yourself. Instead, when calling nlmpcmove, return the opt output argument, which is an nlmpcmoveopt object. opt.Slack contains the calculated slack variable as an initial guess. You can then pass opt in as the options 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.

Object Functions

nlmpcmove

Compute optimal control action for nonlinear MPC controller

Examples

Specify Run-Time Parameters for Nonlinear MPC

Create a default nlmpcmoveopt option set.

options = nlmpcmoveopt;

Specify the run-time values for the controller prediction model parameters. For this example, assume that the controller has the following optional parameters, which are input arguments to all the prediction model functions and custom functions of the controller.

• Sample time of the model, specified as a single numeric value. Specify a value of 0.25.

• Gain factors, specified as a two-element row vector. Specify a value of [0.7 0.35].

The order in which you specify the parameters must match the order specified in the custom function argument lists. Also, the dimensions of the parameters must match the dimensions expected by the custom functions.

options.Parameters = {0.25,[0.7 0.35]};

To use these parameters when computing optional control actions for a nonlinear MPC controller, pass options to the nlmpcmove function.

Version History

Introduced in R2018b