Main Content

Multistage Nonlinear MPC Controller

Simulate multistage nonlinear model predictive controllers

Since R2021a

expand all in page
  • Multistage Nonlinear MPC Controller block

Libraries:
Model Predictive Control Toolbox

Description

The Multistage Nonlinear MPC Controller block simulates a multistage nonlinear model predictive controller. At each control interval, the block computes optimal control moves by solving a nonlinear programming problem in which different cost functions and constraints are defined for different prediction steps (stages). For more information on nonlinear MPC, see Nonlinear MPC.

To use this block, you must first create an nlmpcMultistage object in the MATLAB® workspace.

Examples

Truck and Trailer Automatic Parking Using Multistage Nonlinear MPC

Truck and Trailer Automatic Parking Using Multistage Nonlinear MPC

Use multistage nonlinear MPC to park a truck and trailer system in presence of static obstacles.

Landing a Vehicle Using Multistage Nonlinear MPC

Landing a Vehicle Using Multistage Nonlinear MPC

Plan an optimal rocket lander trajectory and perform closed-loop control of landing process using multistage nonlinear MPC.

Limitations

  • None of the Multistage Nonlinear MPC Controller block parameters are tunable.

Ports

Input

expand all

Required Inputs

Current prediction model states, specified as a vector signal of length Nx, where Nx is the number of prediction model states. Since the nonlinear MPC controller does not perform state estimation, you must either measure or estimate the current prediction model states at each control interval.

Control signals used in plant at previous control interval, specified as a vector signal of length Nmv, where Nmv is the number of manipulated variables.

Note

Connect last_mv to the MV signals actually applied to the plant in the previous control interval. Typically, these MV signals are the values generated by the controller, though sometimes they can come from a different source. For example, if your controller is offline and running in tracking mode, (that is, the controller output is not driving the plant), then feeding the actual plant input to last_mv can help achieve bumpless transfer when the controller is switched back online.

Additional Inputs

If your controller prediction model has measured disturbances you must enable this port and connect to it a row vector or matrix signal.

To use the same measured disturbance values across the prediction horizon, connect md to a row vector signal with Nmd elements, where Nmd is the number of manipulated variables. Each element specifies the value for a measured disturbance.

To vary the disturbances over the prediction horizon (previewing) from time k to time k+p, connect md to a matrix signal with Nmd columns and up to p+1 rows. Here, k is the current time and p is the prediction horizon. Each row contains the disturbances for one prediction horizon step. If you specify fewer than p+1 rows, the final disturbances are used for the remaining steps of the prediction horizon.

Dependencies

To enable this port, select the Measured disturbances parameter.

If your controller uses optional parameters in its prediction model, enable this input port, and connect a vector signal with Npm elements, where Npm is the number of state parameters (equal to the Model.ParameterLength property of the nlmpcMultistage controller object). The controller passes these parameters to its model state transition and state Jacobian functions.

If your controller does not use optional parameters, you must disable the state.param port.

Dependencies

To enable this port, select the StateFcn parameters parameter.

If your controller uses optional parameters in any stage cost or constraint function, enable this input port, and connect a vector signal with Npv elements, where Npv is the total number of parameters for all stage functions, and is equal to sum(Stages.ParameterLength). The parameters for all stages are stacked in the parameter vector as follows.

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

At each stage, the controller passes the relevant parameter vector to the stage cost and constraint functions active at that stage.

If your controller does not use optional parameters, you must disable the stage.param port. For more information, see nlmpcMultistage and nlmpcmove.

Dependencies

To enable this port, select the Stacked stage parameters parameter.

Online Constraints

To specify run-time minimum manipulated variable constraints, enable this input port. If this port is disabled, the block uses the lower bounds specified in the ManipulatedVariables.Min property of its controller object.

To use the same bounds over the prediction horizon, connect mv.min to a row vector signal with Nmv elements, where Nmv is the number of outputs. Each element specifies the lower bound for a manipulated variable.

To vary the bounds over the prediction horizon from time k to time k+p–1, connect mv.min to a matrix signal with Ny columns and 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 bounds in the final row apply for the remainder of the prediction horizon.

