Boost
C++ Libraries
...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
Boost
C++ Libraries
...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
The Jacobi Theta functions are a set of four inter-related periodic functions of x which are expressed in terms of a parameter q (also called the nome), or a closely related value, τ [8] [9] [10].
They are
Plots of the four theta functions for q=0.15.
Appropriately multiplied and divided, these four theta functions can be used to implement the Jacobi elliptic functions; but this is not really recommended, as the existing Boost implementations are likely faster and more accurate.
Most applications will want to use the q parameterization
of the functions: jacobi_theta1,
jacobi_theta2,
jacobi_theta3,
and jacobi_theta4,
where q is restricted to the domain (0, 1). These four
functions are equivalent to Mathematica's EllipticTheta
function (whose first argument is the function number).
A second τ parameterization is also provided for all four functions, where
Note that there is a slight difference between τ in the equation above and
the tau in the Boost function
signatures. The mathematical τ is assumed to be a purely imaginary number,
but the Boost argument is real-valued. Boost treats its real-valued argument
as an imaginary number; that is, it implicitly multiplies the argument by
i. This assumption of τ's imaginarity is not required
by the mathematics, but it does cover the most common application domains.
The purpose of the τ parameterization is to provide increased accuracy either when q is expressible as an exponential or is very close to unity. For example, instead of:
jacobi_theta1(x, exp(-a));
A more accurate computation will take advantage of τ:
jacobi_theta1tau(x, a / boost::math::constants::pi<T>());
Internally, Boost implements the q parameterization by taking the logarithm of q and passing it to the τ parameterization; as such, using the τ parameterization directly will generally yield greater precision. As another example, if the complement of q is known with great accuracy, then instead of:
jacobi_theta1(x, 1-q_complement);
It is more accurate to use log1p
and pass in the result to the τ version:
jacobi_theta1tau(x, -boost::math::log1p(-q_complement) / boost::math::constants::pi<T>());
Additional "minus 1" versions of the third and fourth theta functions
are provided. Similar in spirit to expm1,
these functions return one less than the evaluated function, and yield increased
accuracy when q is small.
Results of the theta functions are tested against Wolfram Alpha data, as well as random values computed at high precision. In addition, the tests verify the majority of the identities described in DLMF Chapter 20.7.
