From 5222ce249c814025773a63e0d64f55a0cc063bdf Mon Sep 17 00:00:00 2001 From: jzmaddock Date: Sat, 12 Mar 2022 16:02:18 +0000 Subject: [PATCH] Regenerate docs, add missing files. [CI SKIP] --- doc/html/index.html | 2 +- doc/html/indexes/s01.html | 2 +- doc/html/indexes/s02.html | 2 +- doc/html/indexes/s03.html | 2 +- doc/html/indexes/s04.html | 2 +- doc/html/indexes/s05.html | 2 +- doc/html/math_toolkit/conventions.html | 2 +- .../math_toolkit/internals/color_maps.html | 170 ++++++++++++++++++ doc/html/math_toolkit/navigation.html | 2 +- doc/html/math_toolkit/powers/logaddexp.html | 166 +++++++++++++++++ doc/html/math_toolkit/quartic_roots.html | 88 +++++++++ 11 files changed, 432 insertions(+), 8 deletions(-) create mode 100644 doc/html/math_toolkit/internals/color_maps.html create mode 100644 doc/html/math_toolkit/powers/logaddexp.html create mode 100644 doc/html/math_toolkit/quartic_roots.html diff --git a/doc/html/index.html b/doc/html/index.html index 42df72f19..8d51e7ffe 100644 --- a/doc/html/index.html +++ b/doc/html/index.html @@ -134,7 +134,7 @@ This manual is also available in -

Last revised: March 08, 2022 at 16:03:29 GMT

+

Last revised: March 12, 2022 at 15:44:15 GMT

diff --git a/doc/html/indexes/s01.html b/doc/html/indexes/s01.html index 616dcb911..956566265 100644 --- a/doc/html/indexes/s01.html +++ b/doc/html/indexes/s01.html @@ -24,7 +24,7 @@

-Function Index

+Function Index

1 2 4 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

diff --git a/doc/html/indexes/s02.html b/doc/html/indexes/s02.html index 0580ea017..cc8984f38 100644 --- a/doc/html/indexes/s02.html +++ b/doc/html/indexes/s02.html @@ -24,7 +24,7 @@

-Class Index

+Class Index

A B C D E F G H I K L M N O P Q R S T U V W

diff --git a/doc/html/indexes/s03.html b/doc/html/indexes/s03.html index f9cd0c910..b656b949f 100644 --- a/doc/html/indexes/s03.html +++ b/doc/html/indexes/s03.html @@ -24,7 +24,7 @@

-Typedef Index

+Typedef Index

A B C D E F G H I K L N P R S T U V W

diff --git a/doc/html/indexes/s04.html b/doc/html/indexes/s04.html index 4f65f61b4..3c5f6a5f4 100644 --- a/doc/html/indexes/s04.html +++ b/doc/html/indexes/s04.html @@ -24,7 +24,7 @@

-Macro Index

+Macro Index

B F

diff --git a/doc/html/indexes/s05.html b/doc/html/indexes/s05.html index 9fba74a98..e808a68a1 100644 --- a/doc/html/indexes/s05.html +++ b/doc/html/indexes/s05.html @@ -23,7 +23,7 @@

-Index

+Index

1 2 4 5 7 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

diff --git a/doc/html/math_toolkit/conventions.html b/doc/html/math_toolkit/conventions.html index e725bfc12..11f88a46b 100644 --- a/doc/html/math_toolkit/conventions.html +++ b/doc/html/math_toolkit/conventions.html @@ -27,7 +27,7 @@ Document Conventions

- +

This documentation aims to use of the following naming and formatting conventions. diff --git a/doc/html/math_toolkit/internals/color_maps.html b/doc/html/math_toolkit/internals/color_maps.html new file mode 100644 index 000000000..febbba121 --- /dev/null +++ b/doc/html/math_toolkit/internals/color_maps.html @@ -0,0 +1,170 @@ + + + +Color Maps + + + + + + + + + + + + + + + +
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
+

+
+PrevUpHomeNext +
+
+

+Color Maps +

+
+ + Synopsis +
+
#include <boost/math/tools/color_maps.hpp>
+
+namespace boost::math::tools {
+
+template<typename Real>
+std::array<Real, 3> viridis(Real x);
+
+template<typename Real>
+std::array<Real, 3> plasma(Real x);
+
+template<typename Real>
+std::array<Real, 3> black_body(Real x);
+
+template<typename Real>
+std::array<Real, 3> inferno(Real x);
+
+template<typename Real>
+std::array<Real, 3> smooth_cool_warm(Real x);
+
+template<typename Real>
+std::array<Real, 3> kindlmann(Real x);
+
+template<typename Real>
+std::array<Real, 3> extended_kindlmann(Real x);
+
+template<typename Real>
+std::array<uint8_t, 4> to_8bit_rgba(std::array<Real, 3> const & color);
+
+} // namespaces
+
+
+ + Description +
+

