GeographicLib: GeographicLib::EllipticFunction Class Reference (original) (raw)

Elliptic integrals and functions. More...

#include <[GeographicLib/EllipticFunction.hpp](EllipticFunction%5F8hpp%5Fsource.html)>

Elliptic integrals and functions.

This provides the elliptic functions and integrals needed for Ellipsoid, GeodesicExact, and TransverseMercatorExact. Two categories of function are provided:

• static functions to compute symmetric elliptic integrals (https://dlmf.nist.gov/19.16.i)
• member functions to compute Legrendre's elliptic integrals (https://dlmf.nist.gov/19.2.ii) and the Jacobi elliptic functions (https://dlmf.nist.gov/22.2).

In the latter case, an object is constructed giving the modulus k (and optionally the parameter α2). The modulus is always passed as its square _k_2 which allows k to be pure imaginary (_k_2 < 0). (Confusingly, Abramowitz and Stegun call m = _k_2 the "parameter" and n = α2 the "characteristic".)

In geodesic applications, it is convenient to separate the incomplete integrals into secular and periodic components, e.g.,

\[ E(\phi, k) = (2 E(k) / \pi) [ \phi + \delta E(\phi, k) ] \]

where δ_E_(φ, k) is an odd periodic function with period π.

The computation of the elliptic integrals uses the algorithms given in

• B. C. Carlson, Computation of real or complex elliptic integrals, Numerical Algorithms 10, 13–26 (1995); preprint.

with the additional optimizations given in https://dlmf.nist.gov/19.36.i. The computation of the Jacobi elliptic functions uses the algorithm given in

• R. Bulirsch, Numerical Calculation of Elliptic Integrals and Elliptic Functions, Numericshe Mathematik 7, 78–90 (1965).

The notation follows https://dlmf.nist.gov/19 and https://dlmf.nist.gov/22

Example of use:

#include

#include

#include

#include

using namespace std;

try {

cout << ell.K() << " " << ell.E() << "\n";

double phi = 20, sn, cn;

Math::sincosd(phi, sn ,cn);

cout << ell.E(phi * Math::degree()) << " "

<< ell.E(sn, cn, ell.Delta(sn, cn))

<< "\n";

cout << fixed << setprecision(16)

<< "RF(1,2,0) = " << EllipticFunction::RF(1,2) << "\n"

<< "RF(2,3,4) = " << EllipticFunction::RF(2,3,4) << "\n"

<< "RC(0,1/4) = " << EllipticFunction::RC(0,0.25) << "\n"

<< "RC(9/4,2) = " << EllipticFunction::RC(2.25,2) << "\n"

<< "RC(1/4,-2) = " << EllipticFunction::RC(0.25,-2) << "\n"

<< "RJ(0,1,2,3) = " << EllipticFunction::RJ(0,1,2,3) << "\n"

<< "RJ(2,3,4,5) = " << EllipticFunction::RJ(2,3,4,5) << "\n"

<< "RD(0,2,1) = " << EllipticFunction::RD(0,2,1) << "\n"

<< "RD(2,3,4) = " << EllipticFunction::RD(2,3,4) << "\n"

<< "RG(0,16,16) = " << EllipticFunction::RG(16,16) << "\n"

<< "RG(2,3,4) = " << EllipticFunction::RG(2,3,4) << "\n"

<< "RG(0,0.0796,4) = " << EllipticFunction::RG(0.0796,4) << "\n";

}

catch (const exception& e) {

cout << "Caught exception: " << e.what() << "\n";

}

}

int main(int argc, const char *const argv[])

Header for GeographicLib::EllipticFunction class.

Header for GeographicLib::Math class.

Elliptic integrals and functions.

Namespace for GeographicLib.

Definition at line 63 of file EllipticFunction.hpp.

Constructor specifying the modulus and parameter.

Parameters

Exceptions

If only elliptic integrals of the first and second kinds are needed, then set α2 = 0 (the default value); in this case, we have Π(φ, 0, k) = F(φ, k), G(φ, 0, k) = E(φ, k), and H(φ, 0, k) = F(φ, k) - D(φ, k).

Definition at line 90 of file EllipticFunction.hpp.

◆ EllipticFunction() [2/2]

