Main Content

matlab.unittest.constraints.RelativeTolerance クラス

名前空間: matlab.unittest.constraints
スーパークラス: matlab.unittest.constraints.Tolerance

数値の相対許容誤差

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

説明

matlab.unittest.constraints.RelativeTolerance クラスは、数値配列 actual と expected の比較のための数値の相対許容誤差を提供します。この許容誤差では、配列 expected に対する配列間の相対的な差の大きさが調べられます。値 RelTol の相対許容誤差を満たすには、abs(expected-actual) <= RelTol.*abs(expected) が true である必要があります。

数値配列を比較するための許容誤差を指定した場合、テスト フレームワークで配列 actual と expected のクラス、サイズ、スパース性の等価性が最初にチェックされます。これらのいずれかのチェックに失敗すると、配列は等しくないと見なされます。これらのチェックにパスした場合に、配列の実数/複素数が同じでないか、それらが関数 isequaln で異なると判定されると、比較がフレームワークから許容誤差にデリゲートされます。

作成

説明

t = matlab.unittest.constraints.RelativeTolerance(value1,...,valueN) は、指定された許容誤差値を使用して相対許容誤差を作成します。たとえば、t = matlab.unittest.constraints.RelativeTolerance(10*eps("single"),0.1) は、単精度または倍精度の数値配列のペアを比較するための相対許容誤差を作成します。

  • 単精度の数値配列を比較するときは 10*eps("single") の許容誤差値が適用されます。

  • 倍精度の数値配列を比較するときは 0.1 の許容誤差値が適用されます。

許容誤差値のデータ型は、許容誤差でサポートされるデータ型のみになります。実際の配列と期待される配列に異なるデータ型の値が格納されている場合、許容誤差でサポートされるデータ型の値にのみ許容誤差が適用されます。

数値許容誤差を & および | の演算子で組み合わせることにより、特定の数値型に対して複数の許容誤差値を指定できます。この方法で特定の数値型に対して複数の許容誤差値を指定する場合、それらの許容誤差値は同じサイズであるか、互換性のあるサイズでなければなりません。互換性のある配列の詳細については、基本的な演算で互換性のある配列サイズを参照してください。

例

入力引数

すべて展開する

許容誤差値。浮動小数点配列のコンマ区切りリストとして指定します。MATLAB® の浮動小数点型には single と double (および single と double のサブクラス) があります。

指定される許容誤差値は明確なデータ型をもたなければなりません。許容誤差値が非スカラーの場合は、その各次元の長さが 1 であるか、期待される数値配列の対応する次元の長さと等しくなければなりません。

この引数は Values プロパティを設定します。

例: 0.1

例: [1e-2 1-e4]

例: 10*eps("single"),1e-2

プロパティ

すべて展開する

許容誤差値。浮動小数点配列の cell 配列として返されます。cell 配列の各要素は、許容誤差の作成時に指定された許容誤差値の 1 つに対応します。

このプロパティは入力引数 value1,...,valueN によって設定されます。

属性:

GetAccess
public
SetAccess
immutable

例

すべて折りたたむ

スクリプトを開く

RelativeTolerance クラスを使用して、実際の値と期待される値を比較します。

最初に、この例で使用するクラスをインポートします。

import matlab.unittest.TestCase
import matlab.unittest.constraints.IsEqualTo
import matlab.unittest.constraints.RelativeTolerance

対話型テスト用にテスト ケースを作成します。

testCase = TestCase.forInteractiveUse;

値 4.1 と 4.5 が等価であるかどうかをテストします。テストは失敗します。

testCase.verifyThat(4.1,IsEqualTo(4.5))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsEqualTo failed.
    --> NumericComparator failed.
        --> The numeric values are not equal using "isequaln".
        --> Failure table:
                Actual    Expected    Error      RelativeError   
                ______    ________    _____    __________________
                                                                 
                 4.1        4.5       -0.4     -0.088888888888889
        
        Actual Value:
           4.100000000000000
        Expected Value:
           4.500000000000000
    ------------------
    Stack Information:
    ------------------
    In C:\work\CompareValuesUsingRelativeToleranceExample.m (CompareValuesUsingRelativeToleranceExample) at 16

相対許容誤差を指定して、テストをもう一度実行します。値が 10% の範囲内で等価であることを検証します。テストはパスします。

testCase.verifyThat(4.1,IsEqualTo(4.5, ...
    "Within",RelativeTolerance(0.1)))

