generateJacobianFcn

自動微分を使用して拡張カルマン フィルターの MATLAB ヤコビ関数を生成

R2023a 以降

構文

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

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

[___,constants] = generateJacobianFcn(___)

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

説明

fcnStateJac = generateJacobianFcn(obj,'state',Us1,...,Usn) は、自動微分手法を使用して拡張カルマン フィルター (EKF) の状態遷移ヤコビ関数を生成します。

この関数により、現在のフォルダーに 2 つの MATLAB^® 関数ファイルが生成されます。

• stateTransitionJacobianFcn.m — 生成された状態遷移ヤコビ関数

• stateTransitionJacobianFcnAD.m — 自動微分を使用して状態遷移ヤコビ関数を生成する補助関数

fcnStateJac は、入力 extendedKalmanFilter オブジェクト (obj)、obj の関数 predict に渡される追加の入力引数 (Us1,...,Usn)、および状態遷移のヤコビアンの計算に内部で使用される定数を使用して stateTransitionJacobianFcn.m を呼び出す無名関数のハンドルです。

このヤコビアンを EKF オブジェクトで使用するには、オブジェクトの StateTransitionJacobianFcn プロパティで fcnStateJac を指定します。以下に例を示します。

obj.StateTransitionJacobianFcn = fcnStateJac;

fcnMeasurementJac = generateJacobianFcn(obj,'measurement',Um1,...,Umn) は、自動微分手法を使用して拡張カルマン フィルター (EKF) の測定ヤコビ関数を生成します。

この関数により、現在のフォルダーに 2 つの MATLAB 関数ファイルが生成されます。

• measurementJacobianFcn.m — 生成された測定ヤコビ関数

• measurementJacobianFcnAD.m — 自動微分を使用して測定ヤコビ関数を生成する補助関数

fcnMeasurementJac は、入力 extendedKalmanFilter オブジェクト (obj)、obj の関数 correct に渡される追加の入力引数 (Um1,...,Umn)、および測定のヤコビアンの計算に内部で使用される定数を使用して measurementJacobianFcn.m を呼び出す無名関数のハンドルです。

このヤコビアンを EKF オブジェクトで使用するには、オブジェクトの MeasurementJacobianFcn プロパティで fcnMeasurementJac を指定します。以下に例を示します。

obj.MeasurementJacobianFcn = fcnMeasurementJac;

[___,constants] = generateJacobianFcn(___) は、ヤコビ関数の計算に使用される定数も返します。いずれのヤコビ関数の定数も返すことができます。

[___] = generateJacobianFcn(___,FileName=filename) は、生成されるヤコビ関数ファイルの名前とそれらを生成するフォルダーの場所を指定します。

例

状態関数と測定関数のヤコビアンの指定

2 つの状態と 1 つの出力を使用して、ファン デル ポール振動子の拡張カルマン フィルター (EKF) オブジェクトを作成します。前に記述して保存した状態遷移関数 vdpStateFcn.m と測定関数 vdpMeasurementFcn.m を使用します。2 つの状態の初期状態の値を [2;0] と指定します。

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

拡張カルマン フィルター アルゴリズムは状態推定に状態遷移関数と測定関数のヤコビアンを使用します。ヤコビ関数を記述して保存し、それらを関数ハンドルとして EKF オブジェクトに指定できます。このオブジェクトでは、前に記述して保存した関数 vdpStateJacobianFcn.m と vdpMeasurementJacobianFcn.m を使用します。

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

ヤコビ関数が使用できない場合は、自動微分を使用して生成できます。

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

関数のヤコビアンを指定しない場合、ソフトウェアで数値的に計算されます。この数値計算によって処理時間が増加し、状態推定の数値が不正確になる可能性があります。

特定のフォルダーへのヤコビ関数の生成

自動微分手法を使用して EKF オブジェクトの状態遷移と測定のヤコビ関数を生成します。ヤコビ関数ファイルを既定以外の場所に保存します。

2 つの状態と 1 つの出力を使用して、ファン デル ポール振動子の拡張カルマン フィルター (EKF) オブジェクトを作成します。前に記述して保存した状態遷移関数 vdpStateFcn.m と測定関数 vdpMeasurementFcn.m を使用します。2 つの状態の初期状態の値を [2;0] と指定します。

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

ヤコビ関数ファイルを生成するフォルダーを作成します。フォルダーをパスに追加します。

% 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)

ヤコビ関数ファイルを新しいフォルダーに生成します。生成されたファイルを表示します。

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

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

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

生成された関数ハンドルを EKF オブジェクトに追加します。

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

入力引数

obj — 拡張カルマン フィルター

extendedKalmanFilter オブジェクト

拡張カルマン フィルター。extendedKalmanFilter オブジェクトとして指定します。

Us1,...,Usn — 状態遷移関数への追加の入力引数

関数 predict で使用される追加の入力引数

状態遷移関数への追加の入力引数。状態遷移関数 f は obj の StateTransitionFcn プロパティで指定します。obj の関数 predict で使用される追加の入力引数と同じものを指定します。任意の型の入力引数を指定できます。

Um1,...,Umn — 測定関数への追加の入力引数

関数 correct で使用される追加の入力引数

測定関数への追加の入力引数。測定関数 h は obj の MeasurementFcn プロパティで指定します。obj の関数 correct で使用される追加の入力引数と同じものを指定します。任意の型の入力引数を指定できます。

filename — ヤコビ関数ファイルの名前

文字ベクトル

