boost/math
2
0
Fork 0
mirror of https://github.com/boostorg/math.git synced 2026-01-19 04:22:09 +00:00
Code Issues Projects Releases Wiki Activity

Regenerate docs, add missing files.

Browse Source 
[CI SKIP]
This commit is contained in:
jzmaddock
2022-03-12 16:02:18 +00:00
parent ed01dae248
commit 5222ce249c
11 changed files with 432 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/html/index.html
View File

@@ -134,7 +134,7 @@ This manual is also available in <a href="http://sourceforge.net/projects/boost/
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"><p><small>Last revised: March 08, 2022 at 16:03:29 GMT</small></p></td>
<td align="left"><p><small>Last revised: March 12, 2022 at 15:44:15 GMT</small></p></td>
<td align="right"><div class="copyright-footer"></div></td>
</tr></table>
<hr>

2
doc/html/indexes/s01.html
View File

@@ -24,7 +24,7 @@
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="id2054573"></a>Function Index</h2></div></div></div>
<a name="id2055750"></a>Function Index</h2></div></div></div>
<p><a class="link" href="s01.html#idx_id_0">1</a> <a class="link" href="s01.html#idx_id_1">2</a> <a class="link" href="s01.html#idx_id_2">4</a> <a class="link" href="s01.html#idx_id_5">A</a> <a class="link" href="s01.html#idx_id_6">B</a> <a class="link" href="s01.html#idx_id_7">C</a> <a class="link" href="s01.html#idx_id_8">D</a> <a class="link" href="s01.html#idx_id_9">E</a> <a class="link" href="s01.html#idx_id_10">F</a> <a class="link" href="s01.html#idx_id_11">G</a> <a class="link" href="s01.html#idx_id_12">H</a> <a class="link" href="s01.html#idx_id_13">I</a> <a class="link" href="s01.html#idx_id_14">J</a> <a class="link" href="s01.html#idx_id_15">K</a> <a class="link" href="s01.html#idx_id_16">L</a> <a class="link" href="s01.html#idx_id_17">M</a> <a class="link" href="s01.html#idx_id_18">N</a> <a class="link" href="s01.html#idx_id_19">O</a> <a class="link" href="s01.html#idx_id_20">P</a> <a class="link" href="s01.html#idx_id_21">Q</a> <a class="link" href="s01.html#idx_id_22">R</a> <a class="link" href="s01.html#idx_id_23">S</a> <a class="link" href="s01.html#idx_id_24">T</a> <a class="link" href="s01.html#idx_id_25">U</a> <a class="link" href="s01.html#idx_id_26">V</a> <a class="link" href="s01.html#idx_id_27">W</a> <a class="link" href="s01.html#idx_id_28">X</a> <a class="link" href="s01.html#idx_id_29">Y</a> <a class="link" href="s01.html#idx_id_30">Z</a></p>
<div class="variablelist"><dl class="variablelist">
<dt>

2
doc/html/indexes/s02.html
View File

@@ -24,7 +24,7 @@
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="id2085674"></a>Class Index</h2></div></div></div>
<a name="id2088205"></a>Class Index</h2></div></div></div>
<p><a class="link" href="s02.html#idx_id_36">A</a> <a class="link" href="s02.html#idx_id_37">B</a> <a class="link" href="s02.html#idx_id_38">C</a> <a class="link" href="s02.html#idx_id_39">D</a> <a class="link" href="s02.html#idx_id_40">E</a> <a class="link" href="s02.html#idx_id_41">F</a> <a class="link" href="s02.html#idx_id_42">G</a> <a class="link" href="s02.html#idx_id_43">H</a> <a class="link" href="s02.html#idx_id_44">I</a> <a class="link" href="s02.html#idx_id_46">K</a> <a class="link" href="s02.html#idx_id_47">L</a> <a class="link" href="s02.html#idx_id_48">M</a> <a class="link" href="s02.html#idx_id_49">N</a> <a class="link" href="s02.html#idx_id_50">O</a> <a class="link" href="s02.html#idx_id_51">P</a> <a class="link" href="s02.html#idx_id_52">Q</a> <a class="link" href="s02.html#idx_id_53">R</a> <a class="link" href="s02.html#idx_id_54">S</a> <a class="link" href="s02.html#idx_id_55">T</a> <a class="link" href="s02.html#idx_id_56">U</a> <a class="link" href="s02.html#idx_id_57">V</a> <a class="link" href="s02.html#idx_id_58">W</a></p>
<div class="variablelist"><dl class="variablelist">
<dt>

2
doc/html/indexes/s03.html
View File

