These functions solve the root of some function f(x)without the need for any derivatives of f(x).

The bracket_and_solve_root
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 Brent
or Dekker) 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.

These functions locate the root using bisection: function arguments are:

f

A unary functor which is the function whose root is to be found.

min

The left bracket of the interval known to contain the root.

max

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.

tol

A binary functor that specifies the termination condition: the function
will return the current brackets enclosing the root when tol(min,max)
becomes true.

max_iter

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.

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.

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:

f

A unary functor that is the function whose root is to be solved. f(x)
must be uniformly increasing or decreasing on x.

guess

An initial approximation to the root

factor

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.

rising

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.

tol

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.

max_iter

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.

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.

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:

f

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.

a

The lower bound for the initial bracket of the root.

b

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.

fa

Optional: the value of f(a).

fb

Optional: the value of f(b).

tol

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.

max_iter

The maximum number of function invocations to perform in the search
for the root. On exit max_iter is set to actual
number of function invocations used.

toms748_solve returns: a pair of values r that bracket
the root so that: f(r.first) * f(r.second) <= 0 and either tol(r.first,
r.second) == true or max_iter >= m 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
against its previous value passed as parameter), rather than because the
termination condition tol was satisfied.

eps_tolerance is the usual
termination condition used with these root finding functions. Its operator()
will return true when the relative distance between a
and b is less than twice the machine epsilon for T,
or 21-bits, whichever is the larger. In other words, you set bits
to the number of bits of precision you want in the result. The minimal tolerance
of twice the machine epsilon of T is required to ensure that we get back
a bracketing interval: since this must clearly be at least 1 epsilon in size.

This termination condition is used when you want to find an integer result
that is the closest to the true root. It will terminate
as soon as both ends of the interval round to the same nearest integer.