C++ Reference¶

Here follows the full C++ API reference, which currently consists of a single class w_elliptic::we nested in the namespace w_elliptic. The documentation is automatically generated from the source code using Doxygen and the Breathe extension for Sphinx.

template <typename T>

class w_elliptic::we¶

Class for the computation of Weierstrass elliptic and related functions.

This class is the main object to be used for the computation of Weierstrass elliptic and related functions. After construction from a pair of real invariants, it will be possible to call methods of this class to compute the desired functions.

Templates

T -
a supported real type (currently, float, double and long double).

The functionality of this class is built upon series expansions which have an implementation-defined hard limit for the number of iterations. Whenever this limit is reached, an std::runtime_error exception will be thrown.

Unless otherwise noted, this class adopts the DLMF conventions: http://dlmf.nist.gov/23.

Public Types

typedef T real_type¶: Alias for T.

typedef std::complex<real_type> complex_type¶: The complex counterpart of T.

Public Functions

we(const real_type &g2, const real_type &g3)¶

Constructor from invariants.

This constructor will initialise the object for the computation of Weierstrass elliptic and related functions defined in terms of the real invariants g2 and g3.

Parameters

g2 -
the first invariant.
g3 -
the second invariant.

Exceptions

std::invalid_argument -
if g2 and/or g3 are not finite.

we(const we&)¶: Defaulted copy constructor.

we(we&&)¶: Defaulted move constructor.

we &operator=(const we&)¶: Defaulted copy-assignment operator.

we &operator=(we&&)¶: Defaulted move-assignment operator.

const std::array<complex_type, 3> &roots() const¶

Roots.

This method will return a const reference to an internal array containing the three roots of the Weierstrass cubic

\[ 4t^3-g_2t-g_3. \]

The three roots \(e_1\), \(e_2\) and \(e_3\) contained in the array are ordered so that

\[ e_j=\wp\left(\omega_j\right), \]

where the \(\omega_j\) are the three half-periods (see we::periods()). The three roots also satisfy the condition

\[ e_1+e_2+e_3 = 0. \]

Return: a const reference to the array of roots of the Weierstrass cubic.
See: http://dlmf.nist.gov/23.3#i

const std::array<real_type, 2> &invariants() const¶

Invariants.

Return: a const reference to an array containing the two invariants \(g_2\) and \(g_3\) used for construction.

const std::array<complex_type, 2> &periods() const¶

Periods.

This method will return a const reference to an internal array containing the two periods \(2\omega_1\) and \(2\omega_3\) that generate a fundamental parallelogram associated to the invariants \(g_2\) and \(g_3\) used for construction.

The following properties are guaranteed:

\(2\omega_1\) is always real and positive,
\(2\omega_3\) is always complex, with a positive imaginary part,
if \(2\omega_3\) is not purely imaginary, then its real part is \(\omega_1\).

The first two properties imply that \(\Im\left(\omega_3/\omega_1\right)>0\). The half-periods \(\omega_1\) and \(\omega_3\) satisfy the property

\[ e_j=\wp\left(\omega_j\right), \]

where the \(e_j\) are the roots of the Weierstrass cubic (see we::roots()). The third half-period \(\omega_2\) is defined as

\[ \omega_2=-\omega_1-\omega_3, \]

and it also satisfies the property \(e_2=\wp\left(\omega_2\right)\).

Return: a const reference to the array of periods.
See: http://dlmf.nist.gov/23.2#i

const std::array<complex_type, 2> &etas() const¶

Eta constants.

This method will return a const reference to an internal array containing the two constants \(\eta_1\) and \(\eta_3\), defined as

\[ \eta_j = \zeta\left(\omega_j\right), \]

where \(\omega_j\) are the half-periods (see we::periods()) and \(\zeta\) the Weierstrass zeta function (see we::zeta()). These constants are used internally in the computation of the Weierstrassian functions. The first eta constant, \(\eta_1\), is guaranteed to be purely real.

Return: a const reference to the array of eta constants.
See: http://dlmf.nist.gov/23.2#iii
See: http://dlmf.nist.gov/23.6#i

const real_type &Delta() const¶

Discriminant.

Return: a const reference to the discriminant of the Weierstrass cubic (that is, \(16g_2^3-432g_3^2\)).

const complex_type &q() const¶

Nome.

The nome \(q\) is defined as:

\[ q = \exp{\left(\imath\pi\frac{\omega_3}{\omega_1}\right)}, \]

where \(\omega_1\) and \(\omega_3\) are the fundamental half-periods (see we::periods()). Due to the conventions adopted in the definition of the periods, \(q\) is always either purely real or purely imaginary.

Return: a const reference to the nome \(q\).

real_type P(const real_type &x) const¶

Weierstrass \(\wp\) function (real argument).

The implementation is based on Jacobi theta functions:

