...one of the most highly
regarded and expertly designed C++ library projects in the
world.

— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards

This is the documentation for a snapshot of the develop branch, built from commit c255f452c6.

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.