validateFcns

Examine prediction model and custom functions of nlmpc or nlmpcMultistage objects for potential problems

Syntax

validateFcns(nlmpcobj,x,mv)

validateFcns(nlmpcobj,x,mv,md)

validateFcns(nlmpcobj,x,mv,md,parameters)

validateFcns(nlmpcobj,x,mv,md,parameters,ref)

validateFcns(nlmpcobj,x,mv,md,parameters,ref,mvtarget)

validateFcns(nlmpcMSobj,x,mv)

validateFcns(nlmpcMSobj,x,mv,simdata)

Description

validateFunctions tests the prediction model, custom cost, custom constraint, and Jacobian functions of a nonlinear MPC controller for potential problems such as whether information is missing, whether input and output arguments of any user supplied functions are incompatible with object settings or whether user supplied analytical gradient/Jacobian functions are numerically accurate. When you first design your nonlinear MPC controller, or when you make significant changes to an existing controller, it is best practice to validate your controller functions.

Nonlinear MPC

validateFcns(nlmpcobj,x,mv) tests the functions of nonlinear MPC controller nlmpcobj for potential problems. The functions are tested using specified state and manipulated variable values, x and mv, respectively. These values can represent nominal conditions or an arbitrary operating point. Use this syntax if your controller has no measured disturbances and no parameters.

validateFcns(nlmpcobj,x,mv,md) specifies measured disturbance values. If your controller has measured disturbance channels, you must specify md. These values can represent nominal conditions or an arbitrary operating point.

validateFcns(nlmpcobj,x,mv,md,parameters) specifies parameter values. If your controller has parameters, you must specify parameters.

validateFcns(nlmpcobj,x,mv,md,parameters,ref) specifies output references at nominal conditions or for an arbitrary operating point.

validateFcns(nlmpcobj,x,mv,md,parameters,ref,mvtarget) specifies manipulated variable targets at nominal conditions or for an arbitrary operating point.

Multistage Nonlinear MPC

validateFcns(nlmpcMSobj,x,mv) tests the functions of multistage nonlinear MPC controller nlmpcMSobj for potential problems. The functions are tested using the specified state and manipulated variable values, x and mv, respectively. These values can represent nominal conditions or an arbitrary operating point. Use this syntax if your controller has no measured disturbances and no parameters.

validateFcns(nlmpcMSobj,x,mv,simdata) specifies the additional simdata structure. If parameters are needed for the state and stage functions, you need to provide them in simdata.

Examples

Validate Nonlinear MPC Prediction Model and Custom Functions

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

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

Zero weights are applied 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,:)';

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.

Create Nonlinear MPC Controller with Discrete-Time Prediction Model

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

nx = 4;
ny = 2;
nu = 1;
nlobj = nlmpc(nx,ny,nu);

Zero weights are applied 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 discrete-time state function uses an optional parameter, the sample time Ts, to integrate the continuous-time model. Therefore, you must specify the number of optional parameters as 1.

nlobj.Model.NumberOfParameters = 1;

Specify the output function for the controller. In this case, define the first and third states as outputs. Even though this output function does not use the optional sample time parameter, you must specify the parameter as an input argument (Ts).

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

Validate the prediction model functions for nominal states x0 and nominal inputs u0. Since the prediction model uses a custom parameter, you must pass this parameter to validateFcns.

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.

Create Nonlinear MPC Controller with Measured and Unmeasured Disturbances

Create a nonlinear MPC controller with three states, one output, and four inputs. The first two inputs are measured disturbances, the third input is the manipulated variable, and the fourth input is an unmeasured disturbance.

nlobj = nlmpc(3,1,'MV',3,'MD',[1 2],'UD',4);

To view the controller state, output, and input dimensions and indices, use the Dimensions property of the controller.

nlobj.Dimensions

ans = struct with fields:
     NumberOfStates: 3
    NumberOfOutputs: 1
     NumberOfInputs: 4
            MVIndex: 3
            MDIndex: [1 2]
            UDIndex: 4

Specify the controller sample time and horizons.

nlobj.Ts = 0.5;
nlobj.PredictionHorizon = 6;
nlobj.ControlHorizon = 3;

Specify the prediction model state function, which is in the file exocstrStateFcnCT.m.

nlobj.Model.StateFcn = 'exocstrStateFcnCT';

Specify the prediction model output function, which is in the file exocstrOutputFcn.m.