\[ \wp\left(z\right)=e_1+\left[\frac{\pi\theta_3\left(0,q\right)\theta_4\left(0,q\right)\theta_2\left(\frac{\pi z}{2\omega_1},q\right)}{2\omega_1\theta_1\left(\frac{\pi z}{2\omega_1},q\right)}\right]^2, \]

where \(q\) is the nome (see we::q()) and \(\omega_1\) the real half-period (see we::periods()). The implementation of this overload uses only real arithmetics.

Return

\(\wp\left(x;g_2,g_3\right)\), where \(x\in\mathbb{R}\).

See

http://dlmf.nist.gov/23.6#i

See

https://en.wikipedia.org/wiki/Theta_function

Parameters

x -
the real argument.

complex_type P(const complex_type &c) const¶

Weierstrass \(\wp\) function (complex argument).

The implementation is based on Jacobi theta functions:

\[ \wp\left(z\right)=e_1+\left[\frac{\pi\theta_3\left(0,q\right)\theta_4\left(0,q\right)\theta_2\left(\frac{\pi z}{2\omega_1},q\right)}{2\omega_1\theta_1\left(\frac{\pi z}{2\omega_1},q\right)}\right]^2, \]

where \(q\) is the nome (see we::q()) and \(\omega_1\) the real half-period (see we::periods()). The implementation of this overload uses complex arithmetics.

Return

\(\wp\left(c;g_2,g_3\right)\), where \(c\in\mathbb{C}\).

See

http://dlmf.nist.gov/23.6#i

See

https://en.wikipedia.org/wiki/Theta_function

Parameters

c -
the complex argument.

real_type Pprime(const real_type &x) const¶

Weierstrass \(\wp^\prime\) function (real argument).

The implementation is based on Jacobi theta functions:

\[ \wp^\prime\left(z\right)=\frac{d}{dz}\left[\frac{\pi\theta_3\left(0,q\right)\theta_4\left(0,q\right)\theta_2\left(\frac{\pi z}{2\omega_1},q\right)}{2\omega_1\theta_1\left(\frac{\pi z}{2\omega_1},q\right)}\right]^2, \]

where \(q\) is the nome (see we::q()) and \(\omega_1\) the real half-period (see we::periods()). The implementation of this overload uses only real arithmetics.

Return

\(\wp^\prime\left(x;g_2,g_3\right)\), where \(x\in\mathbb{R}\).

See

http://dlmf.nist.gov/23.6#i

See

https://en.wikipedia.org/wiki/Theta_function

Parameters

x -
the real argument.

complex_type Pprime(const complex_type &c) const¶

Weierstrass \(\wp^\prime\) function (complex argument).

The implementation is based on Jacobi theta functions:

\[ \wp^\prime\left(z\right)=\frac{d}{dz}\left[\frac{\pi\theta_3\left(0,q\right)\theta_4\left(0,q\right)\theta_2\left(\frac{\pi z}{2\omega_1},q\right)}{2\omega_1\theta_1\left(\frac{\pi z}{2\omega_1},q\right)}\right]^2, \]

where \(q\) is the nome (see we::q()) and \(\omega_1\) the real half-period (see we::periods()). The implementation of this overload uses complex arithmetics.

Return

\(\wp^\prime\left(c;g_2,g_3\right)\), where \(c\in\mathbb{C}\).

See

http://dlmf.nist.gov/23.6#i

See

https://en.wikipedia.org/wiki/Theta_function

Parameters

c -
the complex argument.

real_type zeta(const real_type &x) const¶

Weierstrass \(\zeta\) function (real argument).

The implementation is based on Jacobi theta functions:

\[ \zeta\left(u\right)=\frac{\eta_1}{\omega_1}u+\frac{\pi}{2\omega_1}\frac{d}{dz}\ln\theta_1\left(z,q\right), \]

where \(z=\frac{\pi u}{2\omega_1}\), \(q\) is the nome (see we::q()), \(\eta_1\) is the first eta constant (see we::etas()), and \(\omega_1\) the real half-period (see we::periods()). The implementation of this overload uses only real arithmetics.

Return

\(\zeta\left(x;g_2,g_3\right)\), where \(x\in\mathbb{R}\).

See

http://dlmf.nist.gov/23.6#i

See

https://en.wikipedia.org/wiki/Theta_function

Parameters

x -
the real argument.

complex_type zeta(const complex_type &c) const¶

Weierstrass \(\zeta\) function (complex argument).

The implementation is based on Jacobi theta functions:

\[ \zeta\left(u\right)=\frac{\eta_1}{\omega_1}u+\frac{\pi}{2\omega_1}\frac{d}{dz}\ln\theta_1\left(z,q\right), \]

where \(z=\frac{\pi u}{2\omega_1}\), \(q\) is the nome (see we::q()), \(\eta_1\) is the first eta constant (see we::etas()), and \(\omega_1\) the real half-period (see we::periods()). The implementation of this overload uses complex arithmetics.

Return

