| Home | Libraries | People | FAQ | More

#### Relative Error and Testing

##### Synopsis

    #include <boost/math/tools/test.hpp>

    template <class T>
    T relative_error(T a, T b);

    template <class A, class F1, class F2>
    test_result<see-below> test(const A& a, F1 test_func, F2 expect_func);

##### Description

    template <class T>
    T relative_error(T a, T v);

Returns the relative error between a and v using the usual formula:

In addition the value returned is zero if:

- Both a and v are infinite.
- Both a and v are denormalised numbers or zero.

Otherwise if only one of a and v is zero then the value returned is 1.

    template <class A, class F1, class F2>
    test_result<see-below> test(const A& a, F1 test_func, F2 expect_func);

This function is used for testing a function against tabulated test data.

The return type contains statistical data on the relative errors (max, mean, variance, and the number of test cases etc), as well as the row of test data that caused the largest relative error. Public members of type test_result are:

`unsigned worst()const;`

  Returns the row at which the worst error occurred.

`T min()const;`

  Returns the smallest relative error found.

`T max()const;`

  Returns the largest relative error found.

`T mean()const;`

  Returns the mean error found.

`boost::uintmax_t count()const;`

  Returns the number of test cases.

`T variance()const;`

  Returns the variance of the errors found.

`T variance1()const;`

  Returns the unbiased variance of the errors found.

`T rms()const`

  Returns the Root Mean Square, or quadratic mean of the errors.

`test_result& operator+=(const test_result& t)`

  Combines two test_result's into a single result.

The template parameter of test_result, is the same type as the values in the two dimensional array passed to function test, roughly that's `A::value_type::value_type`.

Parameter a is a matrix of test data: and must be a standard library Sequence type, that contains another Sequence type: typically it will be a two dimensional instance of `boost::array`. Each row of a should contain all the parameters that are passed to the function under test as well as the expected result.

Parameter test_func is the function under test, it is invoked with each row of test data in a. Typically type F1 is created with Boost.Lambda: see the example below.

Parameter expect_func is a functor that extracts the expected result from a row of test data in a. Typically type F2 is created with Boost.Lambda: see the example below.

If the function under test returns a non-finite value when a finite result is expected, or if a gross error is found, then a message is sent to `std::cerr`, and a call to BOOST_ERROR() made (which means that including this header requires you use Boost.Test). This is mainly a debugging/development aid (and a good place for a breakpoint).

##### Example

Suppose we want to test the tgamma and lgamma functions, we can create a two dimensional matrix of test data, each row is one test case, and contains three elements: the input value, and the expected results for the tgamma and lgamma functions respectively.

    static const boost::array<boost::array<TestType, 3>, NumberOfTests>
       factorials = {
          /* big array of test data goes here */
       };

Now we can invoke the test function to test tgamma:

    using namespace boost::math::tools;
    using namespace boost::lambda;

    // get a pointer to the function under test:
    TestType (*funcp)(TestType) = boost::math::tgamma;

    // declare something to hold the result:
    test_result<TestType> result;
    //
    // and test tgamma against data:
    //
    result = test(
       factorials,
       bind(funcp, ret<TestType>(_1[0])), // calls tgamma with factorials[row][0]
       ret<TestType>(_1[1])               // extracts the expected result from factorials[row][1]
    );
    //
    // Print out some results:
    //
    std::cout << "The Mean was " << result.mean() << std::endl;
    std::cout << "The worst error was " << (result.max)() << std::endl;
    std::cout << "The worst error was at row " << result.worst_case() << std::endl;
    //
    // same again with lgamma this time:
    //
    funcp = boost::math::lgamma;
    result = test(
       factorials,
       bind(funcp, ret<TestType>(_1[0])), // calls tgamma with factorials[row][0]
       ret<TestType>(_1[2])               // extracts the expected result from factorials[row][2]
    );
    //
    // etc ...
    //