validateFcns

Examine prediction model and custom functions of nlmpc object for potential problems

validateFunctions tests the prediction model, custom cost, custom constraint, and Jacobian functions of a nonlinear MPC controller for potential problems. 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.

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)

Description

example

validateFcns(nlmpcobj,x,mv) tests the functions of nonlinear MPC controller nlmpcobj for potential problems. The functions are tested using specified nominal state values, x, and manipulated variable values, mv. Use this syntax if your controller has no measured disturbances and no parameters.

example

validateFcns(nlmpcobj,x,mv,md) specifies nominal measured disturbance values. If your controller has measured disturbance channels, you must specify md.

example

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

validateFcns(nlmpcobj,x,mv,md,parameters,ref) specifies nominal output references.

validateFcns(nlmpcobj,x,mv,md,parameters,ref,mvtarget) specifies nominal manipulated variable targets.

Examples

collapse all

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,:)';

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 a nonlinear MPC controller with four states, two outputs, and one input.

nx = 4;
ny = 2;
nu = 1;
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 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 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.

Nominal state values, specified as a vector of length Nx, Nx is equal to nlmpcobj.Dimensions.NumberOfStates

Nominal manipulated variable values, specified as a vector of length Nmv, where Nmv is equal to the length of nlmpcobj.Dimensions.MVIndex.

Nominal measured disturbance values, specified as a vector of length Nmd, where Nmd is equal to the length of nlmpcobj.Dimensions.MDIndex. If your controller has measured disturbance channels, you must specify md. If your controller does not have measured disturbance channels, specify md as [].

Nominal 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. 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 [].

Nominal output reference values, specified as a vector of length Ny, where Ny is equal to nlmpcobj.Dimensions.NumberOfOutputs. ref is passed to the custom cost and constraint function. If you do not specify ref, the controller passes a vector of zeros to the custom functions.

Nominal manipulated variable targets, specified as a vector of length Nmv, where Nmv is equal to the length of nlmpcobj.Dimensions.MVIndex. 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.

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.

Introduced in R2018b