d7141cd353
* Jacobi Theta functions Implementations, tests, and ULP plotting programs are provided for the four Jacobi Theta functions per #373. Twenty-four public C++ functions are provided in all, covering various precision-preserving scenarios. Documentation for collaborators is provided in the code comments. Proper documentation for end users will be provided when the implementation and APIs are finalized. Some tests are failing; this implementation is meant to start a conversation. The core dilemma faced by the author was that large values of |q| resulted in slow convergence, and sometimes wildly inaccurate results. Following the implementation note in DLMF 20.14, I added code to switch over to the imaginary versions of the theta functions when |q| > 0.85. This restored accuracy such that all of the identity tests passed for a loose-enough epsilon, but then lost precision to the point that the Wolfram Alpha spot checks failed. It is the author's hope that someone with floating-point experience can tame the exponential dragons and squeeze the ULPs back down to a reasonable range when |q| is large. When #392 is merged I will add more thorough value tests, although I fully expect them to fail until the underlying precision issues are resolved. As a final note, the precision issues do not affect the z=0 case - the ULP plots indicate these return values within 2 ULP across all valid |q|. So that's a start. * [CI SKIP] Jacobi theta: Add special-value tests and more * Add tests covering z=0 special values from MathWorld * Add missing real_concept header * Replace M_PI and friends with constants::pi etc * Use BOOST_MATH_STD_USING in more places * Jacobi theta: Test two more of Watson's identities [CI SKIP] See https://mathworld.wolfram.com/JacobiThetaFunctions.html (Equations 48 and 49) * Improve precision of Jacobi theta functions [CI SKIP] Rewrite the private imaginary versions to use double-sided summations following DLMF 20.13.4 and 20.13.5. This cuts down the worst of the precision issues by a factor of 10, and gets more of the tests to pass. I am confident enough in the code path to eliminate the compile-time __JACOBI_THETA_USE_IMAGINARY flag. In fact the imaginary-z code paths are now enabled for all |q| > 0.04, i.e. most legal values of q. More extensive tests will be needed to illuminate any remaining precision issues. * Jacobi theta: Make changes suggested in #394 [CI SKIP] * Add LICENSE notice to main file * Document convergence criteria * Eliminate eps*eps = 0 logic. This causes some disagreement with the zero returned by Wolfram Alpha for z=0, q > 0.99 in the fourth function. Mathematically, the fourth function is never exactly zero, so I don't trust Wolfram here. * Per code-review comments, remove multiplications by floating-point 2. * Tweak the plotting programs to display their titles, and to uniformly use `float` as their CoarseType and `long double` as their `PreciseType`. * Add quadrature tests to Jacobi theta functions [CI SKIP] The quadrature tests revealed a problem in the m1 functions: they too should switch to the _IMAGINARY logic for q > exp(-pi), or will suffer from slow convergence. Fix them. Also tighten tolerances for many tests from sqrt(eps) to 100 * eps. * Test Jacobi thetas against elliptic functions and elliptic integrals [CI SKIP] See: * https://dlmf.nist.gov/22.2 * https://dlmf.nist.gov/20.9#i * Test Jacobi Thetas against their Laplace transforms [CI SKIP] See: * https://dlmf.nist.gov/20.10#ii I did find some disagreement, and dropped the negative sign from the theta1 equation. DLMF's theta2 and theta3 Laplace transform equations do not agree at all with the computed values - will need to investigate. In the meantime, the two implemented equations agree to 4 EPS so I am keeping them. * Add a note on using log1p with Jacobi theta functions [CI SKIP] See discussion: * https://github.com/boostorg/math/pull/394#issuecomment-655871762 * Add random data tests to Jacobi Theta functions [CI SKIP] Add a test data generator program for the Jacobi theta functions. This program will produce data for the tau parameterization, so that precision isn't lost during the log-transformation. This distinguishes it from the Wolfram Alpha data, which is parameterized by q. A few of these new random-data tests are failing, but not by obscene margins (< 100 EPS). These failures will be addressed when the test tolerances are finalized. * Add small-tau tests and simplify Jacobi Theta code [CI SKIP] Add tests for small tau (i.e. large q). The tests are failing with mean ~ 200 EPS and max ~ 800 EPS. These look like worst-case input, and should be the focus of future accuracy improvements. This commit also simplifies the _IMAGINARY code by abstracting all of the loops into a single svelte function. * Add user documentation for Jacobi Theta functions [CI SKIP] * Add function graphs to Jacobi Theta docs [CI SKIP] * Define Jacobi Theta test tolerances [CI SKIP] * Add implementation note on Jacobi theta functions [CI SKIP] * Consolidate Jacobi Theta ULPs plotting programs [CI SKIP] * Fix q domain checking of jacobi_theta4 [CI SKIP] * Add ULPs plots to Jacobi Theta docs [CI SKIP] Also add the built HTML files for easy evaluation. A full rebuild is needed for the new docs to appear in the indexes. * Add missing Jacobi Theta ULPs plots [CI SKIP] * Add LaTeX source for Jacobi Theta equations [CI SKIP] * Remove unused Jacobi Theta PNG equations [CI SKIP] * Add Jacobi Theta performance script [CI SKIP] Provided by @NAThompson. * Remove vestigial eps*eps check from jacobi_theta3 [CI SKIP] * Update Jacobi Theta docs per code review comments [CI SKIP] * Enable arg promotion for Jacobi Theta functions [CI SKIP] Add Jacobi theta functions to the instantiation tests and fix up everything needed to make them pass. This changes the function signatures to use promote_args. * Fix Jacobi Theta plotting script [CI SKIP] This script broke when the promote_args API was added. * Change Jacobi Theta convergence criterion [CI SKIP] Compare the non-oscillating part of the delta to the previous one. This avoids some headaches comparing the delta to the partial sum, because the partial sum can be a small number due to the oscillating component alternating signs. Because successive terms involve either q^n^2 or exp(-(pi*n)^2), convergence should still happen pretty quickly. Graphs have been updated and tests still passs with no noticeable difference.
Boost Math Library 
ANNOUNCEMENT: Support for C++03 is now deprecated in this library and will be supported in existing features only until March 2021. New features will require at least C++11, as will existing features from next year.
This library is divided into several interconnected parts:
Floating Point Utilities
Utility functions for dealing with floating point arithmetic, includes functions for floating point classification (fpclassify, isnan, isinf etc), sign manipulation, rounding, comparison, and computing the distance between floating point numbers.
Specific Width Floating Point Types
A set of typedefs similar to those provided by but for floating point types.
Mathematical Constants
A wide range of constants ranging from various multiples of π, fractions, Euler's constant, etc.
These are of course usable from template code, or as non-templates with a simplified interface if that is more appropriate.
Statistical Distributions
Provides a reasonably comprehensive set of statistical distributions, upon which higher level statistical tests can be built.
The initial focus is on the central univariate distributions. Both continuous (like normal & Fisher) and discrete (like binomial & Poisson) distributions are provided.
A comprehensive tutorial is provided, along with a series of worked examples illustrating how the library is used to conduct statistical tests.
Special Functions
Provides a small number of high quality special functions; initially these were concentrated on functions used in statistical applications along with those in the Technical Report on C++ Library Extensions.
The function families currently implemented are the gamma, beta & error functions along with the incomplete gamma and beta functions (four variants of each) and all the possible inverses of these, plus the digamma, various factorial functions, Bessel functions, elliptic integrals, hypergeometrics, sinus cardinals (along with their hyperbolic variants), inverse hyperbolic functions, Legrendre/Laguerre/Hermite/Chebyshev polynomials and various special power and logarithmic functions.
All the implementations are fully generic and support the use of arbitrary "real-number" types, including Boost.Multiprecision, although they are optimised for use with types with known significand (or mantissa) sizes: typically float, double or long double.
These functions also provide the basis of support for the TR1 special functions.
Root Finding and Function Minimisation
A comprehensive set of root-finding algorithms over the real line, both with derivatives and derivative free.
Also function minimisation via Brent's Method.
Polynomials and Rational Functions
Tools for manipulating polynomials and for efficient evaluation of rationals or polynomials.
Interpolation
Function interpolation via barycentric rational interpolation, compactly supported quadartic, cubic, and quintic B-splines, the Chebyshev transform, trigonometric polynomials, Makima, pchip, and cubic Hermite splines.
Numerical Integration and Differentiation
A reasonably comprehensive set of routines for integration (trapezoidal, Gauss-Legendre, Gauss-Kronrod, Gauss-Chebyshev, double-exponential, and Monte-Carlo) and differentiation (Chebyshev transform, finite difference, the complex step derivative, and forward-mode automatic differentiation).
The integration routines are usable for functions returning complex results - and hence can be used for computation of contour integrals.
Quaternions and Octonions
Quaternion and Octonians as class templates similar to std::complex.
The full documentation is available on boost.org.
| Master | Develop | |
|---|---|---|
| Travis |  |
 |
