Main Content

validateFcns

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

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

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.

Multistage Nonlinear MPC

validateFcns(nlmpcMSobj,x,mv) tests the functions of multistage nonlinear MPC controller nlmpcMSobj 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(nlmpcMSobj,x,mv,simdata) if parameters are needed for state and stage functions, you need to provide them in the simdata structure.

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.

Multistage nonlinear MPC controller, specified as an nlmpcMultistage object.

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.

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.

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.

The parameter vectors for all stages must be stacked in the column vector StateFcnParameters as:

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

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