@@ -24,7 +24,7 @@
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="id2087875"></a>Typedef Index</h2></div></div></div>
<a name="id2091546"></a>Typedef Index</h2></div></div></div>
<p><a class="link" href="s03.html#idx_id_67">A</a> <a class="link" href="s03.html#idx_id_68">B</a> <a class="link" href="s03.html#idx_id_69">C</a> <a class="link" href="s03.html#idx_id_70">D</a> <a class="link" href="s03.html#idx_id_71">E</a> <a class="link" href="s03.html#idx_id_72">F</a> <a class="link" href="s03.html#idx_id_73">G</a> <a class="link" href="s03.html#idx_id_74">H</a> <a class="link" href="s03.html#idx_id_75">I</a> <a class="link" href="s03.html#idx_id_77">K</a> <a class="link" href="s03.html#idx_id_78">L</a> <a class="link" href="s03.html#idx_id_80">N</a> <a class="link" href="s03.html#idx_id_82">P</a> <a class="link" href="s03.html#idx_id_84">R</a> <a class="link" href="s03.html#idx_id_85">S</a> <a class="link" href="s03.html#idx_id_86">T</a> <a class="link" href="s03.html#idx_id_87">U</a> <a class="link" href="s03.html#idx_id_88">V</a> <a class="link" href="s03.html#idx_id_89">W</a></p>
<div class="variablelist"><dl class="variablelist">
<dt>

2
doc/html/indexes/s04.html
View File

@@ -24,7 +24,7 @@
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="id2092038"></a>Macro Index</h2></div></div></div>
<a name="id2094690"></a>Macro Index</h2></div></div></div>
<p><a class="link" href="s04.html#idx_id_99">B</a> <a class="link" href="s04.html#idx_id_103">F</a></p>
<div class="variablelist"><dl class="variablelist">
<dt>

2
doc/html/indexes/s05.html
View File

@@ -23,7 +23,7 @@
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="id2093661"></a>Index</h2></div></div></div>
<a name="id2096320"></a>Index</h2></div></div></div>
<p><a class="link" href="s05.html#idx_id_124">1</a> <a class="link" href="s05.html#idx_id_125">2</a> <a class="link" href="s05.html#idx_id_126">4</a> <a class="link" href="s05.html#idx_id_127">5</a> <a class="link" href="s05.html#idx_id_128">7</a> <a class="link" href="s05.html#idx_id_129">A</a> <a class="link" href="s05.html#idx_id_130">B</a> <a class="link" href="s05.html#idx_id_131">C</a> <a class="link" href="s05.html#idx_id_132">D</a> <a class="link" href="s05.html#idx_id_133">E</a> <a class="link" href="s05.html#idx_id_134">F</a> <a class="link" href="s05.html#idx_id_135">G</a> <a class="link" href="s05.html#idx_id_136">H</a> <a class="link" href="s05.html#idx_id_137">I</a> <a class="link" href="s05.html#idx_id_138">J</a> <a class="link" href="s05.html#idx_id_139">K</a> <a class="link" href="s05.html#idx_id_140">L</a> <a class="link" href="s05.html#idx_id_141">M</a> <a class="link" href="s05.html#idx_id_142">N</a> <a class="link" href="s05.html#idx_id_143">O</a> <a class="link" href="s05.html#idx_id_144">P</a> <a class="link" href="s05.html#idx_id_145">Q</a> <a class="link" href="s05.html#idx_id_146">R</a> <a class="link" href="s05.html#idx_id_147">S</a> <a class="link" href="s05.html#idx_id_148">T</a> <a class="link" href="s05.html#idx_id_149">U</a> <a class="link" href="s05.html#idx_id_150">V</a> <a class="link" href="s05.html#idx_id_151">W</a> <a class="link" href="s05.html#idx_id_152">X</a> <a class="link" href="s05.html#idx_id_153">Y</a> <a class="link" href="s05.html#idx_id_154">Z</a></p>
<div class="variablelist"><dl class="variablelist">
<dt>

2
doc/html/math_toolkit/conventions.html
View File

@@ -27,7 +27,7 @@
<a name="math_toolkit.conventions"></a><a class="link" href="conventions.html" title="Document Conventions">Document Conventions</a>
</h2></div></div></div>
<p>
<a class="indexterm" name="id939265"></a>
<a class="indexterm" name="id941450"></a>
</p>
<p>
This documentation aims to use of the following naming and formatting conventions.

170
doc/html/math_toolkit/internals/color_maps.html Normal file
View File

