generic-library/boost
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

[DEV] add v1.76.0

Browse Source
This commit is contained in:
Edouard DUPIN
2021-10-05 21:37:46 +02:00
parent a97e9ae7d4
commit d0115b733d
45133 changed files with 4744437 additions and 1026325 deletions
Download Patch File Download Diff File Expand all files Collapse all files

134
libs/math/doc/html/math_toolkit/roots_deriv.html
View File

@@ -1,11 +1,11 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Root Finding With Derivatives: Newton-Raphson, Halley &amp; Schr&#246;der</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Root Finding With Derivatives: Newton-Raphson, Halley &amp; Schröder</title>
<link rel="stylesheet" href="../math.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../index.html" title="Math Toolkit 2.6.0">
<link rel="up" href="../root_finding.html" title="Chapter&#160;8.&#160;Root Finding &amp; Minimization Algorithms">
<link rel="home" href="../index.html" title="Math Toolkit 3.0.0">
<link rel="up" href="../root_finding.html" title="Chapter 10. Root Finding &amp; Minimization Algorithms">
<link rel="prev" href="roots_noderiv/implementation.html" title="Implementation">
<link rel="next" href="root_finding_examples.html" title="Examples of Root-Finding (with and without derivatives)">
</head>
@@ -24,8 +24,8 @@
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="math_toolkit.roots_deriv"></a><a class="link" href="roots_deriv.html" title="Root Finding With Derivatives: Newton-Raphson, Halley &amp; Schr&#246;der">Root Finding With Derivatives:
Newton-Raphson, Halley &amp; Schr&#246;der</a>
<a name="math_toolkit.roots_deriv"></a><a class="link" href="roots_deriv.html" title="Root Finding With Derivatives: Newton-Raphson, Halley &amp; Schröder">Root Finding With Derivatives:
Newton-Raphson, Halley &amp; Schröder</a>
</h2></div></div></div>
<h5>
<a name="math_toolkit.roots_deriv.h0"></a>
@@ -56,6 +56,12 @@
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
<span class="identifier">T</span> <span class="identifier">schroder_iterate</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">guess</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">min</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">max</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">digits</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">uintmax_t</span><span class="special">&amp;</span> <span class="identifier">max_iter</span><span class="special">);</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Complex</span><span class="special">&gt;</span>
<span class="identifier">Complex</span> <span class="identifier">complex_newton</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">Complex</span> <span class="identifier">guess</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">max_iterations</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Complex</span><span class="special">::</span><span class="identifier">value_type</span><span class="special">&gt;::</span><span class="identifier">digits</span><span class="special">);</span>
<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
<span class="keyword">auto</span> <span class="identifier">quadratic_roots</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span> <span class="special">&amp;</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T</span> <span class="keyword">const</span> <span class="special">&amp;</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T</span> <span class="keyword">const</span> <span class="special">&amp;</span> <span class="identifier">c</span><span class="special">);</span>
<span class="special">}}}</span> <span class="comment">// namespaces boost::math::tools.</span>
</pre>
<h5>
@@ -74,20 +80,26 @@
</li>
<li class="listitem">
<code class="computeroutput"><span class="identifier">halley_iterate</span></code> and <code class="computeroutput"><span class="identifier">schroder_iterate</span></code> perform third-order
<a class="link" href="roots_deriv.html#math_toolkit.roots_deriv.halley">Halley</a> and <a class="link" href="roots_deriv.html#math_toolkit.roots_deriv.schroder">Schr&#246;der</a> iteration.
<a class="link" href="roots_deriv.html#math_toolkit.roots_deriv.halley">Halley</a> and <a class="link" href="roots_deriv.html#math_toolkit.roots_deriv.schroder">Schröder</a> iteration.
</li>
<li class="listitem">
<code class="computeroutput"><span class="identifier">complex_newton</span></code> performs
Newton's method on complex-analytic functions.
</li>
<li class="listitem">
<code class="computeroutput"><span class="identifier">solve_quadratic</span></code> solves
quadratic equations using various tricks to keep catastrophic cancellation
from occurring in computation of the discriminant.
</li>
</ul></div>
<p>
The functions all take the same parameters:
</p>
<div class="variablelist">
<p class="title"><b>Parameters of the root finding functions</b></p>
<p class="title"><b>Parameters of the real-valued root finding functions</b></p>
<dl class="variablelist">
<dt><span class="term">F f</span></dt>
<dd>
<p>
Type F must be a callable function object that accepts one parameter
and returns a <a class="link" href="internals/tuples.html" title="Tuples">std::pair,
Type F must be a callable function object (or C++ lambda) that accepts
one parameter and returns a <a class="link" href="internals/tuples.html" title="Tuples">std::pair,
std::tuple, boost::tuple or boost::fusion::tuple</a>:
</p>
<p>
@@ -98,7 +110,7 @@
</p>
<p>
For the third-order methods (<a href="http://en.wikipedia.org/wiki/Halley%27s_method" target="_top">Halley</a>
and Schr&#246;der) the <code class="computeroutput"><span class="identifier">tuple</span></code>
and Schröder) the <code class="computeroutput"><span class="identifier">tuple</span></code>
should have <span class="bold"><strong>three</strong></span> elements containing
the evaluation of the function and its first and second derivatives.
</p>
@@ -151,6 +163,11 @@
an arbitrarily small value <span class="emphasis"><em>of the correct sign</em></span> rather
than zero.
</li>
<li class="listitem">
The functions will raise an <a class="link" href="error_handling.html#math_toolkit.error_handling.evaluation_error">evaluation_error</a>
if arguments <code class="computeroutput"><span class="identifier">min</span></code> and <code class="computeroutput"><span class="identifier">max</span></code> are the wrong way around or if they
converge to a local minima.
</li>
<li class="listitem">
If the derivative at the current best guess for the result is infinite
(or very close to being infinite) then these functions may terminate prematurely.
@@ -190,7 +207,7 @@
be set by experiment so that the final iteration just takes the next value
into the zone where <span class="emphasis"><em>f(x)</em></span> becomes inaccurate. A good
starting point for <span class="emphasis"><em>digits</em></span> would be 0.6*D for Newton
and 0.4*D for Halley or Shr&#246;der iteration, where D is <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">digits</span></code>.
and 0.4*D for Halley or Shröder iteration, where D is <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">digits</span></code>.
</li>
<li class="listitem">
If you need some diagnostic output to see what is going on, you can <code class="computeroutput"><span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_INSTRUMENT</span></code>
@@ -216,11 +233,12 @@
Given an initial guess <span class="emphasis"><em>x0</em></span> the subsequent values are computed
using:
</p>
<div class="blockquote"><blockquote class="blockquote"><p>
<span class="inlinemediaobject"><img src="../../equations/roots1.svg"></span>
</p></blockquote></div>
<p>
<span class="inlinemediaobject"><img src="../../equations/roots1.svg"></span>
</p>
<p>
Out of bounds steps revert to <a class="link" href="roots_noderiv/bisect.html" title="Bisection">bisection</a>
Out-of-bounds steps revert to <a class="link" href="roots_noderiv/bisect.html" title="Bisection">bisection</a>
of the current bounds.
</p>
<p>
@@ -235,9 +253,10 @@
Given an initial guess <span class="emphasis"><em>x0</em></span> the subsequent values are computed
using:
</p>
<p>
<span class="inlinemediaobject"><img src="../../equations/roots2.svg"></span>
</p>
<div class="blockquote"><blockquote class="blockquote"><p>
<span class="inlinemediaobject"><img src="../../equations/roots2.svg"></span>
</p></blockquote></div>
<p>
Over-compensation by the second derivative (one which would proceed in the
wrong direction) causes the method to revert to a Newton-Raphson step.
@@ -250,15 +269,16 @@
</p>
<h5>
<a name="math_toolkit.roots_deriv.h4"></a>
<span class="phrase"><a name="math_toolkit.roots_deriv.schroder"></a></span><a class="link" href="roots_deriv.html#math_toolkit.roots_deriv.schroder">Schr&#246;der's
<span class="phrase"><a name="math_toolkit.roots_deriv.schroder"></a></span><a class="link" href="roots_deriv.html#math_toolkit.roots_deriv.schroder">Schröder's
Method</a>
</h5>
<p>
Given an initial guess x0 the subsequent values are computed using:
</p>
<p>
<span class="inlinemediaobject"><img src="../../equations/roots3.svg"></span>
</p>
<div class="blockquote"><blockquote class="blockquote"><p>
<span class="inlinemediaobject"><img src="../../equations/roots3.svg"></span>
</p></blockquote></div>
<p>
Over-compensation by the second derivative (one which would proceed in the
wrong direction) causes the method to revert to a Newton-Raphson step. Likewise
@@ -273,9 +293,9 @@
Under ideal conditions, the number of correct digits trebles with each iteration.
</p>
<p>
This is Schr&#246;der's general result (equation 18 from <a href="http://drum.lib.umd.edu/handle/1903/577" target="_top">Stewart,
This is Schröder's general result (equation 18 from <a href="http://drum.lib.umd.edu/handle/1903/577" target="_top">Stewart,
G. W. "On Infinitely Many Algorithms for Solving Equations." English
translation of Schr&#246;der's original paper. College Park, MD: University of Maryland,
translation of Schröder's original paper. College Park, MD: University of Maryland,
Institute for Advanced Computer Studies, Department of Computer Science, 1993</a>.)
</p>
<p>
@@ -283,8 +303,56 @@
method), and is known to work well in the presence of multiple roots: something
that neither Newton nor Halley can do.
</p>
<p>
The complex Newton method works slightly differently than the rest of the methods:
Since there is no way to bracket roots in the complex plane, the <code class="computeroutput"><span class="identifier">min</span></code> and <code class="computeroutput"><span class="identifier">max</span></code>
arguments are not accepted. Failure to reach a root is communicated by returning
<code class="computeroutput"><span class="identifier">nan</span></code>s. Remember that if a function
has many roots, then which root the complex Newton's method converges to is
essentially impossible to predict a priori; see the Newton's fractal for more
information.
</p>
<p>
Finally, the derivative of <span class="emphasis"><em>f</em></span> must be continuous at the
root or else non-roots can be found; see <a href="https://math.stackexchange.com/questions/3017766/constructing-newton-iteration-converging-to-non-root" target="_top">here</a>
for an example.
</p>
<p>
An example usage of <code class="computeroutput"><span class="identifier">complex_newton</span></code>
is given in <code class="computeroutput"><span class="identifier">examples</span><span class="special">/</span><span class="identifier">daubechies_coefficients</span><span class="special">.</span><span class="identifier">cpp</span></code>.
</p>
<h5>
<a name="math_toolkit.roots_deriv.h5"></a>
<span class="phrase"><a name="math_toolkit.roots_deriv.quadratics"></a></span><a class="link" href="roots_deriv.html#math_toolkit.roots_deriv.quadratics">Quadratics</a>
</h5>
<p>
To solve a quadratic <span class="emphasis"><em>ax</em></span><sup>2</sup> + <span class="emphasis"><em>bx</em></span> + <span class="emphasis"><em>c</em></span>
= 0, we may use
</p>
<pre class="programlisting"><span class="keyword">auto</span> <span class="special">[</span><span class="identifier">x0</span><span class="special">,</span> <span class="identifier">x1</span><span class="special">]</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tools</span><span class="special">::</span><span class="identifier">quadratic_roots</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">c</span><span class="special">);</span>
</pre>
<p>
If the roots are real, they are arranged so that <code class="computeroutput"><span class="identifier">x0</span></code>
≤ <code class="computeroutput"><span class="identifier">x1</span></code>. If the roots are
complex and the inputs are real, <code class="computeroutput"><span class="identifier">x0</span></code>
and <code class="computeroutput"><span class="identifier">x1</span></code> are both <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">Real</span><span class="special">&gt;::</span><span class="identifier">quiet_NaN</span><span class="special">()</span></code>. In this case we must cast <code class="computeroutput"><span class="identifier">a</span></code>, <code class="computeroutput"><span class="identifier">b</span></code>
and <code class="computeroutput"><span class="identifier">c</span></code> to a complex type to
extract the complex roots. If <code class="computeroutput"><span class="identifier">a</span></code>,
<code class="computeroutput"><span class="identifier">b</span></code> and <code class="computeroutput"><span class="identifier">c</span></code>
are integral, then the roots are of type double. The routine is much faster
if the fused-multiply-add instruction is available on your architecture. If
the fma is not available, the function resorts to slow emulation. Finally,
speed is improved if you compile for your particular architecture. For instance,
if you compile without any architecture flags, then the <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">fma</span></code> call
compiles down to <code class="computeroutput"><span class="identifier">call</span> <span class="identifier">_fma</span></code>,
which dynamically chooses to emulate or execute the <code class="computeroutput"><span class="identifier">vfmadd132sd</span></code>
instruction based on the capabilities of the architecture. If instead, you
compile with (say) <code class="computeroutput"><span class="special">-</span><span class="identifier">march</span><span class="special">=</span><span class="identifier">native</span></code> then
no dynamic choice is made: The <code class="computeroutput"><span class="identifier">vfmadd132sd</span></code>
instruction is always executed if available and emulation is used if not.
</p>
<h5>
<a name="math_toolkit.roots_deriv.h6"></a>
<span class="phrase"><a name="math_toolkit.roots_deriv.examples"></a></span><a class="link" href="roots_deriv.html#math_toolkit.roots_deriv.examples">Examples</a>
</h5>
<p>
@@ -293,11 +361,11 @@
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2006-2010, 2012-2014, 2017 Nikhar
Agrawal, Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos,
Hubert Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Johan R&#229;de, Gautam
Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg, Daryle Walker
and Xiaogang Zhang<p>
<td align="right"><div class="copyright-footer">Copyright © 2006-2021 Nikhar Agrawal, Anton Bikineev, Matthew Borland,
Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert Holin, Bruno
Lalande, John Maddock, Evan Miller, Jeremy Murphy, Matthew Pulver, Johan Råde,
Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg, Daryle
Walker and Xiaogang Zhang<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
</p>