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 的容差值。

容差值的数据类型是容差支持的唯一数据类型。如果实际数组和预期数组包含不同数据类型的值，则容差仅适用于其数据类型受容差支持的值。

通过将数值容差与 & 和 | 运算符组合，可以为特定数值类型指定多个容差值。如果以这种方式为特定数值类型指定多个容差值，这些容差值的大小必须相同或兼容。有关兼容数组的详细信息，请参阅基本运算的兼容数组大小。

输入参数

全部展开

`value1,...,valueN` — 容差值
以逗号分隔的浮点数组列表

容差值，指定为以逗号分隔的浮点数组列表。MATLAB^® 中的浮点类型包括 single 和 double（以及 single 和 double 的子类）。

指定的容差值必须具有不同的数据类型。如果容差值是非标量值，则其每个维度的长度必须为 1 或等于预期数值数组的对应维度长度。

此参数设置 Values 属性。

示例： 0.1

示例： [1e-2 1-e4]

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

属性

全部展开

`Values` — 容差值
浮点数组组成的元胞数组

容差值，以浮点数组组成的元胞数组形式返回。元胞数组的每个元素对应于在容差创建期间指定的容差值之一。

此属性由 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% 的范围内相等。测试失败，因为容差仅适用于 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

创建支持不同数值类型的相对容差。指定容差值 0.02 和 single(0.02)，分别用于比较 double 和 single 类型的元胞数组元素。如果使用此容差比较元胞数组，则测试通过。

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 约束比较两个数值向量。测试失败。

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.

现在测试是否所有对应的元素都满足绝对容差，或是否所有元素都满足相对容差。测试失败，因为第一个和第二个元素仅分别满足绝对和相对容差。

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 单位表示的真空电磁属性的值。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 中推出

另请参阅

matlab.unittest.constraints.AbsoluteTolerance | matlab.unittest.constraints.AndTolerance | matlab.unittest.constraints.OrTolerance | matlab.unittest.constraints.IsEqualTo

matlab.unittest.constraints.RelativeTolerance 类

描述

创建对象

描述

输入参数

value1,...,valueN — 容差值 以逗号分隔的浮点数组列表

属性

Values — 容差值 浮点数组组成的元胞数组

属性：

示例

使用相对容差比较值

组合绝对和相对误差

使用不同容差比较数组

比较包含小值和大值的结构体

版本历史记录

另请参阅

WeChat

`value1,...,valueN` — 容差值
以逗号分隔的浮点数组列表

`Values` — 容差值
浮点数组组成的元胞数组