Verification passed.

2 つの cell 配列が 2% の範囲内で等価であるかどうかをテストします。許容誤差が double 型の要素にしか適用されないため、テストは失敗します。

actual = {'abc',123,single(106)};
expected = {'abc',122,single(105)};
testCase.verifyThat(actual,IsEqualTo(expected, ...
    "Within",RelativeTolerance(0.02)))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsEqualTo failed.
    --> Path to failure: <Value>{3}
        --> NumericComparator failed.
            --> The numeric values are not equal using "isequaln".
            --> The tolerance was ignored. The tolerance as specified does not support comparisons of single values.
            --> Failure table:
                    Actual    Expected    Error    RelativeError
                    ______    ________    _____    _____________
                                                                
                     106        105         1       0.00952381  
            
            Actual Value:
              single
            
               106
            Expected Value:
              single
            
               105
    
    Actual Value:
      1×3 cell array
    
        {'abc'}    {[123]}    {[106]}
    Expected Value:
      1×3 cell array
    
        {'abc'}    {[122]}    {[105]}
    ------------------
    Stack Information:
    ------------------
    In C:\work\CompareValuesUsingRelativeToleranceExample.m (CompareValuesUsingRelativeToleranceExample) at 27

異なる数値型をサポートする相対許容誤差を作成します。cell 配列の double 型と single 型の要素の比較用に、許容誤差値 0.02 と single(0.02) をそれぞれ指定します。この許容誤差を使用して cell 配列を比較すると、テストはパスします。

tol = RelativeTolerance(0.02,single(0.02));
testCase.verifyThat(actual,IsEqualTo(expected, ...
    "Within",tol))

Verification passed.
スクリプトを開く

数値許容誤差の組み合わせを使用して、実際の値と期待される値を比較します。許容誤差の組み合わせには、& および | の演算子を使用します。

最初に、この例で使用するクラスをインポートします。

import matlab.unittest.TestCase
import matlab.unittest.constraints.IsEqualTo
import matlab.unittest.constraints.AbsoluteTolerance
import matlab.unittest.constraints.RelativeTolerance

対話型テスト用にテスト ケースを作成します。

testCase = TestCase.forInteractiveUse;

値 3.14 を pi と比較します。テストは失敗します。

testCase.verifyThat(3.14,IsEqualTo(pi))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsEqualTo failed.
    --> NumericComparator failed.
        --> The numeric values are not equal using "isequaln".
        --> Failure table:
                Actual        Expected               Error                RelativeError    
                ______    ________________    ____________________    _____________________
                                                                                           
                 3.14     3.14159265358979    -0.00159265358979299    -0.000506957382897213
        
        Actual Value:
           3.140000000000000
        Expected Value:
           3.141592653589793
    ------------------
    Stack Information:
    ------------------
    In C:\work\CombineAbsoluteAndRelativeTolerancesExample.m (CombineAbsoluteAndRelativeTolerancesExample) at 18

絶対許容誤差と相対許容誤差を使用して値を比較します。実際の値と期待される値が絶対許容誤差、相対許容誤差、または両方の範囲内で等価であることを検証します。テストはパスします。

tol1 = AbsoluteTolerance(0.001);
tol2 = RelativeTolerance(0.0025);
testCase.verifyThat(3.14,IsEqualTo(pi, ...
    "Within",tol1 | tol2))

Verification passed.

実際の値と期待される値が両方の許容誤差の範囲内で等価であるかどうかをテストします。絶対許容誤差を満たさないため、テストは失敗します。

testCase.verifyThat(3.14,IsEqualTo(pi, ...
    "Within",tol1 & tol2))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsEqualTo failed.
    --> NumericComparator failed.
        --> The numeric values are not equal using "isequaln".
        --> AndTolerance failed.
            --> AbsoluteTolerance failed.
                --> The error was not within absolute tolerance.
            --> RelativeTolerance passed.
                --> The error was within relative tolerance.
            --> Failure table:
                    Actual        Expected               Error                RelativeError        AbsoluteTolerance    RelativeTolerance
                    ______    ________________    ____________________    _____________________    _________________    _________________
                                                                                                                                         
                     3.14     3.14159265358979    -0.00159265358979299    -0.000506957382897213          0.001               0.0025      
        
        Actual Value:
           3.140000000000000
        Expected Value:
           3.141592653589793
    ------------------
    Stack Information:
    ------------------
    In C:\work\CombineAbsoluteAndRelativeTolerancesExample.m (CombineAbsoluteAndRelativeTolerancesExample) at 31