@@ -0,0 +1,170 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Color Maps</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 3.3.0">
<link rel="up" href="../internals.html" title="Internal tools">
<link rel="prev" href="test_data.html" title="Graphing, Profiling, and Generating Test Data for Special Functions">
<link rel="next" href="../../using_udt.html" title="Chapter 20. Use with User-Defined Floating-Point Types - Boost.Multiprecision and others">
</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="test_data.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../internals.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="../../using_udt.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.internals.color_maps"></a><a class="link" href="color_maps.html" title="Color Maps">Color Maps</a>
</h3></div></div></div>
<h5>
<a name="math_toolkit.internals.color_maps.h0"></a>
<span class="phrase"><a name="math_toolkit.internals.color_maps.synopsis"></a></span><a class="link" href="color_maps.html#math_toolkit.internals.color_maps.synopsis">Synopsis</a>
</h5>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</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">color_maps</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="keyword">namespace</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="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Real</span><span class="special">&gt;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="identifier">Real</span><span class="special">,</span> <span class="number">3</span><span class="special">&gt;</span> <span class="identifier">viridis</span><span class="special">(</span><span class="identifier">Real</span> <span class="identifier">x</span><span class="special">);</span>
<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Real</span><span class="special">&gt;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="identifier">Real</span><span class="special">,</span> <span class="number">3</span><span class="special">&gt;</span> <span class="identifier">plasma</span><span class="special">(</span><span class="identifier">Real</span> <span class="identifier">x</span><span class="special">);</span>
<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Real</span><span class="special">&gt;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="identifier">Real</span><span class="special">,</span> <span class="number">3</span><span class="special">&gt;</span> <span class="identifier">black_body</span><span class="special">(</span><span class="identifier">Real</span> <span class="identifier">x</span><span class="special">);</span>
<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Real</span><span class="special">&gt;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="identifier">Real</span><span class="special">,</span> <span class="number">3</span><span class="special">&gt;</span> <span class="identifier">inferno</span><span class="special">(</span><span class="identifier">Real</span> <span class="identifier">x</span><span class="special">);</span>
<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Real</span><span class="special">&gt;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="identifier">Real</span><span class="special">,</span> <span class="number">3</span><span class="special">&gt;</span> <span class="identifier">smooth_cool_warm</span><span class="special">(</span><span class="identifier">Real</span> <span class="identifier">x</span><span class="special">);</span>
<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Real</span><span class="special">&gt;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="identifier">Real</span><span class="special">,</span> <span class="number">3</span><span class="special">&gt;</span> <span class="identifier">kindlmann</span><span class="special">(</span><span class="identifier">Real</span> <span class="identifier">x</span><span class="special">);</span>
<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Real</span><span class="special">&gt;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="identifier">Real</span><span class="special">,</span> <span class="number">3</span><span class="special">&gt;</span> <span class="identifier">extended_kindlmann</span><span class="special">(</span><span class="identifier">Real</span> <span class="identifier">x</span><span class="special">);</span>
<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Real</span><span class="special">&gt;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="identifier">uint8_t</span><span class="special">,</span> <span class="number">4</span><span class="special">&gt;</span> <span class="identifier">to_8bit_rgba</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="identifier">Real</span><span class="special">,</span> <span class="number">3</span><span class="special">&gt;</span> <span class="keyword">const</span> <span class="special">&amp;</span> <span class="identifier">color</span><span class="special">);</span>
<span class="special">}</span> <span class="comment">// namespaces</span>
</pre>
<h5>
<a name="math_toolkit.internals.color_maps.h1"></a>
<span class="phrase"><a name="math_toolkit.internals.color_maps.description"></a></span><a class="link" href="color_maps.html#math_toolkit.internals.color_maps.description">Description</a>
</h5>
<p>
Abstractly, a color map is any function which maps [0, 1] -&gt; [0, 1]^3.
As stated, this definition is too broad to be useful, so in Boost, we restrict
our attention to the subset of color maps which are useful for the understanding
of scientific data. <a href="https://www.kennethmoreland.com/color-advice/BadColorMaps.pdf" target="_top">Much
research</a> has demonstrated that color maps differ wildly in their
usefulness for interpreting quantitative data; see <a href="https://www.kennethmoreland.com/color-advice/" target="_top">here</a>
for details. In addition, different color maps are useful in different contexts.
For example, the <code class="computeroutput"><span class="identifier">smooth_cool_warm</span></code>
color map is useful for examining surfaces embedded in 3-space which have
scalar fields defined on them, whereas the <code class="computeroutput"><span class="identifier">inferno</span></code>
color map is better for understanding 2D data.
</p>
<p>
Despite the fact that a color map, per our definition, has a domain of [0,
1], we nonetheless do not throw an exception if the value provided falls
outside this range. This is for two reasons: First, visualizations are themselves
amazing debuggers, and if we threw an exception the calculation would not
complete and visual debugging would be inaccessible. Second, often small
changes in floating point rounding cause the value provided to be only slightly
below zero, or just slightly above 1. Hence, we make a call to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">clamp</span></code>
before interpolating into the color table.
</p>
<p>
For an example of how to use these facilites please refer to <code class="computeroutput"><span class="identifier">example</span><span class="special">/</span><span class="identifier">color_maps_example</span><span class="special">.</span><span class="identifier">cpp</span></code> Note: To compile the examples directly
you will need to have <a href="https://github.com/lvandeve/lodepng" target="_top">lodepng</a>.
An example of the viridis color map using <a href="https://en.wikipedia.org/wiki/Newton_fractal" target="_top">the
newton fractal</a> is shown below:
</p>
<p>
<span class="inlinemediaobject"><img src="../../../images/viridis_newton_fractal.png"></span>
</p>
<p>
Swatches of each are listed below:
</p>
<p>
<span class="inlinemediaobject"><img src="../../../images/smooth_cool_warm_swatch.png"></span>
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
Smooth cool warm*
</li></ul></div>
<p>
<span class="inlinemediaobject"><img src="../../../images/viridis_swatch.png"></span>
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
Viridis*
</li></ul></div>
<p>
<span class="inlinemediaobject"><img src="../../../images/plasma_swatch.png"></span>
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
Plasma*
</li></ul></div>
<p>
<span class="inlinemediaobject"><img src="../../../images/black_body_swatch.png"></span>
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
Black body*
</li></ul></div>
<p>
<span class="inlinemediaobject"><img src="../../../images/inferno_swatch.png"></span>
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
Inferno*
</li></ul></div>
<p>
<span class="inlinemediaobject"><img src="../../../images/kindlmann_swatch.png"></span>
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
Kindlmann*
</li></ul></div>
<p>
<span class="inlinemediaobject"><img src="../../../images/extended_kindlmann_swatch.png"></span>
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
Extended Kindlmann*
</li></ul></div>
<h5>
<a name="math_toolkit.internals.color_maps.h2"></a>
<span class="phrase"><a name="math_toolkit.internals.color_maps.references"></a></span><a class="link" href="color_maps.html#math_toolkit.internals.color_maps.references">References</a>
</h5>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
Ken Moreland. <span class="emphasis"><em>Why We Use Bad Color Maps and What You Can Do
About it</em></span> .
</li></ul></div>
</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 © 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>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="test_data.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../internals.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="../../using_udt.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

