nlmpcmove

Compute optimal control action for nonlinear MPC controller

collapse all in page

Syntax

mv = nlmpcmove(nlmpcobj,x,lastmv)

mv = nlmpcmove(nlmpcobj,x,lastmv,ref)

mv = nlmpcmove(nlmpcobj,x,lastmv,ref,md)

mv = nlmpcmove(nlmpcobj,x,lastmv,ref,md,options)

[mv,opt] = nlmpcmove(___)

[mv,opt,info] = nlmpcmove(___)

Description

mv = nlmpcmove(nlmpcobj,x,lastmv) computes the optimal manipulated variable control action for the current time. To simulate closed-loop nonlinear MPC control, call nlmpcmove repeatedly.

example

mv = nlmpcmove(nlmpcobj,x,lastmv,ref) specifies reference values for the plant outputs. If you do not specify reference values, nlmpcmove uses zeros by default.

mv = nlmpcmove(nlmpcobj,x,lastmv,ref,md) specifies run-time measured disturbance values. If your controller has measured disturbances, you must specify md.

example

mv = nlmpcmove(nlmpcobj,x,lastmv,ref,md,options) specifies additional run-time options for computing optimal control moves. Using options, you can specify initial guesses for state and manipulated variable trajectories, update tuning weights at constraints, or modify prediction model parameters.

example

[mv,opt] = nlmpcmove(___) returns an nlmpcmoveopt object that contains initial guesses for the state and manipulated trajectories to be used in the next control interval.

example

[mv,opt,info] = nlmpcmove(___) returns additional solution details, including the final optimization cost function value and the optimal manipulated variable, state, and output trajectories.

Examples

collapse all

Plan Optimal Trajectory Using Nonlinear MPC

This example uses:

Open Live Script

Create nonlinear MPC controller with six states, six outputs, and four inputs.

nx = 6;
ny = 6;
nu = 4;
nlobj = nlmpc(nx,ny,nu);

In standard cost function, zero weights are applied by default to one or more OVs because there are fewer MVs than OVs.

Specify the controller sample time and horizons.

Ts = 0.4;
p = 30;
c = 4;
nlobj.Ts = Ts;
nlobj.PredictionHorizon = p;
nlobj.ControlHorizon = c;

Specify the prediction model state function and the Jacobian of the state function. For this example, use a model of a flying robot.

nlobj.Model.StateFcn = "FlyingRobotStateFcn";
nlobj.Jacobian.StateFcn = "FlyingRobotStateJacobianFcn";

Specify a custom cost function for the controller that replaces the standard cost function.

nlobj.Optimization.CustomCostFcn = @(X,U,e,data) Ts*sum(sum(U(1:p,:)));
nlobj.Optimization.ReplaceStandardCost = true;

Specify a custom constraint function for the controller.

nlobj.Optimization.CustomEqConFcn = @(X,U,data) X(end,:)';

Specify linear constraints on the manipulated variables.

for ct = 1:nu
    nlobj.MV(ct).Min = 0;
    nlobj.MV(ct).Max = 1;
end

Validate the prediction model and custom functions at the initial states (x0) and initial inputs (u0) of the robot.

x0 = [-10;-10;pi/2;0;0;0];
u0 = zeros(nu,1); 
validateFcns(nlobj,x0,u0);

Model.StateFcn is OK.
Jacobian.StateFcn is OK.
No output function specified. Assuming "y = x" in the prediction model.
Optimization.CustomCostFcn is OK.
Optimization.CustomEqConFcn is OK.
Analysis of user-provided model, cost, and constraint functions complete.

Compute the optimal state and manipulated variable trajectories, which are returned in the info.

[~,~,info] = nlmpcmove(nlobj,x0,u0);

Slack variable unused or zero-weighted in your custom cost function. All constraints will be hard.

Plot the optimal trajectories.

FlyingRobotPlotPlanning(info)

Optimal fuel consumption =   4.712383

Simulate Closed-Loop Control using Nonlinear MPC Controller

This example uses:

Open Live Script

Create a nonlinear MPC controller with four states, two outputs, and one input.

nlobj = nlmpc(4,2,1);

In standard cost function, zero weights are applied by default to one or more OVs because there are fewer MVs than OVs.

Specify the sample time and horizons of the controller.