Dependencies

To enable this port, select the Lower MV limits parameter.

To specify run-time maximum manipulated variable constraints, enable this input port. If this port is disabled, the block uses the upper bounds specified in the ManipulatedVariables.Max property of its controller object.

To use the same bounds over the prediction horizon, connect mv.max to a row vector signal with Nmv elements, where Nmv is the number of outputs. Each element specifies the upper bound for a manipulated variable.

To vary the bounds over the prediction horizon from time k to time k+p–1, connect mv.max to a matrix signal with Ny columns and 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 bounds in the final row apply for the remainder of the prediction horizon.

Dependencies

To enable this port, select the Upper MV limits parameter.

To specify run-time minimum manipulated variable rate constraints, enable this input port. If this port is disabled, the block uses the lower bounds specified in the ManipulatedVariable.RateMin property of its controller object. dmv.min bounds must be nonpositive.

To use the same bounds over the prediction horizon, connect dmv.min to a row vector signal with Nmv elements, where Nmv is the number of outputs. Each element specifies the lower bound for a manipulated variable rate of change.

To vary the bounds over the prediction horizon from time k to time k+p–1, connect dmv.min to a matrix signal with Ny columns and 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 bounds in the final row apply for the remainder of the prediction horizon.

Dependencies

To enable this port, select the Lower MVRate limits parameter.

To specify run-time maximum manipulated variable rate constraints, enable this input port. If this port is disabled, the block uses the upper bounds specified in the ManipulatedVariables.RateMax property of its controller object. dmv.max bounds must be nonnegative.

To use the same bounds over the prediction horizon, connect dmv.max to a row vector signal with Nmv elements, where Nmv is the number of outputs. Each element specifies the upper bound for a manipulated variable rate of change.

To vary the bounds over the prediction horizon from time k to time k+p–1, connect dmv.max to a matrix signal with Ny columns and 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 bounds in the final row apply for the remainder of the prediction horizon.

Dependencies

To enable this port, select the Upper MVRate limits parameter.

To specify run-time minimum state constraints, enable this input port. If this port is disabled, the block uses the lower bounds specified in the States.Min property of its controller object.

To use the same bounds over the prediction horizon, connect x.min to a row vector signal with Nx elements, where Nx is the number of outputs. Each element specifies the lower bound for a state.

To vary the bounds over the prediction horizon from time k+1 to time k+p, connect x.min to a matrix signal with Ny columns and 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 bounds in the final row apply for the remainder of the prediction horizon.

Dependencies

To enable this port, select the Lower state limits parameter.

To specify run-time maximum state constraints, enable this input port. If this port is disabled, the block uses the upper bounds specified in the States.Max property of its controller object.

To use the same bounds over the prediction horizon, connect x.max to a row vector signal with Nx elements, where Nx is the number of outputs. Each element specifies the upper bound for a state.

To vary the bounds over the prediction horizon from time k+1 to time k+p, connect x.max to a matrix signal with Ny columns and 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 bounds in the final row apply for the remainder of the prediction horizon.

Dependencies

To enable this port, select the Upper state limits parameter.

Others

Terminal state, specified as a vector signal of length Nx. To specify desired terminal state constraints, enable this input port. To specify desired terminal states at run-time via this input port, you must specify finite values in the TerminalState field of the Model property of the nlmpcMultistage object that is passed as a parameter to the block. Specify inf for the states that you do not need to constrain to a terminal value. At run time, the block ignores any values in the input signal that correspond to inf values in the object. If you do not specify any terminal value condition in the nlmpcMultistage object, the signal at this input port is ignored at runtime.

If this port is not enabled the terminal state constraint (if present) does not change at run time.

Dependencies

To enable this port, select the Terminal state parameter.

To specify initial guesses for the decision variable vector, enable this input port. If this port is disabled, the block uses the decision variable sequences calculated in the previous control interval as initial guesses. Good initial guesses are important since they help the solver to converge to a solution faster.