スクリプトを開く

数値配列を比較する方法をカスタマイズするには、テストで許容誤差と制約の組み合わせを使用します。

最初に、この例で使用するクラスをインポートします。

import matlab.unittest.TestCase
import matlab.unittest.constraints.IsEqualTo
import matlab.unittest.constraints.AbsoluteTolerance
import matlab.unittest.constraints.RelativeTolerance

対話型テスト用にテスト ケースを作成します。

testCase = TestCase.forInteractiveUse;

IsEqualTo 制約を使用して、2 つの数値ベクトルを比較します。テストは失敗します。

exp = [1 100];
act = [1.1 101.1];
testCase.verifyThat(act,IsEqualTo(exp))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsEqualTo failed.
    --> NumericComparator failed.
        --> The numeric values are not equal using "isequaln".
        --> Failure table:
                Index    Actual    Expected         Error            RelativeError   
                _____    ______    ________    ________________    __________________
                                                                                     
                  1      1.1         1         0.1                 0.1               
                  2      101.1       100       1.09999999999999    0.0109999999999999
        
        Actual Value:
           1.0e+02 *
        
           0.011000000000000   1.011000000000000
        Expected Value:
             1   100
    ------------------
    Stack Information:
    ------------------
    In C:\work\CompareArraysWithDifferentTolerancesExample.m (CompareArraysWithDifferentTolerancesExample) at 21

絶対許容誤差と相対許容誤差を使用して、ベクトル間の要素単位の比較を実行します。対応するベクトル要素がいずれかの許容誤差を満たすことを検証します。テストはパスします。

absTol = AbsoluteTolerance(1);
relTol = RelativeTolerance(0.02);
testCase.verifyThat(act,IsEqualTo(exp,"Within",absTol | relTol))

Verification passed.

次に、対応するすべての要素が絶対許容誤差を満たすかどうか、あるいはそれらのすべてが相対許容誤差を満たすかどうかをテストします。最初の要素と 2 番目の要素がそれぞれ絶対許容誤差と相対許容誤差の一方しか満たさないため、テストは失敗します。

testCase.verifyThat(act, ...
    IsEqualTo(exp,"Within",absTol) | IsEqualTo(exp,"Within",relTol))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    OrConstraint failed.
    --> + [First Condition]:
         |   IsEqualTo failed.
         |   --> NumericComparator failed.
         |       --> The numeric values are not equal using "isequaln".
         |       --> AbsoluteTolerance failed.
         |           --> The error was not within absolute tolerance.
         |           --> Failure table:
         |                   Index    Actual    Expected         Error            RelativeError       AbsoluteTolerance
         |                   _____    ______    ________    ________________    __________________    _________________
         |                                                                                                             
         |                     2      101.1       100       1.09999999999999    0.0109999999999999            1        
         |       
         |       Actual Value:
         |          1.0e+02 *
         |       
         |          0.011000000000000   1.011000000000000
         |       Expected Value:
         |            1   100
    --> OR
        + [Second Condition]:
         |   IsEqualTo failed.
         |   --> NumericComparator failed.
         |       --> The numeric values are not equal using "isequaln".
         |       --> RelativeTolerance failed.
         |           --> The error was not within relative tolerance.
         |           --> Failure table:
         |                   Index    Actual    Expected    Error    RelativeError    RelativeTolerance
         |                   _____    ______    ________    _____    _____________    _________________
         |                                                                                             
         |                     1       1.1         1         0.1          0.1               0.02       
         |       
         |       Actual Value:
         |          1.0e+02 *
         |       
         |          0.011000000000000   1.011000000000000
         |       Expected Value:
         |            1   100
        -+---------------------
    ------------------
    Stack Information:
    ------------------
    In C:\work\CompareArraysWithDifferentTolerancesExample.m (CompareArraysWithDifferentTolerancesExample) at 34
スクリプトを開く

許容誤差を組み合わせて、構造体に格納された値を比較するときに、値がゼロに近ければ絶対許容誤差を適用し、はるかに大きければ相対許容誤差を適用するように設定します。

最初に、この例で使用するクラスをインポートします。

