matlab.unittest.constraints.AbsoluteTolerance - Absolute numeric tolerance - MATLAB (original) (raw)

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

Absolute numeric tolerance

Description

The matlab.unittest.constraints.AbsoluteTolerance class provides an absolute numeric tolerance for the comparison of actual andexpected numeric arrays. The tolerance examines the magnitude of the difference between the arrays. For an absolute tolerance with the valueAbsTol to be satisfied, abs(expected-actual) <= AbsTol 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 andexpected 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 theisequaln function finds them different, then the framework delegates comparison to the tolerance.

Creation

Description

t = matlab.unittest.constraints.AbsoluteTolerance([value1,...,valueN](#mw%5Fdfde80f5-da0e-4c8b-aaa5-e5841dbd494a)) creates an absolute tolerance using the specified tolerance values. For example,t = matlab.unittest.constraints.AbsoluteTolerance(10*eps("single"),0.1,int8(1)) creates an absolute tolerance for comparing a pair of single-precision numeric arrays, double-precision numeric arrays, or numeric arrays of type int8:

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 tolerance value of int8(1) is applied when comparing numeric arrays of type int8.

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 numeric arrays. For more information about numeric arrays in MATLAB®, see Numeric Types.

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](matlab.unittest.constraints.absolutetolerance-class.html#mw%5F6eeb46a3-9462-47c8-9289-5631368098d2) property.

Example: 1

Example: [0.5 1]

Example: single(1),1,int8([1 2 4])

Properties

expand all

Tolerance values, returned as a cell array of numeric 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

Compare actual and expected values using the AbsoluteTolerance class.

First, import the classes used in this example.

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

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

             4.1        4.5       -0.4     -0.088888888888889
    
    Actual Value:
       4.100000000000000
    Expected Value:
       4.500000000000000
------------------
Stack Information:
------------------
In C:\work\CompareValuesUsingAbsoluteToleranceExample.m (CompareValuesUsingAbsoluteToleranceExample) at 16

Repeat the test, specifying an absolute tolerance. Verify that the values are equal within a tolerance of 0.5. The test passes.

testCase.verifyThat(4.1,IsEqualTo(4.5, ... "Within",AbsoluteTolerance(0.5)))

Test if two cell arrays are equal using a tolerance value of 3. The test fails because the tolerance applies only to the elements of type double.

actual = {'abc',123,single(106),int8([1 2 3])}; expected = {'abc',122,single(105),int8([2 4 6])}; testCase.verifyThat(actual,IsEqualTo(expected, ... "Within",AbsoluteTolerance(3)))

Verification failed. --------------------- Framework Diagnostic: --------------------- IsEqualTo failed. --> Path to failure: {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×4 cell array

    {'abc'}    {[123]}    {[106]}    {[1 2 3]}
Expected Value:
  1×4 cell array

    {'abc'}    {[122]}    {[105]}    {[2 4 6]}
------------------
Stack Information:
------------------
In C:\work\CompareValuesUsingAbsoluteToleranceExample.m (CompareValuesUsingAbsoluteToleranceExample) at 28

Create an absolute tolerance that supports different numeric types. Specify the tolerance values of 3, single(1), and int8([1 2 4]) for comparing cell array elements of type double, single, and int8, respectively. If you compare the cell arrays using this tolerance, the test passes.

tol = AbsoluteTolerance(3,single(1),int8([1 2 4])); testCase.verifyThat(actual,IsEqualTo(expected, ... "Within",tol))

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

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

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

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

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 = 4pi10^-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: .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: .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)))

Version History

Introduced in R2013a