ヤコビ関数ファイルの名前。文字ベクトルとして指定します。関数で生成されるヤコビ関数ファイルに適用される命名規則は次のとおりです。

• filename.m

• filenameAD.m

filename にフォルダーの絶対パスまたは相対パスが含まれている場合、generateJacobianFcn はそのフォルダーにファイルを生成します。filename で指定されたパスが見つからないと、generateJacobianFcn はエラーを返します。

generateJacobianFcn でファイルを生成するフォルダーが MATLAB パス上にない場合、generateJacobianFcn はヤコビ関数ハンドルを [] として返します。この問題が発生する場合、関数ハンドルを生成するには次の手順に従います。

メモ

この手順を使用するには、generateJacobianFcn の呼び出しで constants 出力引数を返す必要があります。

1. フォルダーを MATLAB 検索パスに追加するか、生成された関数ファイルを MATLAB 検索パス上のフォルダーに移動します。

2. 関数ハンドル名 FcnName に使用する名前の部分を filename から取得します。

   [~,FcnName] = fileparts(filename);

3. この名前を使用して関数ハンドルを生成します。ここで、constants は前に呼び出した generateJacobianFcn の 2 番目の出力引数です。

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

これにより、この fcnJac ハンドルを obj の該当するヤコビ関数のプロパティで指定できます。

MATLAB 検索パスの操作の詳細については、MATLAB 検索パスとはを参照してください。

例: FileName='measjac' は、現在のフォルダーに measjac.m ファイルと measjacAD.m ファイルを生成します。

例: FileName='AD/measjac' は、現在のフォルダーの AD サブフォルダーに measjac.m ファイルと measjacAD.m ファイルを生成します。

例: FileName='C:/AD/measjac' は、C:/AD フォルダーに ekfjac.m ファイルと measjacAD.m ファイルを生成します。

データ型: char

出力引数

constants — ヤコビアンの計算に使用される追加の定数

長さ N の定数値の cell 配列

ヤコビアンの計算に使用される追加の定数。長さ N の定数値の cell 配列として返されます。ここで、N は定数の数です。ヤコビ関数に定数が必要ない場合、constants は空の cell 配列になります。

filename を指定する場合に filename で指定したフォルダーが MATLAB 検索パス上にないときは、これらの定数を使用して関数ハンドルを手動で作成できます。

fcnStateJac — 状態遷移関数のヤコビアン

関数ハンドル

状態遷移関数のヤコビアン。関数ハンドルとして返されます。

• obj.HasAdditiveMeasurementNoise = true の場合、fcnStateJac のシグネチャは次のとおりです。

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

• obj.HasAdditiveMeasurementNoise = false の場合、fcnStateJac のシグネチャは次のとおりです。

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

これらの関数シグネチャの内容は次のとおりです。

• dx は、前の状態から予測される状態のヤコビアンです。

• dw は、プロセス ノイズ要素から予測される状態のヤコビアンです。

• w は、プロセス ノイズ変数です。

• Us1,...,Usn は、obj の関数 predict で使用される追加の入力引数です。

• constants は、ヤコビアンの計算に使用される追加の定数です。

fcnMeasurementJac — 測定関数のヤコビアン

関数ハンドル

測定関数のヤコビアン。関数ハンドルとして返されます。

• obj.HasAdditiveMeasurementNoise = true の場合、fcnMeasurementJac のシグネチャは次のとおりです。

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

• obj.HasAdditiveMeasurementNoise = false の場合、fcnMeasurementJac のシグネチャは次のとおりです。

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

これらの関数シグネチャの内容は次のとおりです。

• dy は、状態に関する測定関数のヤコビアンです。

• dv は、測定ノイズに関する測定関数のヤコビアンです。

• v は、測定ノイズ変数です。

• Um1,...,Umn は、obj の関数 correct で使用される追加の入力引数です。

• constants は、ヤコビアンの計算に使用される追加の定数です。

制限

• 自動微分のサポートは、現在は最適化変数および式でサポートされる演算 (Optimization Toolbox)に記載されている一連の数学演算だけに制限されています。元の状態遷移関数または測定関数でリストにない演算や関数が使用されていたり、if-else ステートメントやループが含まれていると、generateJacobianFcn はエラーで終了します。

• ヤコビ関数を生成する場合、元の関数で最適化変数の事前割り当ては行わないでください。たとえば、次のコードを含む関数からヤコビアンを生成するとします。

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

  このコードでは次のエラーが発生します。

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

  代わりに次のコードを使用してください。

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

• 状態遷移関数および測定関数を obj で指定するときは、現在のフォルダーまたは MATLAB パス上のフォルダーのファイルとして指定することをお勧めします。ローカル関数のハンドルはヤコビ関数の生成ではサポートされますが、C/C++ 展開コードの生成ではサポートされていません。ローカル関数の詳細については、ローカル関数を参照してください。

バージョン履歴

R2023a で導入

参考

extendedKalmanFilter | predict | correct | clone | initialize | residual

トピック

• What Is Online Estimation?
• アンセンテッド カルマン フィルターおよび粒子フィルターを使用した非線形の状態推定
• オンライン状態推定のための拡張カルマン フィルター アルゴリズムおよびアンセンテッド カルマン フィルター アルゴリズム
• MATLAB でのオンライン状態推定のコードの生成

×

例を開く

この例の変更されたバージョンがあります。編集された方の例を開きますか?

いいえ、変更されたバージョンを上書きします。 はい