Main Content

matlab.unittest.constraints.RelativeTolerance class

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

Relative numeric tolerance

expand all in page

Description

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

Construction

RelativeTolerance(tolVals) creates a relative tolerance object that assesses the magnitude of the difference between actual and expected values, relative to the expected value.

The data types of the inputs to the RelativeTolerance constructor determine which data types the tolerance supports. For example, RelativeTolerance(10*eps) constructs a RelativeTolerance for comparing double-precision numeric arrays while RelativeTolerance(single(2)) constructs a RelativeTolerance for comparing single-precision numeric arrays. 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, RelativeTolerance(10*eps, 10*eps('single')) constructs an RelativeTolerance that applies the following absolute tolerances:

  • 10*eps applies a relative tolerance of 10*eps for double-precision numeric arrays.

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

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 arrays containing floating-point numbers. 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

Copy Semantics

Value. To learn how value classes affect copy operations, see Copying Objects.

Examples

collapse all

Create a test case for interactive testing.

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

testCase = TestCase.forInteractiveUse;

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

testCase.assertThat(4.1, IsEqualTo(4.5, ...
    'Within', RelativeTolerance(0.1)))
Assertion passed.

Create a test case for interactive testing.

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

testCase = TestCase.forInteractiveUse;

Create the following actual and expected cell arrays.

act = {'abc', 123, single(106)};
exp = {'abc', 122, single(105)};

Test that the arrays satisfy the RelativeTolerance constraint within 2%.

testCase.verifyThat(act, IsEqualTo(exp, ...
    '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 single:
               106
        Expected single:
               105

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

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 = RelativeTolerance(0.02, single(0.02));

A tolerance of 2% is a applied to double and single valued data.

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

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

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))
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 double:
           3.140000000000000
    Expected double:
           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))
Verification passed.

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)))
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 double:
                 1.256600000000000e-06
        Expected double:
                 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)))
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.010503    -2458.01050287485    -8.1990404935028e-06    0.0001           
        
        Actual double:
               299790000
        Expected double:
                 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)))
Verification passed.

Version History

Introduced in R2013a

See Also

|