matlab.unittest.constraints.RelativeTolerance Class
Namespace: matlab.unittest.constraints
Superclasses: matlab.unittest.constraints.Tolerance
Relative numeric tolerance
Description
The matlab.unittest.constraints.RelativeTolerance
class provides a relative
numeric tolerance for the comparison of actual
and
expected
numeric arrays. The tolerance examines the magnitude of the
difference between the arrays, relative to the expected
array. For a
relative tolerance with the value RelTol
to be satisfied,
abs(expected-actual) <= RelTol.*abs(expected)
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
and
expected
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 the
isequaln
function finds them different, then the framework delegates comparison
to the tolerance.
Creation
Description
t = matlab.unittest.constraints.RelativeTolerance(
creates a relative tolerance using the specified tolerance values. For example, value1,...,valueN
)t
= matlab.unittest.constraints.RelativeTolerance(10*eps("single"),0.1)
creates
a relative tolerance for comparing a pair of single-precision or double-precision numeric arrays:
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 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.
Input Arguments
value1,...,valueN
— Tolerance values
comma-separated list of floating-point arrays
Tolerance values, specified as a comma-separated list of floating-point arrays.
Floating-point types in MATLAB® include single
and double
(and subclasses
of single
and double
).
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
property.
Example:
0.1
Example:
[1e-2 1-e4]
Example:
10*eps("single"),1e-2
Properties
Values
— Tolerance values
cell array of floating-point arrays
Tolerance values, returned as a cell array of floating-point 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
Compare Values Using Relative Tolerance
Compare actual and expected values using the RelativeTolerance
class.
First, import the classes used in this example.
import matlab.unittest.TestCase import matlab.unittest.constraints.IsEqualTo import matlab.unittest.constraints.RelativeTolerance
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))
Verification failed. --------------------- Framework Diagnostic: --------------------- IsEqualTo failed. --> NumericComparator failed. --> The numeric values are not equal using "isequaln". --> Failure table: Actual Expected Error RelativeError ______ ________ _____ __________________ 4.1 4.5 -0.4 -0.088888888888889 Actual Value: 4.100000000000000 Expected Value: 4.500000000000000 ------------------ Stack Information: ------------------ In C:\work\CompareValuesUsingRelativeToleranceExample.m (CompareValuesUsingRelativeToleranceExample) at 16
Repeat the test, specifying a relative tolerance. Verify that the values are equal within 10%. The test passes.
testCase.verifyThat(4.1,IsEqualTo(4.5, ... "Within",RelativeTolerance(0.1)))
Verification passed.
Test if two cell arrays are equal within 2%. The test fails because the tolerance applies only to the elements of type double
.
actual = {'abc',123,single(106)}; expected = {'abc',122,single(105)}; testCase.verifyThat(actual,IsEqualTo(expected, ... "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 Value: single 106 Expected Value: single 105 Actual Value: 1×3 cell array {'abc'} {[123]} {[106]} Expected Value: 1×3 cell array {'abc'} {[122]} {[105]} ------------------ Stack Information: ------------------ In C:\work\CompareValuesUsingRelativeToleranceExample.m (CompareValuesUsingRelativeToleranceExample) at 27
Create a relative tolerance that supports different numeric types. Specify the tolerance values of 0.02
and single(0.02)
for comparing cell array elements of type double
and single
, respectively. If you compare the cell arrays using this tolerance, the test passes.
tol = RelativeTolerance(0.02,single(0.02)); testCase.verifyThat(actual,IsEqualTo(expected, ... "Within",tol))
Verification passed.
Combine Absolute and Relative Tolerances
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))
Verification passed.
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
Compare Arrays with Different Tolerances
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))
Verification passed.
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
Compare Structures That Contain Small and Large Values
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 = 4*pi*10^-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: <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 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: <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 -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)))
Verification passed.
Version History
Introduced in R2013a
Comando de MATLAB
Ha hecho clic en un enlace que corresponde a este comando de MATLAB:
Ejecute el comando introduciéndolo en la ventana de comandos de MATLAB. Los navegadores web no admiten comandos de MATLAB.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)