import matlab.unittest.TestCase
import matlab.unittest.constraints.IsEqualTo
import matlab.unittest.constraints.AbsoluteTolerance
import matlab.unittest.constraints.RelativeTolerance

対話型テスト用にテスト ケースを作成します。

testCase = TestCase.forInteractiveUse;

SI 単位で表された真空の電磁特性の値を含む 2 つの構造体を作成します。構造体 approximate には、構造体 baseline に格納された値の近似を格納します。

baseline.LightSpeed = 299792458;
baseline.Permeability = 4*pi*10^-7;
baseline.Permittivity = 1/(baseline.Permeability*baseline.LightSpeed^2);

approximate.LightSpeed = 2.9979e+08;
approximate.Permeability = 1.2566e-06;
approximate.Permittivity = 8.8542e-12;

対応する近似値とベースライン値の相対差が eps*1.0000e+11 以内であるかどうかをテストします。透磁率の差は小さくなっていますが、期待される透磁率と比較して相対許容誤差を満たすほど十分に小さくはありません。

testCase.verifyThat(approximate,IsEqualTo(baseline, ...
    "Within",RelativeTolerance(eps*1.0000e+11)))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsEqualTo failed.
    --> Path to failure: <Value>.Permeability
        --> NumericComparator failed.
            --> The numeric values are not equal using "isequaln".
            --> RelativeTolerance failed.
                --> The error was not within relative tolerance.
                --> Failure table:
                          Actual            Expected                  Error                RelativeError         RelativeTolerance  
                        __________    ____________________    _____________________    _____________________    ____________________
                                                                                                                                    
                        1.2566e-06    1.25663706143592e-06    -3.70614359173257e-11    -2.94925536216295e-05    2.22044604925031e-05
            
            Actual Value:
                 1.256600000000000e-06
            Expected Value:
                 1.256637061435917e-06
    
    Actual Value:
      struct with fields:
    
          LightSpeed: 299790000
        Permeability: 1.256600000000000e-06
        Permittivity: 8.854200000000000e-12
    Expected Value:
      struct with fields:
    
          LightSpeed: 299792458
        Permeability: 1.256637061435917e-06
        Permittivity: 8.854187817620389e-12
    ------------------
    Stack Information:
    ------------------
    In C:\work\CompareStructuresThatContainSmallAndLargeValuesExample.m (CompareStructuresThatContainSmallAndLargeValuesExample) at 36

対応する近似値とベースライン値の絶対差が 1.0000e-04 以内であるかどうかをテストします。光の速度の差は期待される光の速度と比較して小さくなっていますが、絶対許容誤差を満たすには大きすぎます。

testCase.verifyThat(approximate,IsEqualTo(baseline, ...
    "Within",AbsoluteTolerance(1.0000e-04)))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsEqualTo failed.
    --> Path to failure: <Value>.LightSpeed
        --> NumericComparator failed.
            --> The numeric values are not equal using "isequaln".
            --> AbsoluteTolerance failed.
                --> The error was not within absolute tolerance.
                --> Failure table:
                         Actual      Expected     Error        RelativeError        AbsoluteTolerance
                        _________    _________    _____    _____________________    _________________
                                                                                                     
                        299790000    299792458    -2458    -8.19900545997058e-06         0.0001      
            
            Actual Value:
               299790000
            Expected Value:
               299792458
    
    Actual Value:
      struct with fields:
    
          LightSpeed: 299790000
        Permeability: 1.256600000000000e-06
        Permittivity: 8.854200000000000e-12
    Expected Value:
      struct with fields:
    
          LightSpeed: 299792458
        Permeability: 1.256637061435917e-06
        Permittivity: 8.854187817620389e-12
    ------------------
    Stack Information:
    ------------------
    In C:\work\CompareStructuresThatContainSmallAndLargeValuesExample.m (CompareStructuresThatContainSmallAndLargeValuesExample) at 44

次に、許容誤差を組み合わせて、対応する近似値とベースライン値の絶対差が 1.0000e-04 以内であること、またはその相対差が eps*1.0000e+11 以内であることを検証します。この場合、ゼロに近い透磁率が絶対許容誤差を満たし、はるかに大きな光の速度が相対許容誤差を満たします。

testCase.verifyThat(approximate,IsEqualTo(baseline, ...
    "Within",RelativeTolerance(eps*1.0000e+11) | ...
    AbsoluteTolerance(1.0000e-04)))

Verification passed.

バージョン履歴

R2013a で導入

参考

| | |