z0 is a column vector of length equal to the sum of the lengths of all the decision variable vectors for each stage. The initial guesses must be stacked 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;
 manipulated variable vector guess for stage p;
 manipulated variable vector rate guess for stage p; % if used
 slack variable vector guess for stage p; % if used
 state vector guess for stage p+1;
 slack variable vector guess for stage p+1; % if used
]
For more information, see nlmpcMultistage and nlmpcmove.

Dependencies

To enable this port, select the Initial guess parameter.

Output

expand all

Required Output

Optimal manipulated variable control action, output as a column vector signal of length Nmv, where Nmv is the number of manipulated variables.

If the solver converges to a local optimum solution (nlp.status is positive), then mv contains the optimal solution.

If the solver reaches the maximum number of iterations without finding an optimal solution (nlp.status is zero) and the Optimization.UseSuboptimalSolution property of the controller is true, then mv contains the suboptimal solution, otherwise, mv is the same as last_mv.

If the solver fails (nlp.status is negative), then mv is the same as last_mv.

Additional Outputs

Objective function cost, output as a nonnegative scalar signal. The cost quantifies the degree to which the controller has achieved its objectives.

The cost value is meaningful only when the nlp.status output is nonnegative.

Dependencies

To enable this port, select the Optimal cost parameter.

Stacked slack variables vector, used in constraint softening. If all elements are zero, then all soft constraints are satisfied over the entire prediction horizon. If any element is greater than zero, then at least one soft constraint is violated.

The slack variable vector for all stages are stacked as follows.

[slack variable vector for stage 1; % if used
 slack variable vector for stage 2; % if used
 ...
 slack variable vector for stage p+1; % if used
]

Optimization status, output as one of the following:

  • Positive Integer — Solver converged to an optimal solution

  • 0 — Maximum number of iterations reached without converging to an optimal solution

  • Negative integer — Solver failed

Dependencies

To enable this port, select the Optimization status parameter.

Optimal Sequences

Optimal manipulated variable sequence, returned as a matrix signal with p+1 rows and Nmv columns, where p is the prediction horizon and Nmv is the number of manipulated variables.

The first p rows of mv.seq contain the calculated optimal manipulated variable values from current time k to time k+p-1. The first row of mv.seq contains the current manipulated variable values (output mv). Since the controller does not calculate optimal control moves at time k+p, the final two rows of mv.seq are identical.

Dependencies

To enable this port, select the Optimal control sequence parameter.

Optimal prediction model state sequence, returned as a matrix signal with p+1 rows and Nx columns, where p is the prediction horizon and Nx is the number of states.

The first row of x.seq contains the current estimated state values, either from the built-in state estimator or from the custom state estimation block input x[k|k]. The next p rows of x.seq contain the calculated optimal state values from time k+1 to time k+p.

Dependencies

To enable this port, select the Optimal state sequence parameter.

Parameters

expand all

You must provide an nlmpcMultistage object that defines a nonlinear MPC controller. To do so, enter the name of an nlmpc object in the MATLAB workspace.

Programmatic Use

Block Parameter: nlmpcobj
Type: string, character vector
Default: ""

Select this parameter to run the controller using the same sample time as its prediction model. To use a different controller sample time, clear this parameter, and specify the sample time using the Make block run at a different sample time parameter.

To limit the number of decision variables and improve computational efficiency, you can run the controller with a sample time that is different from the prediction horizon. For example, consider the case of a nonlinear MPC controller running at 10 Hz. If the plant and controller sample times match, predicting plant behavior for ten seconds requires a prediction horizon of length 100, which produces a large number of decision variables. To reduce the number of decision variables, you can use a plant sample time of 1 second and a prediction horizon of length 10.

Programmatic Use

Block Parameter: UseObjectTs
Type: string, character vector
Values: "off", "on"
Default: "on"

Specify this parameter to run the controller using a different sample time from its prediction model. Setting this parameter to -1 allows the block to inherit the sample time from its parent subsystem.

Note

The first element of the MV rate vector (which is the difference between the current and the last value of the manipulated variable) is normally weighted and constrained assuming that the last value of the MV occurred in the past at the sample time specified in the MPC object. When the block is executed with a different sample rate, this assumption no longer holds, therefore, in this case, you must make sure that the weights and constraints defined in the controller handle the first element of the MV rate vector correctly.

