boost-react-native-bundle

<html> <head> <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> <title>Root Finding Without Derivatives: Bisection, Bracket and TOMS748</title> <link rel="stylesheet" href="../../math.css" type="text/css"> <meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> <link rel="home" href="../../index.html" title="Math Toolkit 2.1.0"> <link rel="up" href="../internals1.html" title="Utilities & internals"> <link rel="prev" href="roots.html" title="Root Finding With Derivatives: Newton-Raphson, Halley & Schroeder"> <link rel="next" href="minima.html" title="Locating Function Minima: Brent's algorithm"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> <table cellpadding="2" width="100%"><tr> <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td> <td align="center"><a href="../../../../../../index.html">Home</a></td> <td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td> <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> <td align="center"><a href="../../../../../../more/index.htm">More</a></td> </tr></table> <hr> <div class="spirit-nav"> <a accesskey="p" href="roots.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../internals1.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="minima.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> <a name="math_toolkit.internals1.roots2"></a><a class="link" href="roots2.html" title="Root Finding Without Derivatives: Bisection, Bracket and TOMS748">Root Finding Without Derivatives: Bisection, Bracket and TOMS748</a> </h3></div></div></div> <h5> <a name="math_toolkit.internals1.roots2.h0"></a> <a name="math_toolkit.internals1.roots2.synopsis"></a><a class="link" href="roots2.html#math_toolkit.internals1.roots2.synopsis">Synopsis</a> </h5> <pre class="programlisting">#include <boost/math/tools/roots.hpp> </pre> <pre class="programlisting">namespace boost{ namespace math{ namespace tools{ // Bisection template <class F, class T, class Tol> std::pair<T, T> bisect( F f, T min, T max, Tol tol, boost::uintmax_t& max_iter); template <class F, class T, class Tol> std::pair<T, T> bisect( F f, T min, T max, Tol tol); template <class F, class T, class Tol, class <a class="link" href="../../policy.html" title="Chapter 14. Policies: Controlling Precision, Error Handling etc">Policy</a>> std::pair<T, T> bisect( F f, T min, T max, Tol tol, boost::uintmax_t& max_iter, const <a class="link" href="../../policy.html" title="Chapter 14. Policies: Controlling Precision, Error Handling etc">Policy</a>&); // Bracket and Solve Root template <class F, class T, class Tol> std::pair<T, T> bracket_and_solve_root( F f, const T& guess, const T& factor, bool rising, Tol tol, boost::uintmax_t& max_iter); template <class F, class T, class Tol, class <a class="link" href="../../policy.html" title="Chapter 14. Policies: Controlling Precision, Error Handling etc">Policy</a>> std::pair<T, T> bracket_and_solve_root( F f, const T& guess, const T& factor, bool rising, Tol tol, boost::uintmax_t& max_iter, const <a class="link" href="../../policy.html" title="Chapter 14. Policies: Controlling Precision, Error Handling etc">Policy</a>&); // TOMS 748 algorithm template <class F, class T, class Tol> std::pair<T, T> toms748_solve( F f, const T& a, const T& b, Tol tol, boost::uintmax_t& max_iter); template <class F, class T, class Tol, class <a class="link" href="../../policy.html" title="Chapter 14. Policies: Controlling Precision, Error Handling etc">Policy</a>> std::pair<T, T> toms748_solve( F f, const T& a, const T& b, Tol tol, boost::uintmax_t& max_iter, const <a class="link" href="../../policy.html" title="Chapter 14. Policies: Controlling Precision, Error Handling etc">Policy</a>&); template <class F, class T, class Tol> std::pair<T, T> toms748_solve( F f, const T& a, const T& b, const T& fa, const T& fb, Tol tol, boost::uintmax_t& max_iter); template <class F, class T, class Tol, class <a class="link" href="../../policy.html" title="Chapter 14. Policies: Controlling Precision, Error Handling etc">Policy</a>> std::pair<T, T> toms748_solve( F f, const T& a, const T& b, const T& fa, const T& fb, Tol tol, boost::uintmax_t& max_iter, const <a class="link" href="../../policy.html" title="Chapter 14. Policies: Controlling Precision, Error Handling etc">Policy</a>&); // Termination conditions: template <class T> struct eps_tolerance; struct equal_floor; struct equal_ceil; struct equal_nearest_integer; }}} // namespaces </pre> <h5> <a name="math_toolkit.internals1.roots2.h1"></a> <a name="math_toolkit.internals1.roots2.description"></a><a class="link" href="roots2.html#math_toolkit.internals1.roots2.description">Description</a> </h5> These functions solve the root of some function f(x) without the need for any derivatives of f(x). The <code class="computeroutput">bracket_and_solve_root</code> functions use TOMS Algorithm 748 that is asymptotically the most efficient known, and have been shown to be optimal for a certain classes of smooth functions. Variants with and without __policies are provided. Alternatively, there is a simple bisection routine which can be useful in its own right in some situations, or alternatively for narrowing down the range containing the root, prior to calling a more advanced algorithm. All the algorithms in this section reduce the diameter of the enclosing interval with the same asymptotic efficiency with which they locate the root. This is in contrast to the derivative based methods which may never significantly reduce the enclosing interval, even though they rapidly approach the root. This is also in contrast to some other derivative-free methods (for example the methods of <a href="http://en.wikipedia.org/wiki/Brent%27s_method" target="_top">Brent or Dekker)</a> which only reduce the enclosing interval on the final step. Therefore these methods return a std::pair containing the enclosing interval found, and accept a function object specifying the termination condition. Three function objects are provided for ready-made termination conditions: eps_tolerance causes termination when the relative error in the enclosing interval is below a certain threshold, while equal_floor and equal_ceil are useful for certain statistical applications where the result is known to be an integer. Other user-defined termination conditions are likely to be used only rarely, but may be useful in some specific circumstances. <h4> <a name="math_toolkit.internals1.roots2.h2"></a> <a name="math_toolkit.internals1.roots2.bisection"></a><a class="link" href="roots2.html#math_toolkit.internals1.roots2.bisection">Bisection</a> </h4> <pre class="programlisting">template <class F, class T, class Tol> std::pair<T, T> bisect( F f, T min, T max, Tol tol, boost::uintmax_t& max_iter); template <class F, class T, class Tol> std::pair<T, T> bisect( F f, T min, T max, Tol tol); template <class F, class T, class Tol, class <a class="link" href="../../policy.html" title="Chapter 14. Policies: Controlling Precision, Error Handling etc">Policy</a>> std::pair<T, T> bisect( F f, T min, T max, Tol tol, boost::uintmax_t& max_iter, const <a class="link" href="../../policy.html" title="Chapter 14. Policies: Controlling Precision, Error Handling etc">Policy</a>&); </pre> These functions locate the root using bisection: function arguments are: <div class="variablelist"> <dl class="variablelist"> <dt>f</dt> <dd> A unary functor which is the function whose root is to be found. </dd> <dt>min</dt> <dd> The left bracket of the interval known to contain the root. </dd> <dt>max</dt> <dd> The right bracket of the interval known to contain the root. It is a precondition that min < max and f(min)*f(max) <= 0, the function signals evaluation error if these preconditions are violated. The action taken is controlled by the evaluation error policy. A best guess may be returned, perhaps significantly wrong. </dd> <dt>tol</dt> <dd> A binary functor that specifies the termination condition: the function will return the current brackets enclosing the root when tol(min,max) becomes true. </dd> <dt>max_iter</dt> <dd> The maximum number of invocations of f(x) to make while searching for the root. On exist this is set to actual number of invocations performed. </dd> </dl> </div> The final <a class="link" href="../../policy.html" title="Chapter 14. Policies: Controlling Precision, Error Handling etc">Policy</a> argument is optional and can be used to control the behaviour of the function: how it handles errors, what level of precision to use etc. Refer to the <a class="link" href="../../policy.html" title="Chapter 14. Policies: Controlling Precision, Error Handling etc">policy documentation for more details</a>. Returns: a pair of values r that bracket the root so that: <pre class="programlisting">f(r.first) * f(r.second) <= 0 </pre> and either <pre class="programlisting">tol(r.first, r.second) == true </pre> or <pre class="programlisting">max_iter >= m </pre> where m is the initial value of max_iter passed to the function. In other words, it's up to the caller to verify whether termination occurred as a result of exceeding max_iter function invocations (easily done by checking the updated value of max_iter when the function returns), rather than because the termination condition tol was satisfied. <h4> <a name="math_toolkit.internals1.roots2.h3"></a> <a name="math_toolkit.internals1.roots2.bracket_and_solve"></a><a class="link" href="roots2.html#math_toolkit.internals1.roots2.bracket_and_solve">Bracket and solve</a> </h4> <pre class="programlisting">template <class F, class T, class Tol> std::pair<T, T> bracket_and_solve_root( F f, const T& guess, const T& factor, bool rising, Tol tol, boost::uintmax_t& max_iter); template <class F, class T, class Tol, class <a class="link" href="../../policy.html" title="Chapter 14. Policies: Controlling Precision, Error Handling etc">Policy</a>> std::pair<T, T> bracket_and_solve_root( F f, const T& guess, const T& factor, bool rising, Tol tol, boost::uintmax_t& max_iter, const <a class="link" href="../../policy.html" title="Chapter 14. Policies: Controlling Precision, Error Handling etc">Policy</a>&); </pre> This is a convenience function that calls toms748_solve internally to find the root of f(x). It's usable only when f(x) is a monotonic function, and the location of the root is known approximately, and in particular it is known whether the root is occurs for positive or negative x. The parameters are: <div class="variablelist"> <dl class="variablelist"> <dt>f</dt> <dd> A unary functor that is the function whose root is to be solved. f(x) must be uniformly increasing or decreasing on x. </dd> <dt>guess</dt> <dd> An initial approximation to the root </dd> <dt>factor</dt> <dd> A scaling factor that is used to bracket the root: the value guess is multiplied (or divided as appropriate) by factor until two values are found that bracket the root. A value such as 2 is a typical choice for factor. </dd> <dt>rising</dt> <dd> Set to true if f(x) is rising on x and false if f(x) is falling on x. This value is used along with the result of f(guess) to determine if guess is above or below the root. </dd> <dt>tol</dt> <dd> A binary functor that determines the termination condition for the search for the root. tol is passed the current brackets at each step, when it returns true then the current brackets are returned as the result. </dd> <dt>max_iter</dt> <dd> The maximum number of function invocations to perform in the search for the root. On exit is set to the actual number of invocations performed. </dd> </dl> </div> The final <a class="link" href="../../policy.html" title="Chapter 14. Policies: Controlling Precision, Error Handling etc">Policy</a> argument is optional and can be used to control the behaviour of the function: how it handles errors, what level of precision to use etc. Refer to the <a class="link" href="../../policy.html" title="Chapter 14. Policies: Controlling Precision, Error Handling etc">policy documentation for more details</a>. Returns: a pair of values r that bracket the root so that: <pre class="programlisting">f(r.first) * f(r.second) <= 0 </pre> and either <pre class="programlisting">tol(r.first, r.second) == true </pre> or <pre class="programlisting">max_iter >= m </pre> where m is the initial value of max_iter passed to the function. In other words, it's up to the caller to verify whether termination occurred as a result of exceeding max_iter function invocations (easily done by checking the value of max_iter when the function returns), rather than because the termination condition tol was satisfied. <h4> <a name="math_toolkit.internals1.roots2.h4"></a> <a name="math_toolkit.internals1.roots2.algorithm_toms_748_alefeld_potra"></a><a class="link" href="roots2.html#math_toolkit.internals1.roots2.algorithm_toms_748_alefeld_potra">Algorithm TOMS 748: Alefeld, Potra and Shi: Enclosing zeros of continuous functions</a> </h4> <pre class="programlisting">template <class F, class T, class Tol> std::pair<T, T> toms748_solve( F f, const T& a, const T& b, Tol tol, boost::uintmax_t& max_iter); template <class F, class T, class Tol, class <a class="link" href="../../policy.html" title="Chapter 14. Policies: Controlling Precision, Error Handling etc">Policy</a>> std::pair<T, T> toms748_solve( F f, const T& a, const T& b, Tol tol, boost::uintmax_t& max_iter, const <a class="link" href="../../policy.html" title="Chapter 14. Policies: Controlling Precision, Error Handling etc">Policy</a>&); template <class F, class T, class Tol> std::pair<T, T> toms748_solve( F f, const T& a, const T& b, const T& fa, const T& fb, Tol tol, boost::uintmax_t& max_iter); template <class F, class T, class Tol, class <a class="link" href="../../policy.html" title="Chapter 14. Policies: Controlling Precision, Error Handling etc">Policy</a>> std::pair<T, T> toms748_solve( F f, const T& a, const T& b, const T& fa, const T& fb, Tol tol, boost::uintmax_t& max_iter, const <a class="link" href="../../policy.html" title="Chapter 14. Policies: Controlling Precision, Error Handling etc">Policy</a>&); </pre> These two functions implement TOMS Algorithm 748: it uses a mixture of cubic, quadratic and linear (secant) interpolation to locate the root of f(x). The two functions differ only by whether values for f(a) and f(b) are already available. The toms748_solve parameters are: <div class="variablelist"> <dl class="variablelist"> <dt>f</dt> <dd> A unary functor that is the function whose root is to be solved. f(x) need not be uniformly increasing or decreasing on x and may have multiple roots. </dd> <dt>a</dt> <dd> The lower bound for the initial bracket of the root. </dd> <dt>b</dt> <dd> The upper bound for the initial bracket of the root. It is a precondition that a < b and that a and b bracket the root to find so that f(a)*f(b) < 0. </dd> <dt>fa</dt> <dd> Optional: the value of f(a). </dd> <dt>fb</dt> <dd> Optional: the value of f(b). </dd> <dt>tol</dt> <dd> A binary functor that determines the termination condition for the search for the root. tol is passed the c