\(\zeta\left(c;g_2,g_3\right)\), where \(c\in\mathbb{C}\).

See

http://dlmf.nist.gov/23.6#i

See

https://en.wikipedia.org/wiki/Theta_function

Parameters

c -
the complex argument.

real_type sigma(const real_type &x) const¶

Weierstrass \(\sigma\) function (real argument).

The implementation is based on Jacobi theta functions:

\[ \sigma\left(z\right)=2\omega_1\exp{\left(\frac{\eta_1z^2}{2\omega_1}\right)}\frac{\theta_1\left(\frac{\pi z}{2\omega_1},q\right)}{\pi\theta_1^\prime\left(0,q\right)}, \]

where \(q\) is the nome (see we::q()), \(\eta_1\) is the first eta constant (see we::etas()), and \(\omega_1\) the real half-period (see we::periods()). The implementation of this overload uses only real arithmetics.

Return

\(\sigma\left(x;g_2,g_3\right)\), where \(x\in\mathbb{R}\).

See

http://dlmf.nist.gov/23.6#i

See

https://en.wikipedia.org/wiki/Theta_function

Parameters

x -
the real argument.

complex_type sigma(const complex_type &c) const¶

Weierstrass \(\sigma\) function (complex argument).

The implementation is based on Jacobi theta functions:

\[ \sigma\left(z\right)=2\omega_1\exp{\left(\frac{\eta_1z^2}{2\omega_1}\right)}\frac{\theta_1\left(\frac{\pi z}{2\omega_1},q\right)}{\pi\theta_1^\prime\left(0,q\right)}, \]

where \(q\) is the nome (see we::q()), \(\eta_1\) is the first eta constant (see we::etas()), and \(\omega_1\) the real half-period (see we::periods()). The implementation of this overload uses complex arithmetics.

Return

\(\sigma\left(c;g_2,g_3\right)\), where \(c\in\mathbb{C}\).

See

http://dlmf.nist.gov/23.6#i

See

https://en.wikipedia.org/wiki/Theta_function

Parameters

c -
the complex argument.

real_type ln_sigma_real(const complex_type &c) const¶

Real part of the logarithm of the sigma function.

This method returns:

\[ \Re{\left[\ln\sigma\left(z\right)\right]}, \]

where \(\sigma\) is the Weierstrass sigma function (see we::sigma()). If the imaginary part of \(z\) is in the range \(\left[0,\Im\left(\omega_3\right)\right]\), where \(\omega_3\) is the complex half-period (see we::periods()), the output of this function is guaranteed to be continuous when crossing the branch cut of the complex logarithm.

Return

\(\Re{\left[\ln\sigma\left(c;g_2,g_3\right)\right]}\).

Parameters

c -
the complex argument.

real_type ln_sigma_imag(const complex_type &c) const¶

Imaginary part of the logarithm of the sigma function.

This method returns:

\[ \Im{\left[\ln\sigma\left(z\right)\right]}, \]

where \(\sigma\) is the Weierstrass sigma function (see we::sigma()). If the imaginary part of \(z\) is in the range \(\left[0,\Im\left(\omega_3\right)\right]\), where \(\omega_3\) is the complex half-period (see we::periods()), the output of this function is guaranteed to be continuous when crossing the branch cut of the complex logarithm.

Return

\(\Im{\left[\ln\sigma\left(c;g_2,g_3\right)\right]}\).

Parameters

c -
the complex argument.

std::array<complex_type, 2> Pinv(const complex_type &c) const¶

Inverse \(\wp\) function.

This method will return an array containing the two values \(z_j\) within the fundamental parallelogram that satisfy

\[ \wp\left(z_j\right) = c. \]

The implementation is based on the following relation between \(\wp\) and the Jacobi elliptic function \(\mathrm{cs}\):

\[ \wp\left(z\right)-e_1=\frac{K^2}{\omega_1^2}\mathrm{cs}^2\left(\frac{Kz}{\omega_1},k\right), \]

where

\[ k^2 = \frac{e_2-e_3}{e_1-e_3}, \]

\[ K = \omega_1^2\left(e_1-e_3\right), \]

the \(e_j\) are the roots of the Weierstrass cubic (see we::roots()) and \(\omega_1\) is the real half-period (see we::periods()). The relation in terms of \(\mathrm{cs}\) is inverted to yield an expression of \(\wp^{-1}\) in terms of an elliptic integral computed via a Landen transformation.

The following guarantees are provided for the returned values:

they are always contained within the fundamental parallelogram defined by the periods (see we::periods()),
if the input value c is purely real and greater than \(e_1\), then the two results will be purely real and sorted in ascending order,
otherwise, the two results are sorted in ascending order according to their imaginary part.

Return

an array of two values \(z_j\) such that \(\wp\left(z_j\right) = c\).

See

http://dlmf.nist.gov/23.6#ii

See

https://en.wikipedia.org/wiki/Jacobi_elliptic_functions

See