Dependencies

To enable this parameter, clear the Use prediction model sample time parameter.

Programmatic Use

Block Parameter: TsControl
Type: string, character vector
Default: ""

Select this parameter to simulate the controller using a MEX function generated using buildMEX. Doing so reduces the simulation time of the controller. To specify the name of the MEX function, use the Specify MEX function name parameter.

Programmatic Use

Block Parameter: UseMEX
Type: string, character vector
Values: "off", "on"
Default: "off"

Use this parameter to specify the name of the MEX function to use during simulation. To create the MEX function, use the buildMEX function.

Dependencies

To enable this parameter, select the Use MEX to speed up simulation parameter.

Programmatic Use

Block Parameter: mexname
Type: string, character vector
Default: ""

General Tab

If your controller has measured disturbances, you must select this parameter to add the md output port to the block.

Programmatic Use

Block Parameter: md_enabled
Type: string, character vector
Values: "off", "on"
Default: "off"

If your prediction model uses optional parameters, you must select this parameter to add the state.param input port to the block.

Programmatic Use

Block Parameter: stateparam_enabled
Type: string, character vector
Values: "off", "on"
Default: "off"

If your cost or constraint functions use parameters at any stage, you must select this parameter to add the stage.param input port to the block.

Programmatic Use

Block Parameter: stageparam_enabled
Type: string, character vector
Values: "off", "on"
Default: "off"

Select this parameter to add the cost output port to the block.

Programmatic Use

Block Parameter: cost_enabled
Type: string, character vector
Values: "off", "on"
Default: "off"

Select this parameter to add the mv.seq output port to the block.

Programmatic Use

Block Parameter: mvseq_enabled
Type: string, character vector
Values: "off", "on"
Default: "off"

Select this parameter to add the x.seq output port to the block.

Programmatic Use

Block Parameter: stateseq_enabled
Type: string, character vector
Values: "off", "on"
Default: "off"

Select this parameter to add the slack output port to the block.

Programmatic Use

Block Parameter: slack_enabled
Type: string, character vector
Values: "off", "on"
Default: "off"

Select this parameter to add the nlp.status output port to the block.

Programmatic Use

Block Parameter: status_enabled
Type: string, character vector
Values: "off", "on"
Default: "off"

Online Features Tab

Select this parameter to add the mv.min input port to the block.

Programmatic Use

Block Parameter: mv_min
Type: string, character vector
Values: "off", "on"
Default: "off"

Select this parameter to add the mv.max input port to the block.

Programmatic Use

Block Parameter: mv_max
Type: string, character vector
Values: "off", "on"
Default: "off"

Select this parameter to add the dmv.min input port to the block.

Programmatic Use

Block Parameter: mvrate_min
Type: string, character vector
Values: "off", "on"
Default: "off"

Select this parameter to add the dmv.max input port to the block.

Programmatic Use

Block Parameter: mvrate_max
Type: string, character vector
Values: "off", "on"
Default: "off"

Select this parameter to add the x.min input port to the block.

Programmatic Use

Block Parameter: state_min
Type: string, character vector
Values: "off", "on"
Default: "off"

Select this parameter to add the x.max input port to the block.

Programmatic Use

Block Parameter: state_max
Type: string, character vector
Values: "off", "on"
Default: "off"

Select this parameter to add the x.terminal input port to the block.

Programmatic Use

Block Parameter: terminal_state
Type: string, character vector
Values: "off", "on"
Default: "off"

Select this parameter to add the z0 input port to the block.

Note

By default, the Nonlinar MPC Controller block uses the calculated optimal states, manipulated variables, and slack variables from one control interval as initial guesses for the next control interval.

Enable the initial guess port only if you need it for your application.

Programmatic Use

Block Parameter: nlp_initialize
Type: string, character vector
Values: "off", "on"
Default: "off"

Extended Capabilities

Version History

Introduced in R2021a

See Also

Blocks

Functions

Objects

Topics