|
Home | Libraries | People | FAQ | More |
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, when q is larger than exp(-π) (that is, when τ is less than 1), 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 in that regime. When q is smaller than exp(-π), the Fourier series is summed directly in terms of q, and the two parameterizations are equally accurate.
Every term of the series is an exponential whose argument is a product or
quotient of τ, π and a small integer, or, in the transformed series used when
τ < 1, the square of z plus a multiple of π/2. Rounding
such an argument to working precision would cost as many ulps in the term
as the argument is large, so the rounding errors of π, of the products, of
the division and of the reduction of z are tracked exactly
(using error-free transformations that work for any binary floating-point
type) and applied as a correction factor to each term. The τ parameterization
is therefore accurate to a few ulps throughout, apart from the conditioning
of the function itself, for z up to about 1/ε (1016 for
double); beyond that the reduction
of z by the period loses accuracy in proportion to
zε2. In the q parameterization the
rounding of log(q) remains, and its effect grows as
q approaches 1. 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.
All of the functions return the result of domain_error if z is not finite, if q lies outside (0, 1), or if τ is not strictly positive. A NaN argument is treated as a domain error.
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.