nlobj.Model.OutputFcn = 'exocstrOutputFcn';

Validate the prediction model functions using the initial operating point as the nominal condition for testing and setting the unmeasured disturbance state, x0(3), to 0. Since the model has measured disturbances, you must pass them to validateFcns.

x0 = [311.2639; 8.5698; 0];
u0 = [10; 298.15; 298.15];
validateFcns(nlobj,x0,u0(3),u0(1:2)');

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

Input Arguments

nlmpcobj — Nonlinear MPC controller

nlmpc object

Nonlinear MPC controller, specified as an nlmpc object.

nlmpcMSobj — Nonlinear Multistage MPC controller

nlmpcMultistage object

Multistage nonlinear MPC controller, specified as an nlmpcMultistage object.

x — State values

vector

State values, specified as a vector of length N_x, where N_x is equal to nlmpcobj.Dimensions.NumberOfStates, or nlmpcMSobj.Dimensions.NumberOfStates. The state values can represent nominal conditions or an arbitrary operating point.

mv — Manipulated variable values

vector

Manipulated variable values, specified as a vector of length N_mv, where N_mv is equal to the length of nlmpcobj.Dimensions.MVIndex or nlmpcMSobj.Dimensions.MVIndex. The manipulated variable values can represent nominal conditions or an arbitrary operating point.

md — Measured disturbance values

[] (default) | vector

Measured disturbance values, specified as a vector of length N_md, where N_md is equal to the length of nlmpcobj.Dimensions.MDIndex. The measured disturbance values can represent nominal conditions or an arbitrary operating point.

If your controller has measured disturbance channels, you must specify md. If your controller does not have measured disturbance channels, specify md as [].

parameters — Parameter values

[] (default) | cell array

Parameter values used by the prediction model, custom cost function, and custom constraints, specified as a cell array of length N_p, where N_p is equal to nlmpcobj.Model.NumberOfParameters or nlmpcMSobj.Model.NumberOfParameters. The order of the parameters must match the order specified in the model functions, and each parameter must be a numeric parameter with the correct dimensions.

If your controller has parameters, you must specify parameters. If your controller does not have parameters, specify parameters as [].

ref — Output reference values

[] (default) | vector

Output reference values, specified as a vector of length N_y, where Ny is equal to nlmpcobj.Dimensions.NumberOfOutputs or nlmpcMSobj.Model.NumberOfOutputs. ref is passed to the custom cost and constraint function. The output reference values can represent nominal conditions or an arbitrary operating point.

If you do not specify ref, the controller passes a vector of zeros to the custom functions.

mvtarget — Manipulated variable targets

[] (default) | vector

Manipulated variable targets, specified as a vector of length N_mv, where N_mv is equal to the length of nlmpcobj.Dimensions.MVIndex or nlmpcMSobj.Dimensions.MVIndex. The manipulated variable target values can represent nominal conditions or an arbitrary operating point.

mvtarget is passed to the custom cost and constraint function. If you do not specify mvtarget, the controller passes a vector of zeros to the custom functions.

simdata — Run-time simulation data structure

structure

Run-time simulation data, initially created by getSimulationData, and specified as structure with fields described in detail in nlmpcmove. For validateFcns, only the following fields are relevant.

MeasuredDisturbance — 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 multistage MPC object has any measured disturbance channel defined, you must specify MeasuredDisturbance. If your controller has no measured disturbances, this field does not exist in the structure returned by getSimulationData.

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. If your state function has no parameter, this field does not exist in the structure returned by getSimulationData.

StageFcnParameters — 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. If none of your stage functions needs any parameter, this field does not exist in the structure returned by getSimulationData.

Tips

• When you provide your own analytical Jacobian functions, it is especially important that these functions return valid Jacobian values. If validateFunctions detects large differences between the values returned by your user-defined Jacobian functions and the finite-difference approximation, verify the code in your Jacobian implementations.

Algorithms

For each controller function, validateFunctions checks whether the function:

• Exists on the MATLAB^® path

• Has the required number of input arguments

• Can be executed successfully without errors

• Returns the output arguments with the correct size and dimensions

• Returns valid numerical data; that is, it does not return Inf or NaN values

For Jacobian functions, validateFunctions checks whether the returned values are comparable to a finite-difference approximation of the Jacobian values. These finite-difference values are computed using numerical perturbation.

Version History

Introduced in R2018b