Ts = 0.1;
nlobj.Ts = Ts;
nlobj.PredictionHorizon = 10;
nlobj.ControlHorizon = 5;

Specify the state function for the controller, which is in the file pendulumDT0.m. This discrete-time model integrates the continuous time model defined in pendulumCT0.m using a multistep forward Euler method.

nlobj.Model.StateFcn = "pendulumDT0";
nlobj.Model.IsContinuousTime = false;

The prediction model uses an optional parameter, Ts, to represent the sample time. Specify the number of parameters.

nlobj.Model.NumberOfParameters = 1;

Specify the output function of the model, passing the sample time parameter as an input argument.

nlobj.Model.OutputFcn = @(x,u,Ts) [x(1); x(3)];

Define standard constraints for the controller.

nlobj.Weights.OutputVariables = [3 3];
nlobj.Weights.ManipulatedVariablesRate = 0.1;
nlobj.OV(1).Min = -10;
nlobj.OV(1).Max = 10;
nlobj.MV.Min = -100;
nlobj.MV.Max = 100;

Validate the prediction model functions.

x0 = [0.1;0.2;-pi/2;0.3];
u0 = 0.4;
validateFcns(nlobj, x0, u0, [], {Ts});

Model.StateFcn is OK.
Model.OutputFcn is OK.
Analysis of user-provided model, cost, and constraint functions complete.

Only two of the plant states are measurable. Therefore, create an extended Kalman filter for estimating the four plant states. Its state transition function is defined in pendulumStateFcn.m and its measurement function is defined in pendulumMeasurementFcn.m.

EKF = extendedKalmanFilter(@pendulumStateFcn,@pendulumMeasurementFcn);

Define initial conditions for the simulation, initialize the extended Kalman filter state, and specify a zero initial manipulated variable value.

x = [0;0;-pi;0];
y = [x(1);x(3)];
EKF.State = x;
mv = 0;

Specify the output reference value.

yref = [0 0];

Create an nlmpcmoveopt object, and specify the sample time parameter.

nloptions = nlmpcmoveopt;
nloptions.Parameters = {Ts};

Run the simulation for 10 seconds. During each control interval:

Correct the previous prediction using the current measurement.
Compute optimal control moves using nlmpcmove. This function returns the computed optimal sequences in nloptions. Passing the updated options object to nlmpcmove in the next control interval provides initial guesses for the optimal sequences.
Predict the model states.
Apply the first computed optimal control move to the plant, updating the plant states.
Generate sensor data with white noise.
Save the plant states.

Duration = 10;
xHistory = x;
for ct = 1:(Duration/Ts)
    % Correct previous prediction
    xk = correct(EKF,y);
    % Compute optimal control moves
    [mv,nloptions] = nlmpcmove(nlobj,xk,mv,yref,[],nloptions);
    % Predict prediction model states for the next iteration
    predict(EKF,[mv; Ts]);
    % Implement first optimal control move
    x = pendulumDT0(x,mv,Ts);
    % Generate sensor data
    y = x([1 3]) + randn(2,1)*0.01;
    % Save plant states
    xHistory = [xHistory x];
end

Plot the resulting state trajectories.

figure
subplot(2,2,1)
plot(0:Ts:Duration,xHistory(1,:))
xlabel('time')
ylabel('z')
title('cart position')
subplot(2,2,2)
plot(0:Ts:Duration,xHistory(2,:))
xlabel('time')
ylabel('zdot')
title('cart velocity')
subplot(2,2,3)
plot(0:Ts:Duration,xHistory(3,:))
xlabel('time')
ylabel('theta')
title('pendulum angle')
subplot(2,2,4)
plot(0:Ts:Duration,xHistory(4,:))
xlabel('time')
ylabel('thetadot')
title('pendulum velocity')

Input Arguments

collapse all

`nlmpcobj` — Nonlinear MPC controller
`nlmpc` object

Nonlinear MPC controller, specified as an nlmpc object.

`x` — Current prediction model states
vector

Current prediction model states, specified as a vector of lengthN_x, where N_x 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. For more information on nonlinear MPC prediction models, see Specify Prediction Model for Nonlinear MPC.

`lastmv` — Control signals used in plant at previous control interval
vector

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

Note

