SimTK Regression Testing

SimTK defines some utilities to facilitate the creation of regression tests for SimTK facilities. More...

Classes
class	Test
	This is the main class to support testing. More...
class	Subtest
	Internal utility class for generating test messages for subtests. More...
Functions
	Test (const std::string &name)
	~Test ()
template<class T >
static double	defTol ()
template<class T1 , class T2 >
static double	defTol2 ()
static bool	numericallyEqual (float v1, float v2, int n, double tol=defTol< float >())
static bool	numericallyEqual (double v1, double v2, int n, double tol=defTol< double >())
static bool	numericallyEqual (long double v1, long double v2, int n, double tol=defTol< long double >())
static bool	numericallyEqual (int i1, int i2, int n, double tol=0)
static bool	numericallyEqual (unsigned u1, unsigned u2, int n, double tol=0)
static bool	numericallyEqual (float v1, double v2, int n, double tol=defTol< float >())
static bool	numericallyEqual (double v1, float v2, int n, double tol=defTol< float >())
static bool	numericallyEqual (float v1, long double v2, int n, double tol=defTol< float >())
static bool	numericallyEqual (long double v1, float v2, int n, double tol=defTol< float >())
static bool	numericallyEqual (double v1, long double v2, int n, double tol=defTol< double >())
static bool	numericallyEqual (long double v1, double v2, int n, double tol=defTol< double >())
static bool	numericallyEqual (int i1, float f2, int n, double tol=defTol< float >())
static bool	numericallyEqual (float f1, int i2, int n, double tol=defTol< float >())
static bool	numericallyEqual (unsigned i1, float f2, int n, double tol=defTol< float >())
static bool	numericallyEqual (float f1, unsigned i2, int n, double tol=defTol< float >())
static bool	numericallyEqual (int i1, double f2, int n, double tol=defTol< double >())
static bool	numericallyEqual (double f1, int i2, int n, double tol=defTol< double >())
static bool	numericallyEqual (unsigned i1, double f2, int n, double tol=defTol< double >())
static bool	numericallyEqual (double f1, unsigned i2, int n, double tol=defTol< double >())
static bool	numericallyEqual (int i1, long double f2, int n, double tol=defTol< long double >())
static bool	numericallyEqual (long double f1, int i2, int n, double tol=defTol< long double >())
static bool	numericallyEqual (unsigned i1, long double f2, int n, double tol=defTol< long double >())
static bool	numericallyEqual (long double f1, unsigned i2, int n, double tol=defTol< long double >())
template<class P >
static bool	numericallyEqual (const std::complex< P > &v1, const std::complex< P > &v2, int n, double tol=defTol< P >())
template<class P >
static bool	numericallyEqual (const conjugate< P > &v1, const conjugate< P > &v2, int n, double tol=defTol< P >())
template<class P >
static bool	numericallyEqual (const std::complex< P > &v1, const conjugate< P > &v2, int n, double tol=defTol< P >())
template<class P >
static bool	numericallyEqual (const conjugate< P > &v1, const std::complex< P > &v2, int n, double tol=defTol< P >())
template<class P >
static bool	numericallyEqual (const negator< P > &v1, const negator< P > &v2, int n, double tol=defTol< P >())
template<class P >
static bool	numericallyEqual (const P &v1, const negator< P > &v2, int n, double tol=defTol< P >())
template<class P >
static bool	numericallyEqual (const negator< P > &v1, const P &v2, int n, double tol=defTol< P >())
template<class P >
static bool	numericallyEqual (const negator< std::complex< P > > &v1, const conjugate< P > &v2, int n, double tol=defTol< P >())
template<class P >
static bool	numericallyEqual (const negator< conjugate< P > > &v1, const std::complex< P > &v2, int n, double tol=defTol< P >())
template<class P >
static bool	numericallyEqual (const std::complex< P > &v1, const negator< conjugate< P > > &v2, int n, double tol=defTol< P >())
template<class P >
static bool	numericallyEqual (const conjugate< P > &v1, const negator< std::complex< P > > &v2, int n, double tol=defTol< P >())
template<int M, class E1 , int S1, class E2 , int S2>
static bool	numericallyEqual (const Vec< M, E1, S1 > &v1, const Vec< M, E2, S2 > &v2, int n, double tol=(defTol2< E1, E2 >()))
template<int N, class E1 , int S1, class E2 , int S2>
static bool	numericallyEqual (const Row< N, E1, S1 > &v1, const Row< N, E2, S2 > &v2, int n, double tol=(defTol2< E1, E2 >()))
template<int M, int N, class E1 , int CS1, int RS1, class E2 , int CS2, int RS2>
static bool	numericallyEqual (const Mat< M, N, E1, CS1, RS1 > &v1, const Mat< M, N, E2, CS2, RS2 > &v2, int n, double tol=(defTol2< E1, E2 >()))
template<int N, class E1 , int S1, class E2 , int S2>
static bool	numericallyEqual (const SymMat< N, E1, S1 > &v1, const SymMat< N, E2, S2 > &v2, int n, double tol=(defTol2< E1, E2 >()))
template<class E1 , class E2 >
static bool	numericallyEqual (const VectorView_< E1 > &v1, const VectorView_< E2 > &v2, int n, double tol=(defTol2< E1, E2 >()))
template<class E1 , class E2 >
static bool	numericallyEqual (const Vector_< E1 > &v1, const Vector_< E2 > &v2, int n, double tol=(defTol2< E1, E2 >()))
template<class E1 , class E2 >
static bool	numericallyEqual (const RowVectorView_< E1 > &v1, const RowVectorView_< E2 > &v2, int n, double tol=(defTol2< E1, E2 >()))
template<class E1 , class E2 >
static bool	numericallyEqual (const RowVector_< E1 > &v1, const RowVector_< E2 > &v2, int n, double tol=(defTol2< E1, E2 >()))
template<class E1 , class E2 >
static bool	numericallyEqual (const MatrixView_< E1 > &v1, const MatrixView_< E2 > &v2, int n, double tol=(defTol2< E1, E2 >()))
template<class E1 , class E2 >
static bool	numericallyEqual (const Matrix_< E1 > &m1, const Matrix_< E2 > &m2, int n, double tol=(defTol2< E1, E2 >()))
static bool	numericallyEqual (const Rotation &R1, const Rotation &R2, int n, double tol=defTol< Real >())
static bool	numericallyEqual (const Transform &T1, const Transform &T2, int n, double tol=defTol< Real >())
static Real	randReal ()
static Complex	randComplex ()
static Conjugate	randConjugate ()
static float	randFloat ()
static double	randDouble ()
template<int M>
static Vec< M >	randVec ()
template<int N>
static Row< N >	randRow ()
template<int M, int N>
static Mat< M, N >	randMat ()
template<int N>
static SymMat< N >	randSymMat ()
static Vector	randVector (int m)
static Matrix	randMatrix (int m, int n)
static Vec3	randVec3 ()
static Mat33	randMat33 ()
static SpatialVec	randSpatialVec ()
static SpatialMat	randSpatialMat ()
static Rotation	randRotation ()
static Transform	randTransform ()
	~Subtest ()

