Main Content

validateFcns

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

collapse all in page

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.

example

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.

example

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

example

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.

example

Examples

collapse all

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);
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.
Open Live Script

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.

This example uses:

Open Live Script

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

collapse all

Nonlinear MPC controller, specified as an nlmpc object.

Multistage nonlinear MPC controller, specified as an nlmpcMultistage object.

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

Manipulated variable values, specified as a vector of length Nmv, where Nmv 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.

Measured disturbance values, specified as a vector of length Nmd, where Nmd 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 [].

Parameter values used by the prediction model, custom cost function, and custom constraints, specified as a cell array of length Np, where Np 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 [].

Output reference values, specified as a vector of length Ny, 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.

Manipulated variable targets, specified as a vector of length Nmv, where Nmv 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.

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.

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, this field does not exist in the structure returned by getSimulationData.

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.

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

See Also

Functions

Objects

Blocks

Topics