Accelerating the pace of engineering and science

# matlab.unittest.constraints.RelativeTolerance class

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

Relative numeric tolerance

## 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(int8(2)) constructs a RelativeTolerance 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, RelativeTolerance(10*eps, 10*eps('single'), int8(1)) 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.

• int8(1) applies a relative 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

 and Form logical element-wise conjunction of tolerances or Form 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 Relative Tolerance

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)))```
`Interactive assertion passed.`

### Specify Relative 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.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)))```
```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]
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))`
`Interactive verification passed.`

### Combine Relative and Absolute 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.`