Constructor specifying the modulus and parameter and their complements.

Parameters

Exceptions

The arguments must satisfy k2 + kp2 = 1 and alpha2 + alphap2 = 1. (No checking is done that these conditions are met.) This constructor is provided to enable accuracy to be maintained, e.g., when k is very close to unity.

Definition at line 112 of file EllipticFunction.hpp.

◆ Reset() [1/2]

Reset the modulus and parameter.

Parameters

Exceptions

Definition at line 126 of file EllipticFunction.hpp.

◆ Reset() [2/2]

Reset the modulus and parameter supplying also their complements.

Parameters

Exceptions

The arguments must satisfy k2 + kp2 = 1 and alpha2 + alphap2 = 1. (No checking is done that these conditions are met.) This constructor is provided to enable accuracy to be maintained, e.g., when is very small.

Definition at line 221 of file EllipticFunction.cpp.

References alpha2(), alphap2(), GeographicLib::Math::infinity(), k2(), kp2(), GeographicLib::Math::pi(), RC(), RD(), RF(), RG(), RJ(), and GeographicLib::Math::sq().

◆ k2()

◆ kp2()

◆ alpha2()

◆ alphap2()

◆ K()

◆ E() [1/3]

◆ D() [1/3]

◆ KE()

◆ Pi() [1/3]

The complete integral of the third kind.

Returns

Π(α2, k).

Π(α2, k) is defined in https://dlmf.nist.gov/19.2.E7

\[ \Pi(\alpha^2, k) = \int_0^{\pi/2} \frac1{\sqrt{1-k^2\sin^2\phi}(1 - \alpha^2\sin^2\phi)}\,d\phi. \]

Definition at line 238 of file EllipticFunction.hpp.

Referenced by deltaPi(), Pi(), Pi(), GeographicLib::experimental::JacobiConformal::x(), GeographicLib::experimental::JacobiConformal::x(), GeographicLib::experimental::JacobiConformal::y(), and GeographicLib::experimental::JacobiConformal::y().

◆ G() [1/3]

Legendre's complete geodesic longitude integral.

Returns

G(α2, k).

G(α2, k) is given by

\[ G(\alpha^2, k) = \int_0^{\pi/2} \frac{\sqrt{1-k^2\sin^2\phi}}{1 - \alpha^2\sin^2\phi}\,d\phi. \]

Definition at line 251 of file EllipticFunction.hpp.

Referenced by deltaG(), G(), and G().

◆ H() [1/3]

Cayley's complete geodesic longitude difference integral.

Returns

H(α2, k).

H(α2, k) is given by

\[ H(\alpha^2, k) = \int_0^{\pi/2} \frac{\cos^2\phi}{(1-\alpha^2\sin^2\phi)\sqrt{1-k^2\sin^2\phi}} \,d\phi. \]

Definition at line 265 of file EllipticFunction.hpp.

Referenced by deltaH(), H(), and H().

◆ F() [1/2]

◆ E() [2/3]

◆ Ed()

◆ Einv()

◆ Pi() [2/3]

The incomplete integral of the third kind.

Parameters

Returns

Π(φ, α2, k).

Π(φ, α2, k) is defined in https://dlmf.nist.gov/19.2.E7

\[ \Pi(\phi, \alpha^2, k) = \int_0^\phi \frac1{\sqrt{1-k^2\sin^2\theta}(1 - \alpha^2\sin^2\theta)}\,d\theta. \]

Definition at line 583 of file EllipticFunction.cpp.

References Delta(), deltaPi(), GeographicLib::Math::pi(), and Pi().

◆ D() [2/3]

◆ G() [2/3]

Legendre's geodesic longitude integral.

Parameters

Returns

G(φ, α2, k).

G(φ, α2, k) is defined by

\[ \begin{align} G(\phi, \alpha^2, k) &= \frac{k^2}{\alpha^2} F(\phi, k) + \biggl(1 - \frac{k^2}{\alpha^2}\biggr) \Pi(\phi, \alpha^2, k) \\ &= \int_0^\phi \frac{\sqrt{1-k^2\sin^2\theta}}{1 - \alpha^2\sin^2\theta}\,d\theta. \end{align} \]

