matlab.unittest.constraints.AbsoluteTolerance class

Package: matlab.unittest.constraints
Superclasses: matlab.unittest.constraints.Tolerance

Absolute numeric tolerance

Description

This numeric Tolerance assesses the magnitude of the difference between actual and expected values. For the tolerance to be satisfied, abs(expVal - actVal) <= absTol must be true.

Construction

AbsoluteTolerance(tolVals) creates an absolute tolerance object that assesses the magnitude of the difference between the actual and expected values.

The data types of the inputs to the AbsoluteTolerance constructor determines which data types the tolerance supports. For example, AbsoluteTolerance(10*eps) constructs an AbsoluteTolerance for comparing double-precision numeric arrays, while AbsoluteTolerance(int8(2)) constructs an AbsoluteTolerance for comparing numeric arrays of type int8. If the actual and expected values being compared contain more than one numeric data type, the tolerance only applies to the data types specified by the values passed into the constructor.

To specify different tolerance values for different data types, you can pass multiple tolerance values to the constructor. For example, AbsoluteTolerance(10*eps, 10*eps('single'), int8(1)) constructs an AbsoluteTolerance object applies the following absolute tolerances:

  • 10*eps applies an absolute tolerance of 10*eps for double-precision numeric arrays.

  • 10*eps('single') applies an absolute tolerance of 10*eps for single-precision numeric arrays.

  • int8(1) applies an absolute tolerance of 1 for numeric arrays of type int8.

You can specify more than one tolerance for a particular data type by combining tolerances with the & and | operators. To combine two tolerances, the sizes of the tolerance values for each data type must be compatible.

Input Arguments

tolVals

Numeric tolerances, specified as a comma-separated list of numeric arrays. Each input argument contains the tolerance specification for a particular data type. Each numeric array can be a scalar or array the same size as the actual and expected values.

Properties

Values

Numeric tolerances, specified by the tolVals input argument

Methods

andForm logical element-wise conjunction of tolerances
orForm logical element-wise disjunction of tolerances

Copy Semantics

Value. To learn how value classes affect copy operations, see Copying Objects in the MATLAB® documentation.

Examples

expand all

Test with Absolute Tolerance

Create a test case for interactive testing.

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

testCase = TestCase.forInteractiveUse;

Assert that the difference between an actual value, 4.1, and an expected value, 4.5, is less than 0.5.

testCase.assertThat(4.1, IsEqualTo(4.5, ...
    'Within', AbsoluteTolerance(0.5)))
Interactive assertion passed.

Specify Absolute Tolerance for Different Data Types

Create a test case for interactive testing.

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

testCase = TestCase.forInteractiveUse;

Create the following actual and expected cell arrays.

act = {'abc', 123, single(106), int8([1, 2, 3])};
exp = {'abc', 122, single(105), int8([2, 4, 6])};

Test whether the arrays satisfy the AbsoluteTolerance constraint within a value of 2.

testCase.verifyThat(act, IsEqualTo(exp, ...
    'Within', AbsoluteTolerance(2)))
Interactive verification failed.

---------------------
Framework Diagnostic:
---------------------
IsEqualTo failed.
--> NumericComparator failed.
    Path to failure: <Value>{3}
    --> The values are not equal using "isequaln".
    --> The tolerance does not support single values so it was not used.
    --> Failure table:
                Index    Actual    Expected    Error    RelativeError
                _____    ______    ________    _____    _____________
            
                1        106       105         1        0.00952381   
    
    Actual Value:
           106
    Expected Value:
           105

Actual cell:
        'abc'    [123]    [106]    [1x3 int8]
Expected cell:
        'abc'    [122]    [105]    [1x3 int8]

The test fails because the tolerance is only applied to the double data type.

Create a tolerance object that specifies different tolerances for different data types.

tolObj = AbsoluteTolerance(2, single(3), int8([2, 3, 5]));

A tolerance of 2 is a applied to double valued data. A tolerance of 3 is applied to single valued data. A tolerance of [2 3 5] is applied to corresponding array elements of int8 valued data.

Verify that the expected and actual values satisfy the AbsoluteTolerance constraint.

testCase.verifyThat(act, IsEqualTo(exp, 'Within', tolObj))
Interactive verification passed.

Combine Absolute and Relative Tolerances

Create a test case for interactive testing.

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

testCase = TestCase.forInteractiveUse;

Define an actual value approximation for pi.

act = 3.14;

Construct a tolerance object to test that the difference between the actual and expected values is within 0.001 and within 0.25%.

tolObj = AbsoluteTolerance(0.001) & RelativeTolerance(0.0025);

Verify that the actual value is within the tolerance of the expected value of pi.

testCase.verifyThat(act, IsEqualTo(pi, 'Within', tolObj))
Interactive verification failed.

