Main Content

Simulink.sdi.constraints.MatchesSignal クラス

パッケージ: Simulink.sdi.constraints
スーパークラス: matlab.unittest.constraints.Constraint

シミュレーション データ インスペクターを使用した時系列データと許容誤差との比較を行う制約

R2019a 以降

このページをすべて展開する

説明

Simulink.sdi.constraints.MatchesSignal の制約を使用して、テストの一部として時系列データを想定される値と比較します。この制約を、比較のため、絶対許容誤差、相対許容誤差、時間の許容誤差の値の組わせを使用するよう構成できます。Simulink.sdi.constraints.MatchesSignalOptions オブジェクトを使用して、または 1 つ以上の名前と値のペアの引数を使用して、比較の動作を構成する追加のオプションを指定することもできます。許容誤差とアライメント オプションが比較にどのように影響するかの詳細については、シミュレーション データ インスペクターでデータを比較する方法を参照してください。

メモ

MatchesSignal 制約は、シミュレーション データ インスペクターを使用して比較を実行します。以下のいずれかの製品ライセンスが必要です。

  • Simulink®

  • Signal Processing Toolbox™

  • MATLAB® Coder™

  • Fixed-Point Designer™

作成

説明

例

MatchesSignal(expVal) は、実際の値を表す時系列データが想定される値で指定されるデータ expVal に一致するかどうかを判別する制約を作成します。

例

MatchesSignal(expVal,Name,Value) は、1 つ以上の Name,Value ペア引数で指定される追加のプロパティを使用して制約を作成します。

入力引数

すべて展開する

名前と値の引数

引数のオプションのペアを Name1=Value1,...,NameN=ValueN として指定します。Name は引数名、Value は対応する値です。名前と値の引数は他の引数の後に表示されなければなりませんが、ペアの順序は重要ではありません。

R2021a より前は、名前と値をそれぞれコンマを使って区切り、Name を引用符で囲みます。

例: 'IgnoringDataTypes',true

想定される値と異なるデータ型をもつ実際の値への制約の感度の設定

  • false — 制約は、想定される値と実際の値とのデータ型が一致することをチェックします。

  • true — 制約は、想定される値と実際の値とのデータ型の不一致に影響されません。

例: 'IgnoringDataTypes',true

想定される値と実際の値との間で整列しない 1 つ以上の信号への制約の感度を構成します。

  • false — 制約は、想定される値と実際の値との間で整列しない信号をチェックします。

  • true — 制約は、想定される値と実際の値との間で整列しない 1 つ以上の信号に影響されません。

例: 'IgnoringSignalsNotAligned',true

想定される値によって定義される時間間隔の外側のデータを含む実際の値への制約の感度を構成します。

  • false — 制約は、想定される値によって定義される時間間隔の外側のデータが実際の値に含まれているかどうかをチェックします。

  • true — 制約は、想定される値によって定義される時間間隔の外側のデータが実際の値に含まれていても影響されません。

例: 'IgnoringExtraData',true

比較のための整列基準。想定される値に 1 つ以上の信号が含まれている場合、シミュレーション データ インスペクターの比較アルゴリズムは、想定される値と実際の値との間の比較のため、信号を整列します。既定では、シミュレーション データ インスペクターは、データ ソース、次にブロック パス、次に SID、次に信号名によって整列します。シミュレーション データ インスペクターの整列アルゴリズムの詳細については、シミュレーション データ インスペクターでデータを比較する方法を参照してください。

1 つ以上の以下のオプションを、考慮する順番に string 配列として指定して、整列基準を指定します。

  • BlockPath — 信号のソース ブロックのパス。

  • SID — 自動的に割り当てられる Simulink 識別子。

  • SignalName — 信号の名前。

  • DataSource — 変数のパス。

例: 'AligningBy',["SignalName","BlockPath"] は、信号の名前、次にブロック パスによって信号の整列を指定します。

プロパティ

すべて展開する

比較のベースラインとしての使用が想定される値想定される値のデータは時間をもつデータの値とペアになっていなければなりません。データはシミュレーション データ インスペクターがサポートする任意の形式にすることができます。シミュレーション データ インスペクターは、サンプル値を時間と関連付ける形式のデータを要求します。サポートされる形式には timeseries、Structure with time、および Dataset などがあります。

データが含まれるワークスペースの変数を使用するか、あるいはデータが含まれるファイルの絶対パスまたはファイル名を指定することで、制約の期待値を string スカラーまたは文字配列として指定することができます。

属性:

GetAccess
public
SetAccess
immutable