2
doc/html/math_toolkit/navigation.html
View File

@@ -27,7 +27,7 @@
<a name="math_toolkit.navigation"></a><a class="link" href="navigation.html" title="Navigation">Navigation</a>
</h2></div></div></div>
<p>
<a class="indexterm" name="id939133"></a>
<a class="indexterm" name="id941275"></a>
</p>
<p>
Boost.Math documentation is provided in both HTML and PDF formats.

166
doc/html/math_toolkit/powers/logaddexp.html Normal file
View File

@@ -0,0 +1,166 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>logaddexp and logsumexp</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 3.3.0">
<link rel="up" href="../powers.html" title="Basic Functions">
<link rel="prev" href="rsqrt.html" title="Reciprocal square root">
<link rel="next" href="../sinc.html" title="Sinus Cardinal and Hyperbolic Sinus Cardinal Functions">
</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="rsqrt.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../powers.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="../sinc.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.powers.logaddexp"></a><a class="link" href="logaddexp.html" title="logaddexp and logsumexp">logaddexp and logsumexp</a>
</h3></div></div></div>
<h5>
<a name="math_toolkit.powers.logaddexp.h0"></a>
<span class="phrase"><a name="math_toolkit.powers.logaddexp.synopsis"></a></span><a class="link" href="logaddexp.html#math_toolkit.powers.logaddexp.synopsis">Synopsis</a>
</h5>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">logaddexp</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span> <span class="special">{</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Real</span><span class="special">&gt;</span>
<span class="identifier">Real</span> <span class="identifier">logaddexp</span> <span class="special">(</span><span class="identifier">Real</span> <span class="identifier">x1</span><span class="special">,</span> <span class="identifier">Real</span> <span class="identifier">x2</span><span class="special">);</span>
<span class="special">}}</span> <span class="comment">// namespaces</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">logsumexp</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span> <span class="special">{</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">ForwardIterator</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Real</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">ForwardIterator</span><span class="special">&gt;::</span><span class="identifier">value_type</span><span class="special">&gt;</span>
<span class="identifier">Real</span> <span class="identifier">logsumexp</span> <span class="special">(</span><span class="identifier">ForwardIterator</span> <span class="identifier">first</span><span class="special">,</span> <span class="identifier">ForwardIterator</span> <span class="identifier">last</span><span class="special">);</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">ForwardContainer</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Real</span> <span class="special">=</span> <span class="identifier">ForwardContainer</span><span class="special">::</span><span class="identifier">value_type</span><span class="special">&gt;</span>
<span class="identifier">Real</span> <span class="identifier">logsumexp</span> <span class="special">(</span><span class="keyword">const</span> <span class="identifier">ForwardContainer</span><span class="special">&amp;</span> <span class="identifier">c</span><span class="special">);</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span><span class="special">...</span> <span class="identifier">Args</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Real</span> <span class="special">=</span> <span class="keyword">typename</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">common_type</span><span class="special">&lt;</span><span class="identifier">Args</span><span class="special">...&gt;::</span><span class="identifier">type</span><span class="special">&gt;</span>
<span class="identifier">Real</span> <span class="identifier">logsumexp</span><span class="special">(</span><span class="identifier">Args</span><span class="special">&amp;&amp;</span> <span class="special">...</span><span class="identifier">args</span><span class="special">)</span>
<span class="special">}}</span> <span class="comment">// namespace</span>
</pre>
<p>
The function <code class="computeroutput"><span class="identifier">logaddexp</span><span class="special">(</span><span class="identifier">x1</span><span class="special">,</span> <span class="identifier">x2</span><span class="special">)</span></code> computes log(exp(x1) + exp(x2)). The function
<code class="computeroutput"><span class="identifier">logsumexp</span><span class="special">(</span><span class="identifier">x1</span><span class="special">,</span> <span class="identifier">x2</span><span class="special">,</span> <span class="special">...)</span></code> is
generalized to compute log(exp(x1) + exp(x2) + ...). This function is useful
in statistics where the calculated probabilities of events may be so small
as to exceed the range of normal floating point numbers. In such cases the
logarithm of the calculated probability is stored.
</p>
<p>
The use is
</p>
<pre class="programlisting"><span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">log</span><span class="special">;</span>
<span class="keyword">double</span> <span class="identifier">x1</span> <span class="special">=</span> <span class="identifier">log</span><span class="special">(</span><span class="number">1e-50</span><span class="special">);</span>
<span class="keyword">double</span> <span class="identifier">x2</span> <span class="special">=</span> <span class="identifier">log</span><span class="special">(</span><span class="number">2.5e-50</span><span class="special">);</span>
<span class="keyword">double</span> <span class="identifier">x3</span> <span class="special">=</span> <span class="identifier">log</span><span class="special">(</span><span class="number">3e-50</span><span class="special">);</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="identifier">x</span> <span class="special">=</span> <span class="special">{</span><span class="identifier">x1</span><span class="special">,</span> <span class="identifier">x2</span><span class="special">,</span> <span class="identifier">x3</span><span class="special">};</span>
<span class="keyword">double</span> <span class="identifier">probability1</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">logaddexp</span><span class="special">(</span><span class="identifier">x1</span><span class="special">,</span> <span class="identifier">x2</span><span class="special">);</span>
<span class="keyword">double</span> <span class="identifier">probability2</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">logsumexp</span><span class="special">(</span><span class="identifier">x1</span><span class="special">,</span> <span class="identifier">x2</span><span class="special">,</span> <span class="identifier">x3</span><span class="special">);</span>
<span class="keyword">double</span> <span class="identifier">probability3</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">logsumexp</span><span class="special">(</span><span class="identifier">x</span><span class="special">);</span>
<span class="keyword">double</span> <span class="identifier">probability4</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">logsumexp</span><span class="special">(</span><span class="identifier">x</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">x</span><span class="special">.</span><span class="identifier">end</span><span class="special">());</span>
</pre>
<p>
Performance Data:
</p>
<pre class="programlisting"><span class="identifier">Running</span> <span class="special">./</span><span class="identifier">logaddexp_performance</span>
<span class="identifier">Run</span> <span class="identifier">on</span> <span class="identifier">Apple</span> <span class="identifier">M1</span> <span class="identifier">Pro</span>
<span class="identifier">CPU</span> <span class="identifier">Caches</span><span class="special">:</span>
<span class="identifier">L1</span> <span class="identifier">Data</span> <span class="number">64</span> <span class="identifier">KiB</span> <span class="special">(</span><span class="identifier">x10</span><span class="special">)</span>
<span class="identifier">L1</span> <span class="identifier">Instruction</span> <span class="number">128</span> <span class="identifier">KiB</span> <span class="special">(</span><span class="identifier">x10</span><span class="special">)</span>
<span class="identifier">L2</span> <span class="identifier">Unified</span> <span class="number">4096</span> <span class="identifier">KiB</span> <span class="special">(</span><span class="identifier">x5</span><span class="special">)</span>
<span class="identifier">Load</span> <span class="identifier">Average</span><span class="special">:</span> <span class="number">2.23</span><span class="special">,</span> <span class="number">1.89</span><span class="special">,</span> <span class="number">1.88</span>
<span class="special">-----------------------------------------------------------------------------</span>
<span class="identifier">Benchmark</span> <span class="identifier">Time</span> <span class="identifier">CPU</span> <span class="identifier">Iterations</span>
<span class="special">-----------------------------------------------------------------------------</span>
<span class="identifier">logaddexp_performance</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">&gt;</span> <span class="number">1.05</span> <span class="identifier">ns</span> <span class="number">1.05</span> <span class="identifier">ns</span> <span class="number">597983940</span>
<span class="identifier">logaddexp_performance</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="number">1.03</span> <span class="identifier">ns</span> <span class="number">1.03</span> <span class="identifier">ns</span> <span class="number">672682369</span>
</pre>
<pre class="programlisting"><span class="identifier">Running</span> <span class="special">./</span><span class="identifier">logsumexp_performance</span>
<span class="identifier">Run</span> <span class="identifier">on</span> <span class="identifier">Apple</span> <span class="identifier">M1</span> <span class="identifier">Pro</span>
<span class="identifier">CPU</span> <span class="identifier">Caches</span><span class="special">:</span>
<span class="identifier">L1</span> <span class="identifier">Data</span> <span class="number">64</span> <span class="identifier">KiB</span> <span class="special">(</span><span class="identifier">x10</span><span class="special">)</span>
<span class="identifier">L1</span> <span class="identifier">Instruction</span> <span class="number">128</span> <span class="identifier">KiB</span> <span class="special">(</span><span class="identifier">x10</span><span class="special">)</span>
<span class="identifier">L2</span> <span class="identifier">Unified</span> <span class="number">4096</span> <span class="identifier">KiB</span> <span class="special">(</span><span class="identifier">x5</span><span class="special">)</span>
<span class="identifier">Load</span> <span class="identifier">Average</span><span class="special">:</span> <span class="number">1.56</span><span class="special">,</span> <span class="number">1.67</span><span class="special">,</span> <span class="number">1.81</span>
<span class="special">-----------------------------------------------------------------------------------------------</span>
<span class="identifier">Benchmark</span> <span class="identifier">Time</span> <span class="identifier">CPU</span> <span class="identifier">Iterations</span>
<span class="special">-----------------------------------------------------------------------------------------------</span>
<span class="identifier">logsumexp_performance</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">&gt;/</span><span class="number">64</span><span class="special">/</span><span class="identifier">real_time</span> <span class="number">388</span> <span class="identifier">ns</span> <span class="number">388</span> <span class="identifier">ns</span> <span class="number">1797191</span>
<span class="identifier">logsumexp_performance</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">&gt;/</span><span class="number">128</span><span class="special">/</span><span class="identifier">real_time</span> <span class="number">761</span> <span class="identifier">ns</span> <span class="number">761</span> <span class="identifier">ns</span> <span class="number">890017</span>
<span class="identifier">logsumexp_performance</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">&gt;/</span><span class="number">256</span><span class="special">/</span><span class="identifier">real_time</span> <span class="number">1513</span> <span class="identifier">ns</span> <span class="number">1513</span> <span class="identifier">ns</span> <span class="number">460217</span>
<span class="identifier">logsumexp_performance</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">&gt;/</span><span class="number">512</span><span class="special">/</span><span class="identifier">real_time</span> <span class="number">3026</span> <span class="identifier">ns</span> <span class="number">3026</span> <span class="identifier">ns</span> <span class="number">231454</span>
<span class="identifier">logsumexp_performance</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">&gt;/</span><span class="number">1024</span><span class="special">/</span><span class="identifier">real_time</span> <span class="number">6043</span> <span class="identifier">ns</span> <span class="number">6043</span> <span class="identifier">ns</span> <span class="number">113901</span>
<span class="identifier">logsumexp_performance</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">&gt;/</span><span class="number">2048</span><span class="special">/</span><span class="identifier">real_time</span> <span class="number">12084</span> <span class="identifier">ns</span> <span class="number">12084</span> <span class="identifier">ns</span> <span class="number">57590</span>
<span class="identifier">logsumexp_performance</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">&gt;/</span><span class="number">4096</span><span class="special">/</span><span class="identifier">real_time</span> <span class="number">24240</span> <span class="identifier">ns</span> <span class="number">24240</span> <span class="identifier">ns</span> <span class="number">28835</span>
<span class="identifier">logsumexp_performance</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">&gt;/</span><span class="number">8192</span><span class="special">/</span><span class="identifier">real_time</span> <span class="number">48326</span> <span class="identifier">ns</span> <span class="number">48323</span> <span class="identifier">ns</span> <span class="number">14478</span>
<span class="identifier">logsumexp_performance</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">&gt;/</span><span class="number">16384</span><span class="special">/</span><span class="identifier">real_time</span> <span class="number">96645</span> <span class="identifier">ns</span> <span class="number">96642</span> <span class="identifier">ns</span> <span class="number">7181</span>
<span class="identifier">logsumexp_performance</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">&gt;/</span><span class="number">32768</span><span class="special">/</span><span class="identifier">real_time</span> <span class="number">193351</span> <span class="identifier">ns</span> <span class="number">193351</span> <span class="identifier">ns</span> <span class="number">3607</span>
<span class="identifier">logsumexp_performance</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">&gt;/</span><span class="number">65536</span><span class="special">/</span><span class="identifier">real_time</span> <span class="number">386537</span> <span class="identifier">ns</span> <span class="number">386538</span> <span class="identifier">ns</span> <span class="number">1810</span>
<span class="identifier">logsumexp_performance</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">&gt;/</span><span class="number">131072</span><span class="special">/</span><span class="identifier">real_time</span> <span class="number">774055</span> <span class="identifier">ns</span> <span class="number">774056</span> <span class="identifier">ns</span> <span class="number">894</span>
<span class="identifier">logsumexp_performance</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">&gt;/</span><span class="number">262144</span><span class="special">/</span><span class="identifier">real_time</span> <span class="number">1548913</span> <span class="identifier">ns</span> <span class="number">1548847</span> <span class="identifier">ns</span> <span class="number">451</span>
<span class="identifier">logsumexp_performance</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">&gt;/</span><span class="number">524288</span><span class="special">/</span><span class="identifier">real_time</span> <span class="number">3092771</span> <span class="identifier">ns</span> <span class="number">3092770</span> <span class="identifier">ns</span> <span class="number">226</span>
<span class="identifier">logsumexp_performance</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">&gt;/</span><span class="number">1048576</span><span class="special">/</span><span class="identifier">real_time</span> <span class="number">6188087</span> <span class="identifier">ns</span> <span class="number">6188089</span> <span class="identifier">ns</span> <span class="number">112</span>
<span class="identifier">logsumexp_performance</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">&gt;/</span><span class="identifier">real_time_BigO</span> <span class="number">5.90</span> <span class="identifier">N</span> <span class="number">5.90</span> <span class="identifier">N</span>
<span class="identifier">logsumexp_performance</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">&gt;/</span><span class="identifier">real_time_RMS</span> <span class="number">0</span> <span class="special">%</span> <span class="number">0</span> <span class="special">%</span>
<span class="identifier">logsumexp_performance</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;/</span><span class="number">64</span><span class="special">/</span><span class="identifier">real_time</span> <span class="number">388</span> <span class="identifier">ns</span> <span class="number">388</span> <span class="identifier">ns</span> <span class="number">1806669</span>
<span class="identifier">logsumexp_performance</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;/</span><span class="number">128</span><span class="special">/</span><span class="identifier">real_time</span> <span class="number">770</span> <span class="identifier">ns</span> <span class="number">770</span> <span class="identifier">ns</span> <span class="number">898340</span>
<span class="identifier">logsumexp_performance</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;/</span><span class="number">256</span><span class="special">/</span><span class="identifier">real_time</span> <span class="number">1534</span> <span class="identifier">ns</span> <span class="number">1534</span> <span class="identifier">ns</span> <span class="number">454768</span>
<span class="identifier">logsumexp_performance</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;/</span><span class="number">512</span><span class="special">/</span><span class="identifier">real_time</span> <span class="number">3063</span> <span class="identifier">ns</span> <span class="number">3063</span> <span class="identifier">ns</span> <span class="number">228057</span>
<span class="identifier">logsumexp_performance</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;/</span><span class="number">1024</span><span class="special">/</span><span class="identifier">real_time</span> <span class="number">6126</span> <span class="identifier">ns</span> <span class="number">6126</span> <span class="identifier">ns</span> <span class="number">112667</span>
<span class="identifier">logsumexp_performance</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;/</span><span class="number">2048</span><span class="special">/</span><span class="identifier">real_time</span> <span class="number">12243</span> <span class="identifier">ns</span> <span class="number">12243</span> <span class="identifier">ns</span> <span class="number">56963</span>
<span class="identifier">logsumexp_performance</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;/</span><span class="number">4096</span><span class="special">/</span><span class="identifier">real_time</span> <span class="number">24476</span> <span class="identifier">ns</span> <span class="number">24476</span> <span class="identifier">ns</span> <span class="number">28485</span>
<span class="identifier">logsumexp_performance</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;/</span><span class="number">8192</span><span class="special">/</span><span class="identifier">real_time</span> <span class="number">48979</span> <span class="identifier">ns</span> <span class="number">48978</span> <span class="identifier">ns</span> <span class="number">14215</span>
<span class="identifier">logsumexp_performance</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;/</span><span class="number">16384</span><span class="special">/</span><span class="identifier">real_time</span> <span class="number">97929</span> <span class="identifier">ns</span> <span class="number">97929</span> <span class="identifier">ns</span> <span class="number">7070</span>
<span class="identifier">logsumexp_performance</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;/</span><span class="number">32768</span><span class="special">/</span><span class="identifier">real_time</span> <span class="number">195826</span> <span class="identifier">ns</span> <span class="number">195826</span> <span class="identifier">ns</span> <span class="number">3560</span>
<span class="identifier">logsumexp_performance</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;/</span><span class="number">65536</span><span class="special">/</span><span class="identifier">real_time</span> <span class="number">391855</span> <span class="identifier">ns</span> <span class="number">391835</span> <span class="identifier">ns</span> <span class="number">1787</span>
<span class="identifier">logsumexp_performance</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;/</span><span class="number">131072</span><span class="special">/</span><span class="identifier">real_time</span> <span class="number">784119</span> <span class="identifier">ns</span> <span class="number">784110</span> <span class="identifier">ns</span> <span class="number">882</span>
<span class="identifier">logsumexp_performance</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;/</span><span class="number">262144</span><span class="special">/</span><span class="identifier">real_time</span> <span class="number">1566408</span> <span class="identifier">ns</span> <span class="number">1566386</span> <span class="identifier">ns</span> <span class="number">446</span>
<span class="identifier">logsumexp_performance</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;/</span><span class="number">524288</span><span class="special">/</span><span class="identifier">real_time</span> <span class="number">3151649</span> <span class="identifier">ns</span> <span class="number">3150955</span> <span class="identifier">ns</span> <span class="number">223</span>
<span class="identifier">logsumexp_performance</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;/</span><span class="number">1048576</span><span class="special">/</span><span class="identifier">real_time</span> <span class="number">6300578</span> <span class="identifier">ns</span> <span class="number">6299027</span> <span class="identifier">ns</span> <span class="number">110</span>
<span class="identifier">logsumexp_performance</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;/</span><span class="identifier">real_time_BigO</span> <span class="number">6.01</span> <span class="identifier">N</span> <span class="number">6.01</span> <span class="identifier">N</span>
</pre>
<h5>
<a name="math_toolkit.powers.logaddexp.h1"></a>
<span class="phrase"><a name="math_toolkit.powers.logaddexp.references"></a></span><a class="link" href="logaddexp.html#math_toolkit.powers.logaddexp.references">References</a>
</h5>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
Higham, Nicholas J. <a href="https://nhigham.com/2021/01/05/what-is-the-log-sum-exp-function/" target="_top">What
is the Log-Sum-Exp Function?</a>
</li></ul></div>
</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 © 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>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="rsqrt.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../powers.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="../sinc.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

