]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 | |
10 | The header `boost/math/tools/test.hpp` is located under `libs/math/include_private` | |
11 | and is not installed to the usual locations by default, you will need to add `libs/math/include_private` | |
12 | to 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 | ||
25 | Returns the relative error between /a/ and /v/ using the usual formula: | |
26 | ||
27 | [equation error1] | |
28 | ||
29 | In 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 | ||
34 | Otherwise 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 | ||
39 | This function is used for testing a function against tabulated test data. | |
40 | ||
41 | The return type contains statistical data on the relative errors (max, mean, | |
42 | variance, and the number of test cases etc), as well as the row of test data that | |
43 | caused 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 | |
55 | a single result.]] | |
56 | ] | |
57 | ||
58 | The template parameter of test_result, is the same type as the values in the two | |
59 | dimensional array passed to function /test/, roughly that's | |
60 | `A::value_type::value_type`. | |
61 | ||
62 | Parameter /a/ is a matrix of test data: and must be a standard library Sequence type, | |
63 | that contains another Sequence type: | |
64 | typically it will be a two dimensional instance of | |
65 | [^boost::array]. Each row | |
66 | of /a/ should contain all the parameters that are passed to the function | |
67 | under test as well as the expected result. | |
68 | ||
69 | Parameter /test_func/ is the function under test, it is invoked with each row | |
70 | of test data in /a/. Typically type F1 is created with Boost.Lambda: see | |
71 | the example below. | |
72 | ||
73 | Parameter /expect_func/ is a functor that extracts the expected result | |
74 | from a row of test data in /a/. Typically type F2 is created with Boost.Lambda: see | |
75 | the example below. | |
76 | ||
77 | If the function under test returns a non-finite value when a finite result is | |
78 | expected, or if a gross error is found, then a message is sent to `std::cerr`, | |
79 | and a call to BOOST_ERROR() made (which means that including this header requires | |
80 | you use Boost.Test). This is mainly a debugging/development aid | |
81 | (and a good place for a breakpoint). | |
82 | ||
83 | [h4 Example] | |
84 | ||
85 | Suppose we want to test the tgamma and lgamma functions, we can create a | |
86 | two dimensional matrix of test data, each row is one test case, and contains | |
87 | three 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 | ||
95 | Now 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 | ] |