Detailed Description

SimTK defines some utilities to facilitate the creation of regression tests for SimTK facilities.

These utilities consist of a SimTK::Test class and related support macros.

Features include:

uniform, readable output including execution times
identical comparison tests for all numerical types, scalar and composite
careful treatment of numerical tolerances using relative and absolute comparisons, with provision for size-dependent, reduced accuracy expectations for matrix operations
default tolerance varies with precision (caller can override)
convenient generation of random test data
convenient testing of required argument checking (i.e., test fails unless an exception is thrown)

The Testing.h header file is not automatically included with SimTKcommon.h; you have to ask for it explicilty. Here's how you use this facility:

 #include "SimTKcommon/Testing.h"
 void myFirstSubtest() {...}
 void myNextSubtest() {...}
 int main() {
      SimTK_START_TEST("OverallTestName");
          SimTK_SUBTEST(myFirstSubtest);
          SimTK_SUBTEST(myNextSubtest);
      SimTK_END_TEST();
 }

The arguments to SimTK_SUBTEST are function names and will be called with "()" appended. If your subtest functions have arguments, use SimTK_SUBTEST1(name,arg) or SimTK_SUBTEST2(name,arg1,arg2) which will call name(arg) or name(arg1,arg2) as appropriate.

This will result in nice output including execution times for the overall test and the individual subtests, and arrange for any exceptions raised in the tests to be caught, properly reported, and cause a non-zero return from main(). If everything runs successfully, main() will return 0. Here is an example of the output produced:

 Starting test TestScalar ...
   testIsNaN            ... done. testIsNaN            time: 0ms.
   testIsInf            ... done. testIsInf            time: 0ms.
   testIsFinite         ... done. testIsFinite         time: 0ms.
   testSignBit          ... done. testSignBit          time: 0ms.
   testSign             ... done. testSign             time: 0ms.
   testSquareAndCube    ... done. testSquareAndCube    time: 0ms.
 Done. TestScalar time: 15ms.

