generateJacobianFcn

Generate MATLAB Jacobian functions for extended Kalman filter using automatic differentiation

Since R2023a

Syntax

fcnStateJac = generateJacobianFcn(obj,'state',Us1,...,Usn)

fcnMeasurementJac = generateJacobianFcn(obj,'measurement',Um1,...,Umn)

[___,constants] = generateJacobianFcn(___)

[___] = generateJacobianFcn(___,FileName=filename)

Description

fcnStateJac = generateJacobianFcn(obj,'state',Us1,...,Usn) generates the state transition Jacobian function for an extended Kalman filter (EKF) using the automatic differentiation technique.

This function generates two MATLAB^® function files in the current folder:

• stateTransitionJacobianFcn.m — The generated state transition Jacobian function

• stateTransitionJacobianFcnAD.m — A helper function that uses automatic differentiation to generate the state transition Jacobian function

fcnStateJac is a handle to an anonymous function that calls stateTransitionJacobianFcn.m using the input extendedKalmanFilter object (obj), the additional input arguments passed to the predict function of obj (Us1,...,Usn), and the constants used internally to compute the state transition Jacobian.

To use this Jacobian in the EKF object, specify fcnStateJac in the StateTransitionJacobianFcn property of the object. For example:

obj.StateTransitionJacobianFcn = fcnStateJac;

fcnMeasurementJac = generateJacobianFcn(obj,'measurement',Um1,...,Umn) generates the measurement Jacobian function for an extended Kalman filter (EKF) using the automatic differentiation technique.

This function generates two MATLAB function files in the current folder:

• measurementJacobianFcn.m — The generated measurement Jacobian function

• measurementJacobianFcnAD.m — A helper function that uses automatic differentiation to generate the measurement Jacobian function

fcnMeasurementJac is a handle to an anonymous function that calls measurementJacobianFcn.m using the input extendedKalmanFilter object (obj), the additional input arguments passed to the correct function of obj (Um1,...,Umn), and the constants used internally to compute the measurement Jacobian.

To use this Jacobian in the EKF object, specify fcnMeasurementJac in the MeasurementJacobianFcn property of the object. For example:

obj.MeasurementJacobianFcn = fcnMeasurementJac;

[___,constants] = generateJacobianFcn(___) also returns the constants used to compute the Jacobian function. You can return the constants for either Jacobian function.

[___] = generateJacobianFcn(___,FileName=filename) specifies the name of the generated Jacobian function files and the folder location in which to generate them.

Examples

Specify Jacobians for State and Measurement Functions

Create an extended Kalman filter (EKF) object for a van der Pol oscillator with two states and one output. Use the previously written and saved state transition and measurement functions, vdpStateFcn.m and vdpMeasurementFcn.m. Specify the initial state values for the two states as [2;0].

obj = extendedKalmanFilter(@vdpStateFcn,@vdpMeasurementFcn,[2;0]);

The extended Kalman filter algorithm uses Jacobians of the state transition and measurement functions for state estimation. You can write and save the Jacobian functions and provide them as function handles to the EKF object. For this object, use the previously written and saved functions vdpStateJacobianFcn.m and vdpMeasurementJacobianFcn.m.

obj.StateTransitionJacobianFcn = @vdpStateJacobianFcn;
obj.MeasurementJacobianFcn = @vdpMeasurementJacobianFcn;

If the Jacobian functions are not available, you can generate them using automatic differentiation.

obj.StateTransitionJacobianFcn = generateJacobianFcn(obj,'state');
obj.MeasurementJacobianFcn = generateJacobianFcn(obj,'measurement');

If you do not specify the Jacobians of the functions, the software numerically computes them. This numerical computation can result in increased processing time and numerical inaccuracy of the state estimation.

Generate Jacobians for State and Measurement Functions with Additional Input Arguments

Consider a nonlinear system with input u whose state x and measurement y evolve according to these state transition and measurement equations:

$x[k]=\sqrt{x[k-1]+u[k-1]}+w[k-1]$