| Appveyor |
Support, bugs and feature requests
Bugs and feature requests can be reported through the GitHub issue tracker (see open issues and closed issues).
You can submit your changes through a pull request.
There is no mailing-list specific to Boost Math, although you can use the general-purpose Boost mailing-list using the tag [math].
Development
Clone the whole boost project, which includes the individual Boost projects as submodules (see boost+git doc):
$ git clone https://github.com/boostorg/boost
$ cd boost
$ git submodule update --init
The Boost Math Library is located in libs/math/.
Running tests
First, make sure you are in libs/math/test.
You can either run all the tests listed in Jamfile.v2 or run a single test:
test$ ../../../b2 <- run all tests
test$ ../../../b2 static_assert_test <- single test
test$ # A more advanced syntax, demoing various options for building the tests:
test$ ../../../b2 -a -j2 -q --reconfigure toolset=clang cxxflags="--std=c++14 -fsanitize=address -fsanitize=undefined" linkflags="-fsanitize=undefined -fsanitize=address"
Building documentation
Full instructions can be found here, but to reiterate slightly:
libs/math/doc$ brew install docbook-xsl # on mac
libs/math/doc$ touch ~/user-config.jam
libs/math/doc$ # now edit so that:
libs/math/doc$ cat ~/user-config.jam
using darwin ;
using xsltproc ;
using boostbook
: /usr/local/opt/docbook-xsl/docbook-xsl
;
using doxygen ;
using quickbook ;
libs/math/doc$ ../../../b2