88
doc/html/math_toolkit/quartic_roots.html Normal file
View File

@@ -0,0 +1,88 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Roots of Quartic Polynomials</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 3.3.0">
<link rel="up" href="../root_finding.html" title="Chapter 10. Root Finding &amp; Minimization Algorithms">
<link rel="prev" href="cubic_roots.html" title="Roots of Cubic Polynomials">
<link rel="next" href="root_finding_examples.html" title="Examples of Root-Finding (with and without derivatives)">
</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="cubic_roots.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../root_finding.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="root_finding_examples.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="math_toolkit.quartic_roots"></a><a class="link" href="quartic_roots.html" title="Roots of Quartic Polynomials">Roots of Quartic Polynomials</a>
</h2></div></div></div>
<h4>
<a name="math_toolkit.quartic_roots.h0"></a>
<span class="phrase"><a name="math_toolkit.quartic_roots.synopsis"></a></span><a class="link" href="quartic_roots.html#math_toolkit.quartic_roots.synopsis">Synopsis</a>
</h4>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">roots</span><span class="special">/</span><span class="identifier">quartic_roots</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="keyword">namespace</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="comment">// Solves ax⁴ + bx³ + cx² + dx + e = 0.</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="identifier">Real</span><span class="special">,</span><span class="number">3</span><span class="special">&gt;</span> <span class="identifier">quartic_roots</span><span class="special">(</span><span class="identifier">Real</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">Real</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">Real</span> <span class="identifier">c</span><span class="special">,</span> <span class="identifier">Real</span> <span class="identifier">d</span><span class="special">,</span> <span class="identifier">Real</span> <span class="identifier">e</span><span class="special">);</span>
<span class="special">}</span>
</pre>
<h4>
<a name="math_toolkit.quartic_roots.h1"></a>
<span class="phrase"><a name="math_toolkit.quartic_roots.background"></a></span><a class="link" href="quartic_roots.html#math_toolkit.quartic_roots.background">Background</a>
</h4>
<p>
The <code class="computeroutput"><span class="identifier">quartic_roots</span></code> function
extracts all real roots of a quartic polynomial ax⁴+ bx³ + cx² + dx + e.
The result is a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="identifier">Real</span><span class="special">,</span> <span class="number">4</span><span class="special">&gt;</span></code>, which has length four, irrespective of
the number of real roots the polynomial possesses. (This is to prevent the
performance overhead of allocating a vector, which often exceeds the time to
extract the roots.) The roots are returned in nondecreasing order. If a root
is complex, then it is placed at the back of the array and set to a nan.
</p>
<p>
The algorithm uses the classical method of Ferrari, and follows <a href="https://github.com/erich666/GraphicsGems/blob/master/gems/Roots3And4.c" target="_top">Graphics
Gems V</a>, with an additional Halley iterate for root polishing. A typical
use of a quartic real-root solver is to raytrace a torus.
</p>
<h4>
<a name="math_toolkit.quartic_roots.h2"></a>
<span class="phrase"><a name="math_toolkit.quartic_roots.performance_and_accuracy"></a></span><a class="link" href="quartic_roots.html#math_toolkit.quartic_roots.performance_and_accuracy">Performance
and Accuracy</a>
</h4>
<p>
On a consumer laptop, we observe extraction of the roots taking ~90ns. The
file <code class="computeroutput"><span class="identifier">reporting</span><span class="special">/</span><span class="identifier">performance</span><span class="special">/</span><span class="identifier">quartic_roots_performance</span><span class="special">.</span><span class="identifier">cpp</span></code> allows determination of the speed on
your system.
</p>
</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 © 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>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="cubic_roots.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../root_finding.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="root_finding_examples.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>