Legendre expresses the longitude of a point on the geodesic in terms of this combination of elliptic integrals in Exercices de Calcul Intégral, Vol. 1 (1811), p. 181, https://books.google.com/books?id=riIOAAAAQAAJ&pg=PA181.

See Geodesics in terms of elliptic integrals for the expression for the longitude in terms of this function.

Definition at line 595 of file EllipticFunction.cpp.

References Delta(), deltaG(), G(), and GeographicLib::Math::pi().

◆ H() [2/3]

Cayley's geodesic longitude difference integral.

Parameters

Returns

H(φ, α2, k).

H(φ, α2, k) is defined by

\[ \begin{align} H(\phi, \alpha^2, k) &= \frac1{\alpha^2} F(\phi, k) + \biggl(1 - \frac1{\alpha^2}\biggr) \Pi(\phi, \alpha^2, k) \\ &= \int_0^\phi \frac{\cos^2\theta} {(1-\alpha^2\sin^2\theta)\sqrt{1-k^2\sin^2\theta}} \,d\theta. \end{align} \]

Cayley expresses the longitude difference of a point on the geodesic in terms of this combination of elliptic integrals in Phil. Mag. 40 (1870), p. 333, https://books.google.com/books?id=Zk0wAAAAIAAJ&pg=PA333.

See Geodesics in terms of elliptic integrals for the expression for the longitude in terms of this function.

Definition at line 601 of file EllipticFunction.cpp.

References Delta(), deltaH(), H(), and GeographicLib::Math::pi().

◆ F() [2/2]

The incomplete integral of the first kind in terms of Jacobi elliptic functions.

Parameters

Returns

F(φ, k) as though φ ∈ (−π, π].

Definition at line 429 of file EllipticFunction.cpp.

References K(), and RF().

◆ E() [3/3]

The incomplete integral of the second kind in terms of Jacobi elliptic functions.

Parameters

Returns

E(φ, k) as though φ ∈ (−π, π].

Definition at line 440 of file EllipticFunction.cpp.

References E(), RD(), and RF().

◆ Pi() [3/3]

The incomplete integral of the third kind in terms of Jacobi elliptic functions.

Parameters

Returns

Π(φ, α2, k) as though φ ∈ (−π, π].

Definition at line 475 of file EllipticFunction.cpp.

References Pi(), RF(), and RJ().

◆ D() [3/3]

Jahnke's incomplete elliptic integral in terms of Jacobi elliptic functions.

Parameters

Returns

D(φ, k) as though φ ∈ (−π, π].

Definition at line 463 of file EllipticFunction.cpp.

References D(), and RD().

◆ G() [3/3]

Legendre's geodesic longitude integral in terms of Jacobi elliptic functions.

Parameters

Returns

G(φ, α2, k) as though φ ∈ (−π, π].

Definition at line 490 of file EllipticFunction.cpp.

References G(), RF(), and RJ().

◆ H() [3/3]

Cayley's geodesic longitude difference integral in terms of Jacobi elliptic functions.

Parameters

Returns

H(φ, α2, k) as though φ ∈ (−π, π].

Definition at line 503 of file EllipticFunction.cpp.

References H(), RF(), and RJ().

◆ deltaF()

The periodic incomplete integral of the first kind.

Parameters

Returns

the periodic function π F(φ, k) / (2 K(k)) - φ.

Definition at line 517 of file EllipticFunction.cpp.

References F(), K(), and GeographicLib::Math::pi().

Referenced by F().

◆ deltaE()

◆ deltaEinv()

◆ deltaPi()

The periodic incomplete integral of the third kind.

Parameters

Returns

the periodic function π Π(φ, α2, k) / (2 Π(α2, k)) - φ.

Definition at line 529 of file EllipticFunction.cpp.

References GeographicLib::Math::pi(), and Pi().

Referenced by Pi().

◆ deltaD()

◆ deltaG()

Legendre's periodic geodesic longitude integral.

Parameters

Returns

the periodic function π G(φ, k) / (2 G(k)) - φ.

Definition at line 541 of file EllipticFunction.cpp.

References G(), and GeographicLib::Math::pi().

Referenced by G().

◆ deltaH()

◆ am() [1/2]

◆ am() [2/2]

The Jacobi amplitude function and associated elliptic functions.

Parameters

Returns