(Admittedly the timings aren't much use in that example!)

Within your subtests, several useful macros and static functions are available. By using these macros, the resulting message will include the actual line number at which the test failure occurred.

      SimTK_TEST(cond)             -- this is like assert(cond)
      SimTK_TEST_FAILED("message") -- like assert(!"message")

      SimTK_TEST_EQ(a,b)           -- equal to within a default tolerance
      SimTK_TEST_NOTEQ(a,b)        -- not equal to within a default tolerance

      SimTK_TEST_EQ_SIZE(a,b,n)    -- equal to within n * default tolerance
      SimTK_TEST_NOTEQ_SIZE(a,b,n) -- not equal to within n * default tolerance

      SimTK_TEST_EQ_TOL(a,b,tol)   -- same as above with specified tolerance
      SimTK_TEST_NOTEQ_TOL(a,b,tol)

      SimTK_TEST_MUST_THROW(statement)    -- we expect the statement to throw some exception
      SimTK_TEST_MUST_THROW_EXC(statement, exception) -- we expect a particular exception type

The SimTK_TEST_EQ macros test scalar and composite numerical values for equality to within a numerical tolerance, using both relative and absolute tolerances. The default is the value of SignificantReal for the underlying numerical type. For composite types the equality test is done elementwise; that is, we apply it strictly to each pair of elements not to an overall norm.

The SimTK_TEST_EQ_SIZE macros allows you to specify a multiple of default tolerance to be used. This is necessary for most Matrix operations since attainable accuracy falls off with the size of the matrix. Typically, if the smallest dimension of the Matrix is n, then the tolerance you should allow is n*scalarTol where scalarTol is the default tolerance for a scalar operation. Note that you still need to specify size when comparing Vector or scalar values if those values were produced using a matrix computation.

The SimTK_TEST_EQ_TOL macros take a user-specified tolerance value for the elementwise tests, overriding the default.

The SimTK::Test class has a number of static methods that are useful in tests. Currently these are all for generating numerical objects filled with random numbers (all uniform between -1 and 1). These are:

      randReal()      randFloat()     randDouble()
      randComplex()   randConjugate()
      randVec<M>()    randRow<N>()    randMat<M,N>()  randSymMat<N>()
      randVector(m)   randMatrix(m,n)
      randVec3()      randMat33()
      randSpatialVec() randSpatialMat()
      randRotation()  randTransform()

These are invoked Test::randReal() etc.

Function Documentation

static double defTol ( ) [inline, static, inherited]

static double defTol2 ( ) [inline, static, inherited]

References SimTK::max().

static bool numericallyEqual	(	const Transform &	T1,
		const Transform &	T2,
		int	n,
		double	tol = `defTol<Real>()`
	)			`[inline, static, inherited]`

References Test::numericallyEqual(), Transform::p(), and Transform::R().

static bool numericallyEqual	(	const Rotation &	R1,
		const Rotation &	R2,
		int	n,
		double	tol = `defTol<Real>()`
	)			`[inline, static, inherited]`

References Rotation::isSameRotationToWithinAngle().

static bool numericallyEqual	(	const Matrix_< E1 > &	m1,
		const Matrix_< E2 > &	m2,
		int	n,
		double	tol = `(defTol2<E1,E2>())`
	)			`[inline, static, inherited]`

static bool numericallyEqual	(	const MatrixView_< E1 > &	v1,
		const MatrixView_< E2 > &	v2,
		int	n,
		double	tol = `(defTol2<E1,E2>())`
	)			`[inline, static, inherited]`

static bool numericallyEqual	(	const RowVector_< E1 > &	v1,
		const RowVector_< E2 > &	v2,
		int	n,
		double	tol = `(defTol2<E1,E2>())`
	)			`[inline, static, inherited]`

static bool numericallyEqual	(	const RowVectorView_< E1 > &	v1,
		const RowVectorView_< E2 > &	v2,
		int	n,
		double	tol = `(defTol2<E1,E2>())`
	)			`[inline, static, inherited]`

static bool numericallyEqual	(	const Vector_< E1 > &	v1,
		const Vector_< E2 > &	v2,
		int	n,
		double	tol = `(defTol2<E1,E2>())`
	)			`[inline, static, inherited]`

static bool numericallyEqual	(	const VectorView_< E1 > &	v1,
		const VectorView_< E2 > &	v2,
		int	n,
		double	tol = `(defTol2<E1,E2>())`
	)			`[inline, static, inherited]`

static bool numericallyEqual	(	const SymMat< N, E1, S1 > &	v1,
		const SymMat< N, E2, S2 > &	v2,
		int	n,
		double	tol = `(defTol2<E1,E2>())`
	)			`[inline, static, inherited]`

static bool numericallyEqual	(	const Mat< M, N, E1, CS1, RS1 > &	v1,
		const Mat< M, N, E2, CS2, RS2 > &	v2,
		int	n,
		double	tol = `(defTol2<E1,E2>())`
	)			`[inline, static, inherited]`

static bool numericallyEqual	(	const Row< N, E1, S1 > &	v1,
		const Row< N, E2, S2 > &	v2,
		int	n,
		double	tol = `(defTol2<E1,E2>())`
	)			`[inline, static, inherited]`

static bool numericallyEqual	(	const Vec< M, E1, S1 > &	v1,
		const Vec< M, E2, S2 > &	v2,
		int	n,
		double	tol = `(defTol2<E1,E2>())`
	)			`[inline, static, inherited]`

static bool numericallyEqual	(	const conjugate< P > &	v1,
		const negator< std::complex< P > > &	v2,
		int	n,
		double	tol = `defTol<P>()`
	)			`[inline, static, inherited]`

static bool numericallyEqual	(	const std::complex< P > &	v1,
		const negator< conjugate< P > > &	v2,
		int	n,
		double	tol = `defTol<P>()`
	)			`[inline, static, inherited]`

static bool numericallyEqual	(	const negator< P > &	v1,
		const P &	v2,
		int	n,
		double	tol = `defTol<P>()`
	)			`[inline, static, inherited]`

static bool numericallyEqual	(	long double	f1,
		unsigned	i2,
		int	n,
		double	tol = `defTol<long double>()`
	)			`[inline, static, inherited]`

static bool numericallyEqual	(	float	f1,
		unsigned	i2,
		int	n,
		double	tol = `defTol<float>()`
	)			`[inline, static, inherited]`

static bool numericallyEqual	(	int	i1,
		int	i2,
		int	n,
		double	tol = `0`
	)			`[inline, static, inherited]`

static Matrix randMatrix	(	int	m,
		int	n
	)			`[inline, static, inherited]`

SimTK Regression Testing

Classes

Functions

Detailed Description

Function Documentation