---------------------
Framework Diagnostic:
---------------------
IsEqualTo failed.
--> NumericComparator failed.
    --> The values are not equal using "isequaln".
    --> AndTolerance failed.
        --> AbsoluteTolerance failed.
            --> The error was not within absolute tolerance.
        --> RelativeTolerance passed.
        --> Failure table:
                    Index    Actual        Expected               Error                RelativeError        AbsoluteTolerance    RelativeTolerance
                    _____    ______    ________________    ____________________    _____________________    _________________    _________________
                
                    1        3.14      3.14159265358979    -0.00159265358979299    -0.000506957382897213    0.001                0.0025           

Actual Value:
       3.140000000000000
Expected Value:
       3.141592653589793

The actual value does not satisfy the AbsoluteTolerance constraint.

Construct a constraint that is satisfied if the values are within 0.001 or 0.25%, and then retest the actual value.

tolObj = AbsoluteTolerance(0.001) | RelativeTolerance(0.0025);
testCase.verifyThat(act, IsEqualTo(pi, 'Within', tolObj))
Interactive verification passed.

Combine Absolute and Relative Tolerances to Test Small and Large Values

Combine tolerances so when you test the equality of values, an absolute (floor) tolerance dominates when the values are near zero, and a relative tolerance dominates for larger values.

Create a test case for interactive testing.

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

testCase = TestCase.forInteractiveUse;

Define two structures containing electromagnetic properties of a vacuum. One structure, approxVacuumProps, contains approximate values for the permeability and speed of light in a vacuum.

approxVacuumProps.Permeability = 1.2566e-06; % Approximate
approxVacuumProps.Permitivity = 8.854187817*10^-12;
approxVacuumProps.LightSpeed = 2.9979e+08; % Approximate

baselineVacuumProps.Permeability = 4*pi*10^-7;
baselineVacuumProps.Permitivity = 8.854187817*10^-12;
baselineVacuumProps.LightSpeed = 1/sqrt(...
    baselineVacuumProps.Permeability*baselineVacuumProps.Permitivity);

Test that the relative difference between the approximate and baseline values is within eps*1e11.

testCase.verifyThat(approxVacuumProps, IsEqualTo(baselineVacuumProps, ...
    'Within', RelativeTolerance(eps*1e11)))
Interactive verification failed.

---------------------
Framework Diagnostic:
---------------------
IsEqualTo failed.
--> NumericComparator failed.
    Path to failure: <Value>.Permeability
    --> The 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.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 struct:
        Permeability: 1.256600000000000e-06
         Permitivity: 8.854187816999999e-12
          LightSpeed: 299790000
Expected struct:
        Permeability: 1.256637061435917e-06
         Permitivity: 8.854187816999999e-12
          LightSpeed: 2.997924580105029e+08

The test fails because the relative difference in the permeabilities is not within the tolerance. The difference between the two values is small, but the numbers are close to zero, so the difference relative to their size is not small enough to satisfy the tolerance.

Construct a tolerance object to test that the absolute difference between the approximate and baseline values is within 1e-4.

testCase.verifyThat(approxVacuumProps, IsEqualTo(baselineVacuumProps, ...
    'Within', AbsoluteTolerance(1e-4)))
Interactive verification failed.

---------------------
Framework Diagnostic:
---------------------
IsEqualTo failed.
--> NumericComparator failed.
    Path to failure: <Value>.LightSpeed
    --> The values are not equal using "isequaln".
    --> AbsoluteTolerance failed.
        --> The error was not within absolute tolerance.
        --> Failure table:
                    Index     Actual          Expected              Error             RelativeError        AbsoluteTolerance
                    _____    _________    ________________    _________________    ____________________    _________________
                
                    1        299790000    299792458.010503    -2458.01050287485    -8.1990404935028e-06    0.0001           
    
    Actual Value:
           299790000
    Expected Value:
             2.997924580105029e+08

Actual struct:
        Permeability: 1.256600000000000e-06
         Permitivity: 8.854187816999999e-12
          LightSpeed: 299790000
Expected struct:
        Permeability: 1.256637061435917e-06
         Permitivity: 8.854187816999999e-12
          LightSpeed: 2.997924580105029e+08

The test fails because the absolute difference in the speed of light is not within the tolerance. The difference between the two values is small relative to their size, but too large to satisfy the tolerance.

Construct a logical disjunction of tolerance objects to test that the absolute difference between the approximate and baseline values is within 1e-4 or the relative difference is within eps*1e11. The test uses this tolerance so permeability values that are close to zero satisfy the absolute (floor) tolerance, and speed of light values that are large, satisfy the relative tolerance.

testCase.verifyThat(approxVacuumProps, IsEqualTo(baselineVacuumProps, ...
    'Within', RelativeTolerance(eps*1e11)| AbsoluteTolerance(1e-4)))
Interactive verification passed.
Was this topic helpful?