Main Content

matlab.unittest.constraints.RelativeTolerance Class

Namespace: matlab.unittest.constraints
Superclasses: matlab.unittest.constraints.Tolerance

Relative numeric tolerance

expand all in page

Description

The matlab.unittest.constraints.RelativeTolerance class provides a relative numeric tolerance for the comparison of actual and expected numeric arrays. The tolerance examines the magnitude of the difference between the arrays, relative to the expected array. For a relative tolerance with the value RelTol to be satisfied, abs(expected-actual) <= RelTol.*abs(expected) must be true.

When you specify a tolerance for comparing numeric arrays, the testing framework first checks for equivalent class, size, and sparsity of the actual and expected arrays. If any of these checks fail, the arrays are considered not equal. If the checks pass, but the arrays do not have the same complexity, or if the isequaln function finds them different, then the framework delegates comparison to the tolerance.

Creation

Description

t = matlab.unittest.constraints.RelativeTolerance(value1,...,valueN) creates a relative tolerance using the specified tolerance values. For example, t = matlab.unittest.constraints.RelativeTolerance(10*eps("single"),0.1) creates a relative tolerance for comparing a pair of single-precision or double-precision numeric arrays:

  • The tolerance value of 10*eps("single") is applied when comparing single-precision numeric arrays.

  • The tolerance value of 0.1 is applied when comparing double-precision numeric arrays.

The data types of the tolerance values are the only data types the tolerance supports. If the actual and expected arrays contain values with different data types, the tolerance applies only to the values whose data type is supported by the tolerance.

You can specify more than one tolerance value for a particular numeric type by combining numeric tolerances with the & and | operators. If you specify multiple tolerance values for a particular numeric type this way, the sizes of these tolerance values must be the same or be compatible. See Compatible Array Sizes for Basic Operations for more information about compatible arrays.

example

Input Arguments

expand all

Tolerance values, specified as a comma-separated list of floating-point arrays. Floating-point types in MATLAB® include single and double (and subclasses of single and double).

The specified tolerance values must have distinct data types. If a tolerance value is nonscalar, the length of each of its dimensions must be 1 or equal to the corresponding dimension length of the expected numeric array.

This argument sets the Values property.

Example: 0.1

Example: [1e-2 1-e4]

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

Properties

expand all

Tolerance values, returned as a cell array of floating-point arrays. Each element of the cell array corresponds to one of the tolerance values specified during the creation of the tolerance.

This property is set by the value1,...,valueN input argument.

Attributes:

GetAccess
public
SetAccess
immutable

Examples

collapse all

Open Script

Compare actual and expected values using the RelativeTolerance class.

First, import the classes used in this example.

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

Create a test case for interactive testing.

testCase = TestCase.forInteractiveUse;

Test if the values 4.1 and 4.5 are equal. The test fails.

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

Repeat the test, specifying a relative tolerance. Verify that the values are equal within 10%. The test passes.

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

Verification passed.

Test if two cell arrays are equal within 2%. The test fails because the tolerance applies only to the elements of type 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

Create a relative tolerance that supports different numeric types. Specify the tolerance values of 0.02 and single(0.02) for comparing cell array elements of type double and single, respectively. If you compare the cell arrays using this tolerance, the test passes.

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

Verification passed.
Open Script

Compare actual and expected values using a combination of numeric tolerances. To combine tolerances, use the & and | operators.

First, import the classes used in this example.

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

Create a test case for interactive testing.

testCase = TestCase.forInteractiveUse;

Compare the value 3.14 to pi. The test fails.

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

Compare the values using an absolute tolerance and a relative tolerance. Verify that the actual and expected values are equal within the absolute tolerance, the relative tolerance, or both. The test passes.

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

Verification passed.

Test if the actual and expected values are equal within both the tolerances. The test fails because the absolute tolerance is not satisfied.

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
Open Script

To customize how numeric arrays are compared, use a combination of tolerances and constraints in your tests.

First, import the classes used in this example.

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

Create a test case for interactive testing.

testCase = TestCase.forInteractiveUse;

Compare two numeric vectors using the IsEqualTo constraint. The test fails.

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

Perform element-wise comparisons between the vectors using absolute and relative tolerances. Verify that corresponding vector elements satisfy either of the tolerances. The test passes.

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

Verification passed.

Now test if all the corresponding elements satisfy the absolute tolerance, or if all of them satisfy the relative tolerance. The test fails because the first and second elements satisfy only the absolute and relative tolerances, respectively.

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
Open Script

Combine tolerances so that when you compare values contained in structures, an absolute tolerance applies when the values are close to zero and a relative tolerance applies when they are much larger.

First, import the classes used in this example.

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

Create a test case for interactive testing.

testCase = TestCase.forInteractiveUse;

Create two structures that contain the values of electromagnetic properties of a vacuum, expressed in SI units. The approximate structure holds approximations for the values contained in the baseline structure.

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;

Test if the relative difference between the corresponding approximate and baseline values is within eps*1.0000e+11. Even though the difference between the permeabilities is small, it is not small enough relative to the expected permeability to satisfy the relative tolerance.

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

Test if the absolute difference between the corresponding approximate and baseline values is within 1.0000e-04. Even though the difference between the light speeds is small relative to the expected light speed, it is too large to satisfy the absolute tolerance.

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

Now, combine the tolerances to verify that the absolute difference between the corresponding approximate and baseline values is within 1.0000e-04 or their relative difference is within eps*1.0000e+11. In this case, the permeabilities that are close to zero satisfy the absolute tolerance, and the light speeds that are much larger satisfy the relative tolerance.

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

Verification passed.

Version History

Introduced in R2013a

See Also

| | |