gmx::test::FloatingPointTolerance Class Reference

#include <testutils/testasserts.h>

Description

Specifies a floating-point comparison tolerance and checks whether a difference is within the tolerance.

The related functions section lists methods that can be construct methods using less parameters than the full constructor, and with more obvious semantics. These should be preferred over using the constructor directly.

Several types of tolerances are possible:

• absolute tolerance: difference between the values must be smaller than the given tolerance for the check to pass. Setting the absolute tolerance to zero disables the absolute tolerance check.
• relative tolerance: the absolute difference between the numbers must be smaller than the tolerance multiplied by the first number. Setting the relative tolerance to zero disables this check.
• ULP tolerance: ULP (units of least precision) difference between the values must be smaller than the given tolerance for the check to pass. Setting the ULP tolerance to zero requires exact match. Setting the ULP tolerance to UINT64_MAX disables the ULP check. 0.0 and -0.0 are treated as equal for the ULP check.
• sign check: if set, any values that are of different signs fail the check (note that this also applies to 0.0 and -0.0: a value with a different sign than the zero will fail the check).

Either an absolute, relative, or ULP tolerance must always be specified. If several of them are specified, then the check passes if either of the tolerances is satisfied.

Any combination of absolute, relative, and ULP tolerance can be combined with the sign check. In this case, the sign check must succeed for the check to pass, even if other tolerances are satisfied.

The tolerances can be specified separately for single and double precision comparison. Different initialization functions have different semantics on how the provided tolerance values are interpreted; check their documentation.

Methods in this class do not throw, except for toString(), which may throw std::bad_alloc.

Todo:

The factory methods that take ULP difference could be better formulated as methods that take the acceptable number of incorrect bits and/or the number of accurate bits.

See Also

FloatingPointDifference

Public Member Functions
	FloatingPointTolerance (float singleAbsoluteTolerance, double doubleAbsoluteTolerance, float singleRelativeTolerance, double doubleRelativeTolerance, uint64_t singleUlpTolerance, uint64_t doubleUlpTolerance, bool bSignMustMatch)
	Creates a tolerance with the specified values. More...
bool	isWithin (const FloatingPointDifference &difference) const
	Checks whether a difference is within the specified tolerance. More...
std::string	toString (const FloatingPointDifference &difference) const
	Formats the tolerance as a string for assertion failure messages.

Related Functions
(Note that these are not member functions.)
static FloatingPointTolerance	ulpTolerance (uint64_t ulpDiff)
	Creates a tolerance that only allows a specified ULP difference. More...
FloatingPointTolerance	relativeToleranceAsFloatingPoint (double magnitude, double tolerance)
	Creates a tolerance that allows a difference in two compared values that is relative to the given magnitude. More...
FloatingPointTolerance	relativeToleranceAsPrecisionDependentFloatingPoint (double magnitude, float singleTolerance, double doubleTolerance)
	Creates a tolerance that allows a precision-dependent difference in two compared values that is relative to the given magnitude. More...
static FloatingPointTolerance	relativeToleranceAsPrecisionDependentUlp (double magnitude, uint64_t singleUlpDiff, uint64_t doubleUlpDiff)
	Creates a tolerance that allows a precision-dependent relative difference in a complex computation. More...
static FloatingPointTolerance	absoluteTolerance (double tolerance)
	Creates a tolerance that allows a specified absolute difference.
static FloatingPointTolerance	relativeToleranceAsUlp (double magnitude, uint64_t ulpDiff)
	Creates a tolerance that allows a relative difference in a complex computation. More...
static FloatingPointTolerance	defaultRealTolerance ()
	Returns the default tolerance for comparing real numbers.
static FloatingPointTolerance	defaultFloatTolerance ()
	Returns the default tolerance for comparing single-precision numbers when compared by GROMACS built in either precision mode. More...

Constructor & Destructor Documentation

gmx::test::FloatingPointTolerance::FloatingPointTolerance ( float  singleAbsoluteTolerance, double  doubleAbsoluteTolerance, float  singleRelativeTolerance, double  doubleRelativeTolerance, uint64_t  singleUlpTolerance, uint64_t  doubleUlpTolerance, bool  bSignMustMatch  )

inline

Creates a tolerance with the specified values.

Parameters

[in]	singleAbsoluteTolerance	Allowed absolute difference in a single-precision number.
[in]	doubleAbsoluteTolerance	Allowed absolute difference in a double-precision number.
[in]	singleRelativeTolerance	Allowed relative difference in a single-precision number.
[in]	doubleRelativeTolerance	Allowed relative difference in a double-precision number.
[in]	singleUlpTolerance	Allowed ULP difference in a single-precision number.
[in]	doubleUlpTolerance	Allowed ULP difference in a double-precision number.
[in]	bSignMustMatch	Whether sign mismatch fails the comparison.

Member Function Documentation

bool gmx::test::FloatingPointTolerance::isWithin

(

const FloatingPointDifference &

difference

)

const

Checks whether a difference is within the specified tolerance.

NaNs are always treated outside the tolerance.

---

The documentation for this class was generated from the following files:

• src/testutils/testasserts.h
• src/testutils/testasserts.cpp