Documentation Center

  • Trial Software
  • Product Updates

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 determine the data types to which the tolerance is applied. 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.

Different tolerance values can be specified for different data types by passing multiple tolerance values to the constructor. For example, AbsoluteTolerance(10*eps, 10*eps('single'), int8(1)) constructs an AbsoluteTolerance that would apply 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 cell array of numeric arrays. Each input argument contains the tolerance specification for a particular data type. Each numeric array can be a scalar or array with the same number of dimensions 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 and 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.
    
    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 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 value was not within absolute tolerance.
                
                Tolerance Value:
                         1.000000000000000e-03
        --> RelativeTolerance passed.

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

Typically when testing 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 value was not within relative tolerance.
            
            Tolerance Value:
                     2.220446049250313e-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 isn't 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 value was not within absolute tolerance.
            
            Tolerance Value:
                     1.000000000000000e-04
    
    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. This tolerance is used so permeability values, which are close to zero, satisfy the absolute (floor) tolerance, and speed of light values, which are large, satisfy the relative tolerance.

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

See Also

|

Was this topic helpful?