Specify lastmv as the manipulated variable signals applied to the plant in the previous control interval. Typically, these signals are the values generated by the controller, though this is not always the case. 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 control signal to last_mv can help achieve bumpless transfer when the controller is switched back online.

`ref` — Plant output reference values
`[]` (default) | row vector | array

Plant output reference values, specified as a row vector of length N_y or an array with N_y columns, where N_y is the number of output variables. If you do not specify ref, the default reference values are zero.

To use the same reference values across the prediction horizon, specify a row vector.

To vary the reference values over the prediction horizon from time k+1 to time k+p, specify an array with up to p rows. Here, k is the current time and p is the prediction horizon. Each row contains the reference 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.

`md` — 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 controller has measured disturbances, you must specify md. If your controller has no measured disturbances, specify md 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.

`options` — Run-time options
`nlmpcmoveopt` object

Run-time options, specified as an nlmpcmoveopt object. Using these options, you can:

Tune controller weights
Update linear constraints
Set manipulated variable targets
Specify prediction model parameters
Provide initial guesses for state and manipulated variable trajectories

These options apply to only the current nlmpcmove time instant.

To improve solver efficiency, it is best practice to specify initial guesses for the state and manipulated variable trajectories.

Output Arguments

collapse all

`mv` — Optimal manipulated variable control action
column vector

Optimal manipulated variable control action, returned as a column vector of length N_mv, where N_mv is the number of manipulated variables.

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

If the solver reaches the maximum number of iterations without finding an optimal solution (info.ExitFlag = 0) and:

nlmpcobj.Optimization.UseSuboptimalSolution is true, then mv contains the suboptimal solution
nlmpcobj.Optimization.UseSuboptimalSolution is false, then mv contains lastmv

If the solver fails (info.ExitFlag is negative), then mv contains lastmv.

`opt` — Run-time options with initial guesses
`nlmpcmoveopt` object

Run-time options with initial guesses for the state and manipulated variable trajectories to be used in the next control interval, returned as an nlmpcmoveopt object. Any run-time options that you specified using options, such as weights, constraints, or parameters, are copied to opt.

The initial guesses for the states (opt.X0) and manipulated variables (opt.MV0) are the optimal trajectories computed by nlmpcmove and correspond to the last p-1 rows of info.Xopt and info.MVopt, respectively.

To use these initial guesses in the next control interval, specify opt as the options input argument to nlmpcmove.

`info` — Solution details
structure

Solution details, returned as a structure with the following fields.

`MVopt` — Optimal manipulated variable sequence
array

Optimal manipulated variable sequence, returned as a (p+1)-by-N_mv array, where p is the prediction horizon and N_mv is the number of manipulated variables.

MVopt(i,:) contains the calculated optimal manipulated variable values at time k+i-1, for i = 1,...,p, where k is the current time. MVopt(1,:) contains the same manipulated variable values as output argument mv. Since the controller does not calculate optimal control moves at time k+p, MVopt(p+1,:) is equal to MVopt(p,:).

`Xopt` — Optimal prediction model state sequence
array

Optimal prediction model state sequence, returned as a (p+1)-by-N_x array, where p is the prediction horizon and N_x is the number of states in the prediction model.

Xopt(i,:) contains the calculated state values at time k+i-1, for i = 2,...,p+1, where k is the current time. Xopt(1,:) is the same as the current states in x.

`Yopt` — Optimal output variable sequence
array

Optimal output variable sequence, returned as a (p+1)-by-N_y array, where p is the prediction horizon and N_y is the number of outputs.

Yopt(i,:) contains the calculated output values at time k+i-1, for i = 2,...,p+1, where k is the current time. Yopt(1,:) is computed based on the current states in x and the current measured disturbances in md, if any.

`Topt` — Prediction horizon time sequence
column vector

Prediction horizon time sequence, returned as a column vector of length p+1, where p is the prediction horizon. Topt contains the time sequence from time k to time k+p, where k is the current time.

Topt(1) = 0 represents the current time. Subsequent time steps Topt(i) are Ts*(i-1), where Ts is the controller sample time.

Use Topt when plotting the MVopt, Xopt, or Yopt sequences.

`Slack` — Slack variable
nonnegative scalar

Slack variable, ε, used in constraint softening, returned as a nonnegative scalar value.