$y[k]=x[k]+2*u[k]+v[k{]}^2$

The process noise w of the system is additive, while the measurement noise v is nonadditive.

Create the state transition function and measurement function for the system. Specify the functions with an additional input u.

f = @(x,u)(sqrt(x+u));
h = @(x,v,u)(x+2*u+v^2);

f and h are function handles to the anonymous functions that store the state transition and measurement functions, respectively. In the measurement function, because the measurement noise is nonadditive, v is also specified as an input. Note that v is specified as an input before the additional input u.

Create an extended Kalman filter (EKF) object for estimating the state of the nonlinear system using the state transition and measurement functions. Specify the initial value of the state as 1 and the measurement noise as nonadditive.

obj = extendedKalmanFilter(f,h,1,"HasAdditiveMeasurementNoise",false);

Generate the state transition and measurement Jacobian functions of obj using automatic differentiation. Because both the state transition and measurement functions have the additional input u, pass an arbitrary value of the same type and size as u to generateJacobianFcn.

obj.StateTransitionJacobianFcn = generateJacobianFcn(obj,"state",0.2);
obj.MeasurementJacobianFcn = generateJacobianFcn(obj,"measurement",0.2);

Generate Jacobian Functions to Specific Folder

Generate the state transition and measurement Jacobian functions of an EKF object using automatic differentiation techniques. Save the Jacobian function files to a nondefault location.

Create an extended Kalman filter (EKF) object for a van der Pol oscillator with two states and one output. Use the previously written and saved state transition and measurement functions, vdpStateFcn.m and vdpMeasurementFcn.m. Specify the initial state values for the two states as [2;0].

obj = extendedKalmanFilter(@vdpStateFcn,@vdpMeasurementFcn,[2;0]);

Create a folder in which to generate the Jacobian function files. Add the folder to the path.

% Change to a folder where you have write permission
CWD = pwd;
c = onCleanup(@()cd(CWD));
cd(tempdir)

% create a folder of the desired name
folder = 'jacobians';
[status,msg,msgID] = mkdir(folder);
% add the new folder to MATLAB path
addpath(folder)

Generate the Jacobian function files to the new folder. Display the generated files.

fcnStateJac = generateJacobianFcn(obj,"state",...
    FileName=fullfile(folder,'sJac'));
fcnMeasurementJac = generateJacobianFcn(obj,"measurement",...
    FileName=fullfile(folder,'mJac'));

{dir(fullfile(folder,"*.m")).name}'

ans = 4x1 cell
    {'mJac.m'  }
    {'mJacAD.m'}
    {'sJac.m'  }
    {'sJacAD.m'}

Add the generated function handles to the EKF object.

obj.StateTransitionJacobianFcn = @fcnStateJac;
obj.MeasurementJacobianFcn = @fcnMeasurementJac;
delete(c); % restore working folder

Input Arguments

obj — Extended Kalman filter

extendedKalmanFilter object

Extended Kalman filter, specified as an extendedKalmanFilter object.

Us1,...,Usn — Additional input arguments to state transition function

additional input arguments used by predict function

Additional input arguments to the state transition function. The state transition function f is specified in the StateTransitionFcn property of obj. Specify the same additional input arguments used by the predict function of obj. The input arguments can be of any type.

Um1,...,Umn — Additional input arguments to measurement function

additional input arguments used by correct function

Additional input arguments to the measurement function. The measurement function h is specified in the MeasurementFcn property of obj. Specify the same additional input arguments used by the correct function of obj. The input arguments can be of any type.

filename — Jacobian function file name

character vector

Jacobian function file name, specified as a character vector. The function applies this naming convention to the generated Jacobian function files:

• filename.m

• filenameAD.m

If filename contains an absolute or relative folder path, then generateJacobianFcn generates the files to that folder. If filename is unable to find the specified path, then generateJacobianFcn returns an error.

If the folder that generateJacobianFcn generates the files to is not on the MATLAB path, then generateJacobianFcn returns the Jacobian function handle as []. If this issue occurs, to generate the function handle, follow these steps:

Note

To use this procedure, you must return the constants output argument in your call to generateJacobianFcn.

1. Add the folder to the MATLAB search path, or move the generated function files to a folder on the MATLAB search path.

2. Obtain the name part of filename to use in the function handle name, FcnName.

   [~,FcnName] = fileparts(filename);

3. Generate the function handle using this name, where constants is the second output argument of your previous call to generateJacobianFcn.

   fcnJac = @(varargin)FcnName(varargin{:},constants);

You can then specify fcnJac handle in the appropriate Jacobian function property of obj.

For more details on working with the MATLAB search path, see What Is the MATLAB Search Path?

Example: FileName='measjac' generates measjac.m and measjacAD.m files in the current folder.

Example: FileName='AD/measjac' generates measjac.m and measjacAD.m files in the AD subfolder of the current folder.

Example: FileName='C:/AD/measjac' generates ekfjac.m and measjacAD.m files in the C:/AD folder.

Data Types: char

Output Arguments

constants — Additional constants used to compute Jacobian

length-N cell array of constant values

Additional constants used to compute the Jacobian, returned as a length-N cell array of constant values, where N is the number of constants. If the Jacobian function requires no constants, then constants is an empty cell array.

If you specify filename, and the folder specified in filename is not on the MATLAB search path, you can use these constants to manually construct the function handle.

fcnStateJac — Jacobian of state transition function

function handle

Jacobian of the state transition function, returned as a function handle.

• If obj.HasAdditiveMeasurementNoise = true, then fcnStateJac has this signature:

  dx = fcnStateJac(obj,Us1,...,Usn,constants)

• If obj.HasAdditiveMeasurementNoise = false, then fcnStateJac has this signature:

  [dx,dw] = fcnStateJac(obj,w,Us1,...,Usn,constants)

In these function signatures:

• dx is the Jacobian of the predicted state with respect to the previous state.

• dw is the Jacobian of the predicted state with respect to the process noise elements.

• w is the process noise variable.

• Us1,...,Usn are the additional input arguments used by the predict function of obj.

• constants are the additional constants used to compute the Jacobians.

fcnMeasurementJac — Jacobian of measurement function

function handle

Jacobian of the measurement function, returned as a function handle.

• If obj.HasAdditiveMeasurementNoise = true, then fcnMeasurementJac has this signature:

  dy = fcnMeasurementJac(obj,Um1,...,Umn,constants)

• If obj.HasAdditiveMeasurementNoise = false, then fcnMeasurementJac has this signature:

  [dy,dv] = fcnMeasurementJac(obj,v,Um1,...,Umn,constants)

In these function signatures:

• dy is the Jacobian of the measurement function with respect to the state.

• dv is the Jacobian of the measurement function with respect to the measurement noise.

• v is the measurement noise variable.

• Um1,...,Umn are the additional input arguments used by the correct function of obj.

• constants are the additional constants used to compute the Jacobians.

Limitations

• Automatic differentiation currently supports only a limited set of mathematical operations, which are described in Supported Operations for Optimization Variables and Expressions (Optimization Toolbox). If your original state transition or measurement function uses operations or functions that are not in the list, or has if-else statements or loops, generateJacobianFcn terminates with an error.

• To generate Jacobian functions, do not preallocate any optimization variable in the original function. For example, suppose you try to generate Jacobians from a function containing the following code.

  dxdt = zeros(2,1); 
  dxdt(1) = x(1)*x(2);
  dxdt(2) = x(1)/x(2); 

  This code results in the following error.

  Unable to perform assignment because value of type 
  'optim.problemdef.OptimizationExpression' 
  is not convertible to 'double'.

  Instead, use this code.

  dxdt = [x(1)*x(2); x(1)/x(2)];

• Specifying the state transition and measurement functions in obj as files in the current folder or in a folder on the MATLAB path is recommended. While handles to local functions are supported for Jacobian function generation, they are not supported for generation of C/C++ deployment code. For more information on local functions, see Local Functions.

Version History

Introduced in R2023a