the value of am(x, k)

Definition at line 414 of file EllipticFunction.cpp.

References am(), and Delta().

◆ sncndn()

The Jacobi elliptic functions.

Parameters

For this routine k is restricted to the interval [0, 1].

Definition at line 315 of file EllipticFunction.cpp.

References GEOGRAPHICLIB_PANIC, and std::swap().

◆ Delta()

The Δ amplitude function.

Parameters

Returns

Δ = sqrt(1 − _k_2 sin2φ).

Definition at line 607 of file EllipticFunction.hpp.

Referenced by am(), D(), E(), Ed(), Einv(), F(), G(), GeographicLib::GeodesicLineExact::GenPosition(), H(), Pi(), GeographicLib::experimental::JacobiConformal::x(), and GeographicLib::experimental::JacobiConformal::y().

◆ RF() [1/2]

Symmetric integral of the first kind R F.

Parameters

Returns

R F(x, y, z).

R F is defined in https://dlmf.nist.gov/19.16.E1

\[ R_F(x, y, z) = \frac12 \int_0^\infty\frac1{\sqrt{(t + x) (t + y) (t + z)}}\, dt, \]

where at most one of arguments, x, y, z, can be zero and those arguments that are nonzero must be positive. If one of the arguments is zero, it is more efficient to call the two-argument version of this function with the non-zero arguments.

Definition at line 24 of file EllipticFunction.cpp.

Referenced by E(), F(), G(), H(), Pi(), GeographicLib::AuxLatitude::Rectifying(), Reset(), and RG().

◆ RF() [2/2]

◆ RC()

Degenerate symmetric integral of the first kind R C.

Parameters

Returns

R C(x, y) = R F(x, y, y).

R C is defined in https://dlmf.nist.gov/19.2.E17

\[ R_C(x, y) = \frac12 \int_0^\infty\frac1{\sqrt{t + x}(t + y)}\,dt, \]

where x ≥ 0 and y > 0.

Definition at line 76 of file EllipticFunction.cpp.

Referenced by Reset(), and RJ().

◆ RG() [1/2]

Symmetric integral of the second kind R G.

Parameters

Returns

R G(x, y, z).

R G is defined in Carlson, eq 1.5

\[ R_G(x, y, z) = \frac14 \int_0^\infty[(t + x) (t + y) (t + z)]^{-1/2} \biggl( \frac x{t + x} + \frac y{t + y} + \frac z{t + z} \biggr)t\,dt, \]

where at most one of arguments, x, y, z, can be zero and those arguments that are nonzero must be positive. See also https://dlmf.nist.gov/19.23.E6_5. If one of the arguments is zero, it is more efficient to call the two-argument version of this function with the non-zero arguments.

Definition at line 91 of file EllipticFunction.cpp.

References RD(), RF(), and RG().

Referenced by GeographicLib::AuxLatitude::RectifyingRadius(), Reset(), and RG().

◆ RG() [2/2]

◆ RJ()

Symmetric integral of the third kind R J.

Parameters

Returns

R J(x, y, z, p).

R J is defined in https://dlmf.nist.gov/19.16.E2

\[ R_J(x, y, z, p) = \frac32 \int_0^\infty [(t + x) (t + y) (t + z)]^{-1/2} (t + p)^{-1}\, dt, \]

where p > 0, and x, y, z are nonnegative with at most one of them being 0.

Definition at line 123 of file EllipticFunction.cpp.

References RC(), and GeographicLib::Math::sq().

Referenced by G(), H(), Pi(), and Reset().

◆ RD()

Degenerate symmetric integral of the third kind R D.

Parameters

Returns

R D(x, y, z) = R J(x, y, z, z).

R D is defined in https://dlmf.nist.gov/19.16.E5

\[ R_D(x, y, z) = \frac32 \int_0^\infty[(t + x) (t + y)]^{-1/2} (t + z)^{-3/2}\, dt, \]

where x, y, z are positive except that at most one of x and y can be 0.

Definition at line 177 of file EllipticFunction.cpp.

Referenced by D(), E(), GeographicLib::AuxLatitude::Rectifying(), Reset(), and RG().

The documentation for this class was generated from the following files:

• EllipticFunction.hpp
• EllipticFunction.cpp