ε = 0 — All soft constraints are satisfied over the entire prediction horizon.
ε > 0 — At least one soft constraint is violated. When more than one constraint is violated, ε represents the worst-case soft constraint violation (scaled by your ECR values for each constraint).

`ExitFlag` — Optimization exit code
integer

Optimization exit code, returned as one of the following:

Positive Integer — Optimal solution found
0 — Feasible suboptimal solution found after the maximum number of iterations
Negative integer — No feasible solution found

`Cost` — Objective function cost
nonnegative scalar

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

The cost value is only meaningful when ExitFlag is nonnegative.

Tips

During closed-loop simulations, it is best practice to warm start the nonlinear solver by using the predicted state and manipulated variable trajectories from the previous control interval as the initial guesses for the current control interval. To use these trajectories as initial guesses:

Return the opt output argument when calling nlmpcmove. This nlmpcmoveopt object contains any run-time options you specified in the previous call to nlmpcmove, along with the initial guesses for the state (opt.X0) and manipulated variable (opt.MV0) trajectories.
Pass this object 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.

Documentation

nlmpcmove

Syntax

Description

Examples

Plan Optimal Trajectory Using Nonlinear MPC

Simulate Closed-Loop Control using Nonlinear MPC Controller

Input Arguments

`nlmpcobj` — Nonlinear MPC controller
`nlmpc` object

`x` — Current prediction model states
vector

`lastmv` — Control signals used in plant at previous control interval
vector

`ref` — Plant output reference values
`[]` (default) | row vector | array

`md` — Measured disturbance values
`[]` (default) | row vector | array

`options` — Run-time options
`nlmpcmoveopt` object

Output Arguments

`mv` — Optimal manipulated variable control action
column vector

`opt` — Run-time options with initial guesses
`nlmpcmoveopt` object

`info` — Solution details
structure

`MVopt` — Optimal manipulated variable sequence
array

`Xopt` — Optimal prediction model state sequence
array

`Yopt` — Optimal output variable sequence
array

`Topt` — Prediction horizon time sequence
column vector

`Slack` — Slack variable
nonnegative scalar

`ExitFlag` — Optimization exit code
integer

`Cost` — Objective function cost
nonnegative scalar

Tips

See Also

Topics

Model Predictive Control Toolbox Documentation

Support

Documentation

nlmpcmove

Syntax

Description

Examples

Plan Optimal Trajectory Using Nonlinear MPC

Simulate Closed-Loop Control using Nonlinear MPC Controller

Input Arguments

nlmpcobj — Nonlinear MPC controller nlmpc object

x — Current prediction model states vector

lastmv — Control signals used in plant at previous control interval vector

ref — Plant output reference values [] (default) | row vector | array

md — Measured disturbance values [] (default) | row vector | array

options — Run-time options nlmpcmoveopt object

Output Arguments

mv — Optimal manipulated variable control action column vector

opt — Run-time options with initial guesses nlmpcmoveopt object

info — Solution details structure

MVopt — Optimal manipulated variable sequence array

Xopt — Optimal prediction model state sequence array

Yopt — Optimal output variable sequence array

Topt — Prediction horizon time sequence column vector

Slack — Slack variable nonnegative scalar

ExitFlag — Optimization exit code integer

Cost — Objective function cost nonnegative scalar

Tips

See Also

Topics

Model Predictive Control Toolbox Documentation

Support

`nlmpcobj` — Nonlinear MPC controller
`nlmpc` object

`x` — Current prediction model states
vector

`lastmv` — Control signals used in plant at previous control interval
vector

`ref` — Plant output reference values
`[]` (default) | row vector | array

`md` — Measured disturbance values
`[]` (default) | row vector | array

`options` — Run-time options
`nlmpcmoveopt` object

`mv` — Optimal manipulated variable control action
column vector

`opt` — Run-time options with initial guesses
`nlmpcmoveopt` object

`info` — Solution details
structure

`MVopt` — Optimal manipulated variable sequence
array

`Xopt` — Optimal prediction model state sequence
array

`Yopt` — Optimal output variable sequence
array

`Topt` — Prediction horizon time sequence
column vector

`Slack` — Slack variable
nonnegative scalar

`ExitFlag` — Optimization exit code
integer

`Cost` — Objective function cost
nonnegative scalar