1[section:error_test Relative Error and Testing] 2 3[h4 Synopsis] 4 5`` 6#include <boost/math/tools/test.hpp> 7`` 8 9[important 10The header `boost/math/tools/test.hpp` is located under `libs/math/include_private` 11and is NOT installed to the usual locations by default; you will need to add `libs/math/include_private` 12to your compiler's include path in order to use this header.] 13 14 template <class T> 15 T relative_error(T a, T b); 16 17 template <class A, class F1, class F2> 18 test_result<see-below> test(const A& a, F1 test_func, F2 expect_func); 19 20[h4 Description] 21 22 template <class T> 23 T relative_error(T a, T v); 24 25Returns the relative error between /a/ and /v/ using the usual formula: 26 27[equation error1] 28 29In addition the value returned is zero if: 30 31* Both /a/ and /v/ are infinite. 32* Both /a/ and /v/ are denormalised numbers or zero. 33 34Otherwise if only one of /a/ and /v/ is zero then the value returned is 1. 35 36 template <class A, class F1, class F2> 37 test_result<see-below> test(const A& a, F1 test_func, F2 expect_func); 38 39This function is used for testing a function against tabulated test data. 40 41The return type contains statistical data on the relative errors (max, mean, 42variance, and the number of test cases etc), as well as the row of test data that 43caused the largest relative error. Public members of type test_result are: 44 45[variablelist 46[[`unsigned worst()const;`][Returns the row at which the worst error occurred.]] 47[[`T min()const;`][Returns the smallest relative error found.]] 48[[`T max()const;`][Returns the largest relative error found.]] 49[[`T mean()const;`][Returns the mean error found.]] 50[[`boost::uintmax_t count()const;`][Returns the number of test cases.]] 51[[`T variance()const;`][Returns the variance of the errors found.]] 52[[`T variance1()const;`][Returns the unbiased variance of the errors found.]] 53[[`T rms()const`][Returns the Root Mean Square, or quadratic mean of the errors.]] 54[[`test_result& operator+=(const test_result& t)`][Combines two test_result's into 55a single result.]] 56] 57 58The template parameter of test_result, is the same type as the values in the two 59dimensional array passed to function /test/, roughly that's 60`A::value_type::value_type`. 61 62Parameter /a/ is a matrix of test data: and must be a standard library Sequence type, 63that contains another Sequence type: 64typically it will be a two dimensional instance of 65[^boost::array]. Each row 66of /a/ should contain all the parameters that are passed to the function 67under test as well as the expected result. 68 69Parameter /test_func/ is the function under test, it is invoked with each row 70of test data in /a/. Typically type F1 is created with Boost.Lambda: see 71the example below. 72 73Parameter /expect_func/ is a functor that extracts the expected result 74from a row of test data in /a/. Typically type F2 is created with Boost.Lambda: see 75the example below. 76 77If the function under test returns a non-finite value when a finite result is 78expected, or if a gross error is found, then a message is sent to `std::cerr`, 79and a call to BOOST_ERROR() made (which means that including this header requires 80you use Boost.Test). This is mainly a debugging/development aid 81(and a good place for a breakpoint). 82 83[h4 Example] 84 85Suppose we want to test the `tgamma` and `lgamma` functions, we can create a 86two-dimensional matrix of test data, each row is one test case, and contains 87three elements: the input value, and the expected results for the `tgamma` and 88`lgamma` functions respectively. 89 90 static const boost::array<boost::array<TestType, 3>, NumberOfTests> 91 factorials = { 92 /* big array of test data goes here */ 93 }; 94 95Now we can invoke the test function to test tgamma: 96 97 using namespace boost::math::tools; 98 using namespace boost::lambda; 99 100 // get a pointer to the function under test: 101 TestType (*funcp)(TestType) = boost::math::tgamma; 102 103 // declare something to hold the result: 104 test_result<TestType> result; 105 // 106 // and test tgamma against data: 107 // 108 result = test( 109 factorials, 110 bind(funcp, ret<TestType>(_1[0])), // calls tgamma with factorials[row][0] 111 ret<TestType>(_1[1]) // extracts the expected result from factorials[row][1] 112 ); 113 // 114 // Print out some results: 115 // 116 std::cout << "The Mean was " << result.mean() << std::endl; 117 std::cout << "The worst error was " << (result.max)() << std::endl; 118 std::cout << "The worst error was at row " << result.worst_case() << std::endl; 119 // 120 // same again with lgamma this time: 121 // 122 funcp = boost::math::lgamma; 123 result = test( 124 factorials, 125 bind(funcp, ret<TestType>(_1[0])), // calls tgamma with factorials[row][0] 126 ret<TestType>(_1[2]) // extracts the expected result from factorials[row][2] 127 ); 128 // 129 // etc ... 130 // 131 132[endsect] [/section:error_test Relative Error and Testing] 133 134[/ 135 Copyright 2006 John Maddock and Paul A. Bristow. 136 Distributed under the Boost Software License, Version 1.0. 137 (See accompanying file LICENSE_1_0.txt or copy at 138 http://www.boost.org/LICENSE_1_0.txt). 139] 140