制約の比較を構成するオプションを指定する Simulink.sdi.constraints.MatchesSignalOptions オブジェクト。既定では、比較ではシミュレーション データ インスペクターの既定の整列が使用され、厳密な受け入れ基準があります。これは、比較ではあらゆるチェックが無視されないということです。MatchesSignalOptions プロパティを使用して、制約が、想定される実行と実際の実行との信号を整列する方法、および、制約が以下のものに影響を受けるかどうかを構成できます。

  • 実際の値が想定される値と異なるデータ型をもつかどうか。

  • 1 つ以上の信号が想定される実行と実際の実行との間で整列していないか。

  • 実際の値が、想定される値で定義される時間間隔の外側のデータを含んでいるか。

個別の名前と値のペアの引数を使用して、または Simulink.sdi.constraints.MatchesSignalOptions オブジェクトを値としてもつ名前と値のペア 'WithOptions' を使用して、制約の MatchesSignalOptions プロパティを指定できます。MatchesSignalOptions オブジェクトを使用して MatchesSignalOptions プロパティを指定する場合、制約を使用する比較のすべてのオプションを、単一の名前と値のペアを使用して構成できます。

属性:

GetAccess
public
SetAccess
immutable

データ型: Simulink.sdi.constraints.MatchesSignalOptions

制約を使用した比較の絶対許容誤差。シミュレーション データ インスペクターが比較において許容誤差の値を使用する方法の詳細については、シミュレーション データ インスペクターでデータを比較する方法を参照してください。

例: 0.1

例: 2

属性:

GetAccess
public
SetAccess
immutable

データ型: double

制約を使用した比較の相対許容誤差。たとえば、0.1 を指定して、比較において 10% の許容誤差を使用します。シミュレーション データ インスペクターが比較において許容誤差の値を使用する方法の詳細については、シミュレーション データ インスペクターでデータを比較する方法を参照してください。

例: 0.05

属性:

GetAccess
public
SetAccess
immutable

データ型: double

制約を使用した比較の時間許容誤差 (秒単位)。シミュレーション データ インスペクターが比較において許容誤差の値を使用する方法の詳細については、シミュレーション データ インスペクターでデータを比較する方法を参照してください。

例: 0.001

属性:

GetAccess
public
SetAccess
immutable

データ型: double

例

すべて折りたたむ

ライブ スクリプトを開く

この例では、Simulink.sdi.constraints.MatchesSignal 制約を使用して、ワークスペースで生成されたデータを使用した時系列データを比較する方法を示します。MatchesSignal 制約を使用して、ファイル内の測定されたテスト データやログに記録されているシミュレーション出力など、多数のソースからデータを比較します。

MatchesSignal 制約を使用する場合、絶対許容誤差、相対許容誤差、および時間許容誤差を比較で使用するよう指定できます。MatchesSignal 制約は、整列および同期のステップが含まれるシミュレーション データ インスペクターの比較アルゴリズムを使用します。アルゴリズムの詳細については、シミュレーション データ インスペクターでデータを比較する方法を参照してください。

MatchesSignal 制約は、時系列比較にシミュレーション データ インスペクターを使用します。次のいずれかの製品が必要です。

  • Simulink®

  • Signal Processing Toolbox™

  • MATLAB Coder™

  • Fixed-Point Designer™

時系列データの作成

この例では、わかりやすく説明する目的でのみ timeseries 形式でワークスペース データを生成します。MatchesSignal 制約を使用して、シミュレーション出力またはテスト データが含まれるファイルなど、その他のソースからのデータを比較できます。また、この制約はシミュレーション データ インスペクターでサポートされている任意の形式で時系列データを比較できます。

この例では、最初の信号は Wave Data という名前をもつ正弦波のデータが含まれる timeseries オブジェクトです。 

time = 0:0.1:20;
sig1vals = sin(2*pi/5*time);
sig1_ts = timeseries(sig1vals,time);
sig1_ts.Name = 'Wave Data';

2 つ目の信号も、わずかな減衰があり、異なるレートでサンプリングされる同じ周波数の正弦波です。MatchesSignal 制約の比較アルゴリズムには同期ステップが含まれるため、異なる時間ベクトルをもつこれら 2 つの信号を比較しても、結果が常にテスト エラーになるとは限りません。2 つ目の信号は Wave Data とも呼ばれるため、整列アルゴリズムでは、比較するために信号をペアにすることができます。

time2 = 0:0.05:20;
sig2vals = 0.98*sin(2*pi/5*time2);
sig2_ts = timeseries(sig2vals,time2);
sig2_ts.Name = 'Wave Data';

