Boost C++ Libraries

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.

Accuracy considerations

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.

Testing

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.