+ Abstractly, a color map is any function which maps [0, 1] -> [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. Much + research has demonstrated that color maps differ wildly in their + usefulness for interpreting quantitative data; see here + for details. In addition, different color maps are useful in different contexts. + For example, the smooth_cool_warm + color map is useful for examining surfaces embedded in 3-space which have + scalar fields defined on them, whereas the inferno + color map is better for understanding 2D data. +

+

+ 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 std::clamp + before interpolating into the color table. +

+

+ For an example of how to use these facilites please refer to example/color_maps_example.cpp Note: To compile the examples directly + you will need to have lodepng. + An example of the viridis color map using the + newton fractal is shown below: +

+

+ +

+

+ Swatches of each are listed below: +

+

+ +

+
  • + Smooth cool warm* +
+

+ +

+
  • + Viridis* +
+

+ +

+
  • + Plasma* +
+

+ +

+
  • + Black body* +
+

+ +

+
  • + Inferno* +
+

+ +

+
  • + Kindlmann* +
+

+ +

+
  • + Extended Kindlmann* +
+
+ + References +
+
  • + Ken Moreland. Why We Use Bad Color Maps and What You Can Do + About it . +
+
+ + + +
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

+ Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +

+
+
+
+PrevUpHomeNext +
+ + diff --git a/doc/html/math_toolkit/navigation.html b/doc/html/math_toolkit/navigation.html index a3f71c46c..c874d6c9a 100644 --- a/doc/html/math_toolkit/navigation.html +++ b/doc/html/math_toolkit/navigation.html @@ -27,7 +27,7 @@ Navigation

- +

Boost.Math documentation is provided in both HTML and PDF formats. diff --git a/doc/html/math_toolkit/powers/logaddexp.html b/doc/html/math_toolkit/powers/logaddexp.html new file mode 100644 index 000000000..774cac660 --- /dev/null +++ b/doc/html/math_toolkit/powers/logaddexp.html @@ -0,0 +1,166 @@ + + + +logaddexp and logsumexp + + + + + + + + + + + + + + + +
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
+

+
+PrevUpHomeNext +
+
+

+logaddexp and logsumexp +

+
+ + Synopsis +
+
#include <boost/math/special_functions/logaddexp.hpp>
+
+namespace boost { namespace math {
+
+template <typename Real>
+Real logaddexp (Real x1, Real x2);
+
+}} // namespaces
+
+#include <boost/math/special_functions/logsumexp.hpp>
+
+namespace boost { namespace math {
+
+template <typename ForwardIterator, typename Real = std::iterator_traits<ForwardIterator>::value_type>
+Real logsumexp (ForwardIterator first, ForwardIterator last);
+
+template <typename ForwardContainer, typename Real = ForwardContainer::value_type>
+Real logsumexp (const ForwardContainer& c);
+
+template <typename... Args, typename Real = typename std::common_type<Args...>::type>
+Real logsumexp(Args&& ...args)
+
+}} // namespace
+
+

+ The function logaddexp(x1, x2) computes log(exp(x1) + exp(x2)). The function + logsumexp(x1, x2, ...) 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. +

+

+ The use is +

+
using std::log;
+
+double x1 = log(1e-50);
+double x2 = log(2.5e-50);
+double x3 = log(3e-50);
+std::vector<double> x = {x1, x2, x3};
+
+double probability1 = boost::math::logaddexp(x1, x2);
+double probability2 = boost::math::logsumexp(x1, x2, x3);
+double probability3 = boost::math::logsumexp(x);
+double probability4 = boost::math::logsumexp(x.begin(), x.end());
+
+

+ Performance Data: +

+
Running ./logaddexp_performance
+Run on Apple M1 Pro
+CPU Caches:
+  L1 Data 64 KiB (x10)
+  L1 Instruction 128 KiB (x10)
+  L2 Unified 4096 KiB (x5)
+Load Average: 2.23, 1.89, 1.88
+-----------------------------------------------------------------------------
+Benchmark                                   Time             CPU   Iterations
+-----------------------------------------------------------------------------
+logaddexp_performance<float>             1.05 ns         1.05 ns    597983940
+logaddexp_performance<double>            1.03 ns         1.03 ns    672682369
+
+
Running ./logsumexp_performance
+Run on Apple M1 Pro
+CPU Caches:
+  L1 Data 64 KiB (x10)
+  L1 Instruction 128 KiB (x10)
+  L2 Unified 4096 KiB (x5)
+Load Average: 1.56, 1.67, 1.81
+-----------------------------------------------------------------------------------------------
+Benchmark                                                     Time             CPU   Iterations
+-----------------------------------------------------------------------------------------------
+logsumexp_performance<float>/64/real_time                   388 ns          388 ns      1797191
+logsumexp_performance<float>/128/real_time                  761 ns          761 ns       890017
+logsumexp_performance<float>/256/real_time                 1513 ns         1513 ns       460217
+logsumexp_performance<float>/512/real_time                 3026 ns         3026 ns       231454
+logsumexp_performance<float>/1024/real_time                6043 ns         6043 ns       113901
+logsumexp_performance<float>/2048/real_time               12084 ns        12084 ns        57590
+logsumexp_performance<float>/4096/real_time               24240 ns        24240 ns        28835
+logsumexp_performance<float>/8192/real_time               48326 ns        48323 ns        14478
+logsumexp_performance<float>/16384/real_time              96645 ns        96642 ns         7181
+logsumexp_performance<float>/32768/real_time             193351 ns       193351 ns         3607
+logsumexp_performance<float>/65536/real_time             386537 ns       386538 ns         1810
+logsumexp_performance<float>/131072/real_time            774055 ns       774056 ns          894
+logsumexp_performance<float>/262144/real_time           1548913 ns      1548847 ns          451
+logsumexp_performance<float>/524288/real_time           3092771 ns      3092770 ns          226
+logsumexp_performance<float>/1048576/real_time          6188087 ns      6188089 ns          112
+logsumexp_performance<float>/real_time_BigO                5.90 N          5.90 N
+logsumexp_performance<float>/real_time_RMS                    0 %             0 %
+logsumexp_performance<double>/64/real_time                  388 ns          388 ns      1806669
+logsumexp_performance<double>/128/real_time                 770 ns          770 ns       898340
+logsumexp_performance<double>/256/real_time                1534 ns         1534 ns       454768
+logsumexp_performance<double>/512/real_time                3063 ns         3063 ns       228057
+logsumexp_performance<double>/1024/real_time               6126 ns         6126 ns       112667
+logsumexp_performance<double>/2048/real_time              12243 ns        12243 ns        56963
+logsumexp_performance<double>/4096/real_time              24476 ns        24476 ns        28485
+logsumexp_performance<double>/8192/real_time              48979 ns        48978 ns        14215
+logsumexp_performance<double>/16384/real_time             97929 ns        97929 ns         7070
+logsumexp_performance<double>/32768/real_time            195826 ns       195826 ns         3560
+logsumexp_performance<double>/65536/real_time            391855 ns       391835 ns         1787
+logsumexp_performance<double>/131072/real_time           784119 ns       784110 ns          882
+logsumexp_performance<double>/262144/real_time          1566408 ns      1566386 ns          446
+logsumexp_performance<double>/524288/real_time          3151649 ns      3150955 ns          223
+logsumexp_performance<double>/1048576/real_time         6300578 ns      6299027 ns          110
+logsumexp_performance<double>/real_time_BigO               6.01 N          6.01 N
+
+
+ + References +
+
+
+ + + +
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

+ Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +

+
+
+
+PrevUpHomeNext +
+ + diff --git a/doc/html/math_toolkit/quartic_roots.html b/doc/html/math_toolkit/quartic_roots.html new file mode 100644 index 000000000..8cccd2d1a --- /dev/null +++ b/doc/html/math_toolkit/quartic_roots.html @@ -0,0 +1,88 @@ + + + +Roots of Quartic Polynomials + + + + + + + + + + + + + + + +
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
+
+
+PrevUpHomeNext +
+
+

+Roots of Quartic Polynomials +

+

+ + Synopsis +

+
#include <boost/math/roots/quartic_roots.hpp>
+
+namespace boost::math::tools {
+
+// Solves ax⁴ + bx³ + cx² + dx + e = 0.
+std::array<Real,3> quartic_roots(Real a, Real b, Real c, Real d, Real e);
+
+}
+
+

+ + Background +

+

+ The quartic_roots function + extracts all real roots of a quartic polynomial ax⁴+ bx³ + cx² + dx + e. + The result is a std::array<Real, 4>, 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. +

+

+ The algorithm uses the classical method of Ferrari, and follows Graphics + Gems V, with an additional Halley iterate for root polishing. A typical + use of a quartic real-root solver is to raytrace a torus. +

+

+ + Performance + and Accuracy +

+

+ On a consumer laptop, we observe extraction of the roots taking ~90ns. The + file reporting/performance/quartic_roots_performance.cpp allows determination of the speed on + your system. +

+
+ + + +
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

+ Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +

+
+
+
+PrevUpHomeNext +
+ +