テスト ケースの作成および信号の比較

この例では、わかりやすく説明する目的で対話型テストを使用します。MATLAB テスト フレームワークでその他のユニット テストのタイプをもつ MatchesSignal 制約を使用できます。たとえば、クラス ベースのユニット テストを書き込む方法については、クラスを使用する単純なテスト ケースの記述を参照してください。

対話型で使用する TestCase のインスタンスを作成します。 

import matlab.unittest.TestCase

testCase = TestCase.forInteractiveUse;

MatchesSignal 制約を使用して sig1_ts と sig2_ts を比較します。MatchesSignal 制約のインスタンスの想定される値に sig1_ts を使用します。 

import Simulink.sdi.constraints.MatchesSignal

testCase.verifyThat(sig2_ts,MatchesSignal(sig1_ts));
Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    MatchesSignal(<Value>) failed.
    --> The following aligned signals did not match:
        
              Name       ActualSignals    ExpectedSignals
            _________    _____________    _______________
                                                         
            Wave Data    <Actual>.Data    <Expected>.Data
    
    Comparison results have been saved to:
    --> /tmp/Bdoc23a_2181783_2906229/comparisonResults_503d062a-094a-4367-ad85-fe22ad14d7af.mldatx
    ------------------
    Stack Information:
    ------------------
    In /tmp/Bdoc23a_2181783_2906229/tpd218e4cb/simulink-ex22803619/TestTimeSeriesDataWithTimeToleranceExample.mlx (TestTimeSeriesDataWithTimeToleranceExample) at 14
    In /mathworks/devel/bat/Bdoc23a/build/matlab/toolbox/matlab/codetools/embeddedoutputs/+matlab/+internal/+editor/evaluateRegions.p (evaluateRegions) at 0
    In /mathworks/devel/bat/Bdoc23a/build/matlab/toolbox/matlab/codetools/embeddedoutputs/+matlab/+internal/+editor/EvaluationOutputsService.p (EvaluationOutputsService.evalRegions) at 0
    In /mathworks/devel/bat/Bdoc23a/build/matlab/toolbox/matlab/codetools/+matlab/+internal/+liveeditor/@LiveEditorUtilities/execute.m (execute) at 68
    In /mathworks/devel/bat/Bdoc23a/build/matlab/tools/examples/exampletools/+mwtools/liveCodeToDocbook.m (doRun) at 431
    In /mathworks/devel/bat/Bdoc23a/build/matlab/tools/examples/exampletools/+mwtools/liveCodeToDocbook.m (doRunConvert) at 346
    In /mathworks/devel/bat/Bdoc23a/build/matlab/tools/examples/exampletools/+mwtools/liveCodeToDocbook.m (liveCodeToDocbook) at 164
    In /mathworks/devel/bat/Bdoc23a/build/matlab/tools/build_using_matlab/BML.m (BML) at 13

診断情報は検証が失敗したことを示しています。テストに失敗すると、比較結果および元の実行データがシミュレーション データ インスペクターのセッション ファイルに保存されます。MLDATX ファイルのリンクをクリックしてシミュレーション データ インスペクターでセッションを開きます。ここでは、テストで比較されたデータと、その比較結果を調べることができます。結果を調べると、減衰により差動が生じ、比較の失敗の原因となることがわかります。

比較に使用する MatchesSignal 制約のインスタンスの絶対許容誤差 0.02 を指定します。

testCase.verifyThat(sig2_ts,MatchesSignal(sig1_ts,'AbsTol',0.02));
Verification passed.
ライブ スクリプトを開く

この例では、Simulink.sdi.constraints.MatchesSignalOptions オブジェクトを使用した Simulink.sdi.constraints.MatchesSignal 制約の比較の動作を構成する方法を示します。MatchesSignalOptions オブジェクトを使用して、MatchesSignal インスタンスの構築で単一の名前と値のペアの入力をもつ複数の比較プロパティを構成できます。

時系列データの作成

この例では、わかりやすく説明する目的でのみ、使用するワークスペース データを作成します。MatchesSignal 制約を使用して、シミュレーション出力またはテスト データが含まれるファイルなど、その他のソースからのデータを比較できます。また、この制約はシミュレーション データ インスペクターでサポートされている任意の形式で時系列データを比較できます。

この例では、最初の信号は正弦波のデータを含む Wave Data という名前の timeseries オブジェクトです。

time = 0:0.1:20;
sig1vals = sin(2*pi/5*time);
sig1_ts = timeseries(sig1vals,time);
sig1_ts.Name = 'Wave Data';

2 つ目の信号も、わずかな減衰があり、異なるレートでサンプリングされる同じ周波数の正弦波です。MatchesSignal 制約の比較アルゴリズムには同期ステップが含まれるため、異なる時間ベクトルをもつこれら 2 つの信号を比較しても、結果が必ずしもテスト エラーになるとは限りません。2 番目の信号は single データ型にキャストされ、Wave Data とも呼ばれるため、整列アルゴリズムでは、比較するために信号をペアにすることができます。

time2 = 0:0.1:22;
sig2vals = single(0.98*sin(2*pi/5*time2));
sig2_ts = timeseries(sig2vals,time2);
sig2_ts.Name = 'Wave Data';

MatchesSignal インスタンスの構成およびデータの比較

MatchesSignalOptions オブジェクトを使用して、MatchesSignal 制約のインスタンスがデータ型の不一致などの条件を処理する方法と、実際のデータセットと想定されるデータセットとの間で信号が整列される方法を指定できます。書き込むテストに合わせて MatchesSignalOptions オブジェクトのプロパティを指定できます。たとえば、テストでさまざまな型のデータを比較し、データ型の一致が機能的に関連しない場合、IgnoreDataTypes プロパティを true に設定することもできます。

MatchesSignalOptions オブジェクトを作成して、データ型の不一致や、実際の信号と想定される信号が共有する時間間隔外のデータ サンプルを無視する MatchesSignal インスタンスを作成します。

import Simulink.sdi.constraints.MatchesSignalOptions
opts = MatchesSignalOptions('IgnoringDataTypes',true,'IgnoringExtraData',true);

対話型で使用する TestCase インスタンスを作成し、MatchesSignal 制約、MatchesSignalOptions オブジェクト、0.02 の絶対許容誤差を使用して、sig1_ts と sig2_ts を比較します。

import matlab.unittest.TestCase
testCase = TestCase.forInteractiveUse;

import Simulink.sdi.constraints.MatchesSignal
testCase.verifyThat(sig2_ts,MatchesSignal(sig1_ts,'AbsTol',0.02,'WithOptions',opts))
Verification passed.

テストにパスします。MatchesSignalOptions オブジェクトで定義されたオプションなしで、同じテストを再実行すると、データ型の不一致が原因でテストは失敗します。

testCase.verifyThat(sig2_ts,MatchesSignal(sig1_ts,'AbsTol',0.02))
Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    MatchesSignal(<Value>,'AbsTol',0.02) failed.
    --> Data types do not match for the following aligned signals:
        
              Name       ActualSignals    ActualDataType    ExpectedSignals    ExpectedDataType
            _________    _____________    ______________    _______________    ________________
                                                                                               
            Wave Data    <Actual>.Data        single        <Expected>.Data         double     
    
    ------------------
    Stack Information:
    ------------------
    In /tmp/Bdoc23a_2181783_2898774/tp96c38b24/simulink-ex71177165/ConfigureMatchesSignalConstraintBehaviorExample.mlx (ConfigureMatchesSignalConstraintBehaviorExample) at 16
    In /mathworks/devel/bat/Bdoc23a/build/matlab/toolbox/matlab/codetools/embeddedoutputs/+matlab/+internal/+editor/evaluateRegions.p (evaluateRegions) at 0
    In /mathworks/devel/bat/Bdoc23a/build/matlab/toolbox/matlab/codetools/embeddedoutputs/+matlab/+internal/+editor/EvaluationOutputsService.p (EvaluationOutputsService.evalRegions) at 0
    In /mathworks/devel/bat/Bdoc23a/build/matlab/toolbox/matlab/codetools/+matlab/+internal/+liveeditor/@LiveEditorUtilities/execute.m (execute) at 68
    In /mathworks/devel/bat/Bdoc23a/build/matlab/tools/examples/exampletools/+mwtools/liveCodeToDocbook.m (doRun) at 431
    In /mathworks/devel/bat/Bdoc23a/build/matlab/tools/examples/exampletools/+mwtools/liveCodeToDocbook.m (doRunConvert) at 346
    In /mathworks/devel/bat/Bdoc23a/build/matlab/tools/examples/exampletools/+mwtools/liveCodeToDocbook.m (liveCodeToDocbook) at 164
    In /mathworks/devel/bat/Bdoc23a/build/matlab/tools/build_using_matlab/BML.m (BML) at 13

バージョン履歴

R2019a で導入

すべて展開する

参考

| | | |

トピック