GeographicLib
1.47
|
Elliptic integrals and functions. More...
#include <GeographicLib/EllipticFunction.hpp>
Public Member Functions | |
Constructor | |
EllipticFunction (real k2=0, real alpha2=0) | |
EllipticFunction (real k2, real alpha2, real kp2, real alphap2) | |
void | Reset (real k2=0, real alpha2=0) |
void | Reset (real k2, real alpha2, real kp2, real alphap2) |
Inspector functions. | |
Math::real | k2 () const |
Math::real | kp2 () const |
Math::real | alpha2 () const |
Math::real | alphap2 () const |
Complete elliptic integrals. | |
Math::real | K () const |
Math::real | E () const |
Math::real | D () const |
Math::real | KE () const |
Math::real | Pi () const |
Math::real | G () const |
Math::real | H () const |
Incomplete elliptic integrals. | |
Math::real | F (real phi) const |
Math::real | E (real phi) const |
Math::real | Ed (real ang) const |
Math::real | Einv (real x) const |
Math::real | Pi (real phi) const |
Math::real | D (real phi) const |
Math::real | G (real phi) const |
Math::real | H (real phi) const |
Incomplete integrals in terms of Jacobi elliptic functions. | |
Math::real | F (real sn, real cn, real dn) const |
Math::real | E (real sn, real cn, real dn) const |
Math::real | Pi (real sn, real cn, real dn) const |
Math::real | D (real sn, real cn, real dn) const |
Math::real | G (real sn, real cn, real dn) const |
Math::real | H (real sn, real cn, real dn) const |
Periodic versions of incomplete elliptic integrals. | |
Math::real | deltaF (real sn, real cn, real dn) const |
Math::real | deltaE (real sn, real cn, real dn) const |
Math::real | deltaEinv (real stau, real ctau) const |
Math::real | deltaPi (real sn, real cn, real dn) const |
Math::real | deltaD (real sn, real cn, real dn) const |
Math::real | deltaG (real sn, real cn, real dn) const |
Math::real | deltaH (real sn, real cn, real dn) const |
Elliptic functions. | |
void | sncndn (real x, real &sn, real &cn, real &dn) const |
Math::real | Delta (real sn, real cn) const |
Static Public Member Functions | |
Symmetric elliptic integrals. | |
static real | RF (real x, real y, real z) |
static real | RF (real x, real y) |
static real | RC (real x, real y) |
static real | RG (real x, real y, real z) |
static real | RG (real x, real y) |
static real | RJ (real x, real y, real z, real p) |
static real | RD (real x, real y, real z) |
Elliptic integrals and functions.
This provides the elliptic functions and integrals needed for Ellipsoid, GeodesicExact, and TransverseMercatorExact. Two categories of function are provided:
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 k2 which allows k to be pure imaginary (k2 < 0). (Confusingly, Abramowitz and Stegun call m = k2 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
with the additional optimizations given in http://dlmf.nist.gov/19.36.i. The computation of the Jacobi elliptic functions uses the algorithm given in
The notation follows http://dlmf.nist.gov/19 and http://dlmf.nist.gov/22
Example of use:
Definition at line 62 of file EllipticFunction.hpp.
|
inline |
Constructor specifying the modulus and parameter.
[in] | k2 | the square of the modulus k2. k2 must lie in (−∞, 1]. |
[in] | alpha2 | the parameter α2. α2 must lie in (−∞, 1]. |
GeographicErr | if k2 or alpha2 is out of its legal range. |
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 88 of file EllipticFunction.hpp.
|
inline |
Constructor specifying the modulus and parameter and their complements.
[in] | k2 | the square of the modulus k2. k2 must lie in (−∞, 1]. |
[in] | alpha2 | the parameter α2. α2 must lie in (−∞, 1]. |
[in] | kp2 | the complementary modulus squared k'2 = 1 − k2. This must lie in [0, ∞). |
[in] | alphap2 | the complementary parameter α'2 = 1 − α2. This must lie in [0, ∞). |
GeographicErr | if k2, alpha2, kp2, or alphap2 is out of its legal range. |
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 110 of file EllipticFunction.hpp.
|
inline |
Reset the modulus and parameter.
[in] | k2 | the new value of square of the modulus k2 which must lie in (−∞, ]. done.) |
[in] | alpha2 | the new value of parameter α2. α2 must lie in (−∞, 1]. |
GeographicErr | if k2 or alpha2 is out of its legal range. |
Definition at line 124 of file EllipticFunction.hpp.
Referenced by GeographicLib::GeodesicExact::InverseLine().
void GeographicLib::EllipticFunction::Reset | ( | real | k2, |
real | alpha2, | ||
real | kp2, | ||
real | alphap2 | ||
) |
Reset the modulus and parameter supplying also their complements.
[in] | k2 | the square of the modulus k2. k2 must lie in (−∞, 1]. |
[in] | alpha2 | the parameter α2. α2 must lie in (−∞, 1]. |
[in] | kp2 | the complementary modulus squared k'2 = 1 − k2. This must lie in [0, ∞). |
[in] | alphap2 | the complementary parameter α'2 = 1 − α2. This must lie in [0, ∞). |
GeographicErr | if k2, alpha2, kp2, or alphap2 is out of its legal range. |
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 222 of file EllipticFunction.cpp.
References GeographicLib::Math::infinity(), GeographicLib::Math::pi(), and GeographicLib::Math::sq().
|
inline |
Definition at line 156 of file EllipticFunction.hpp.
Referenced by GeographicLib::Rhumb::GenDirect(), and GeographicLib::GeodesicExact::InverseLine().
|
inline |
Definition at line 162 of file EllipticFunction.hpp.
|
inline |
Definition at line 167 of file EllipticFunction.hpp.
|
inline |
Definition at line 173 of file EllipticFunction.hpp.
|
inline |
The complete integral of the first kind.
K(k) is defined in http://dlmf.nist.gov/19.2.E4
\[ K(k) = \int_0^{\pi/2} \frac1{\sqrt{1-k^2\sin^2\phi}}\,d\phi. \]
Definition at line 189 of file EllipticFunction.hpp.
Referenced by GeographicLib::TransverseMercatorExact::Forward(), GeographicLib::TransverseMercatorExact::Reverse(), and GeographicLib::TransverseMercatorExact::UTM().
|
inline |
The complete integral of the second kind.
E(k) is defined in http://dlmf.nist.gov/19.2.E5
\[ E(k) = \int_0^{\pi/2} \sqrt{1-k^2\sin^2\phi}\,d\phi. \]
Definition at line 201 of file EllipticFunction.hpp.
Referenced by GeographicLib::TransverseMercatorExact::Forward(), GeographicLib::Rhumb::GenDirect(), GeographicLib::GeodesicExact::InverseLine(), GeographicLib::Ellipsoid::InverseRectifyingLatitude(), GeographicLib::Ellipsoid::QuarterMeridian(), GeographicLib::TransverseMercatorExact::Reverse(), and GeographicLib::TransverseMercatorExact::UTM().
|
inline |
Jahnke's complete integral.
D(k) is defined in http://dlmf.nist.gov/19.2.E6
\[ D(k) = \int_0^{\pi/2} \frac{\sin^2\phi}{\sqrt{1-k^2\sin^2\phi}}\,d\phi. \]
Definition at line 213 of file EllipticFunction.hpp.
Referenced by GeographicLib::GeodesicExact::InverseLine().
|
inline |
The difference between the complete integrals of the first and second kinds.
Definition at line 221 of file EllipticFunction.hpp.
Referenced by GeographicLib::TransverseMercatorExact::Reverse(), and GeographicLib::TransverseMercatorExact::UTM().
|
inline |
The complete integral of the third kind.
Π(α2, k) is defined in http://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 235 of file EllipticFunction.hpp.
Referenced by GeographicLib::JacobiConformal::x(), and GeographicLib::JacobiConformal::y().
|
inline |
Legendre's complete geodesic longitude integral.
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 248 of file EllipticFunction.hpp.
|
inline |
Cayley's complete geodesic longitude difference integral.
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 262 of file EllipticFunction.hpp.
Referenced by GeographicLib::GeodesicExact::InverseLine().
Math::real GeographicLib::EllipticFunction::F | ( | real | phi | ) | const |
The incomplete integral of the first kind.
[in] | phi |
F(φ, k) is defined in http://dlmf.nist.gov/19.2.E4
\[ F(\phi, k) = \int_0^\phi \frac1{\sqrt{1-k^2\sin^2\theta}}\,d\theta. \]
Definition at line 490 of file EllipticFunction.cpp.
References GeographicLib::Math::pi().
Math::real GeographicLib::EllipticFunction::E | ( | real | phi | ) | const |
The incomplete integral of the second kind.
[in] | phi |
E(φ, k) is defined in http://dlmf.nist.gov/19.2.E5
\[ E(\phi, k) = \int_0^\phi \sqrt{1-k^2\sin^2\theta}\,d\theta. \]
Definition at line 496 of file EllipticFunction.cpp.
References GeographicLib::Math::pi().
Math::real GeographicLib::EllipticFunction::Ed | ( | real | ang | ) | const |
The incomplete integral of the second kind with the argument given in degrees.
[in] | ang | in degrees. |
Definition at line 502 of file EllipticFunction.cpp.
References GeographicLib::Math::sincosd().
Referenced by GeographicLib::Ellipsoid::MeridianDistance().
Math::real GeographicLib::EllipticFunction::Einv | ( | real | x | ) | const |
The inverse of the incomplete integral of the second kind.
[in] | x |
Definition at line 534 of file EllipticFunction.cpp.
References GEOGRAPHICLIB_PANIC, and GeographicLib::Math::pi().
Referenced by GeographicLib::Ellipsoid::InverseRectifyingLatitude().
Math::real GeographicLib::EllipticFunction::Pi | ( | real | phi | ) | const |
The incomplete integral of the third kind.
[in] | phi |
Π(φ, α2, k) is defined in http://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 510 of file EllipticFunction.cpp.
References GeographicLib::Math::pi().
Math::real GeographicLib::EllipticFunction::D | ( | real | phi | ) | const |
Jahnke's incomplete elliptic integral.
[in] | phi |
D(φ, k) is defined in http://dlmf.nist.gov/19.2.E4
\[ D(\phi, k) = \int_0^\phi \frac{\sin^2\theta}{\sqrt{1-k^2\sin^2\theta}}\,d\theta. \]
Definition at line 516 of file EllipticFunction.cpp.
References GeographicLib::Math::pi().
Math::real GeographicLib::EllipticFunction::G | ( | real | phi | ) | const |
Legendre's geodesic longitude integral.
[in] | phi |
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 522 of file EllipticFunction.cpp.
References GeographicLib::Math::pi().
Math::real GeographicLib::EllipticFunction::H | ( | real | phi | ) | const |
Cayley's geodesic longitude difference integral.
[in] | phi |
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 528 of file EllipticFunction.cpp.
References GeographicLib::Math::pi().
Math::real GeographicLib::EllipticFunction::F | ( | real | sn, |
real | cn, | ||
real | dn | ||
) | const |
The incomplete integral of the first kind in terms of Jacobi elliptic functions.
[in] | sn | = sinφ. |
[in] | cn | = cosφ. |
[in] | dn | = sqrt(1 − k2 sin2φ). |
Definition at line 367 of file EllipticFunction.cpp.
References GeographicLib::Math::copysign().
Math::real GeographicLib::EllipticFunction::E | ( | real | sn, |
real | cn, | ||
real | dn | ||
) | const |
The incomplete integral of the second kind in terms of Jacobi elliptic functions.
[in] | sn | = sinφ. |
[in] | cn | = cosφ. |
[in] | dn | = sqrt(1 − k2 sin2φ). |
Definition at line 378 of file EllipticFunction.cpp.
References GeographicLib::Math::copysign().
Math::real GeographicLib::EllipticFunction::Pi | ( | real | sn, |
real | cn, | ||
real | dn | ||
) | const |
The incomplete integral of the third kind in terms of Jacobi elliptic functions.
[in] | sn | = sinφ. |
[in] | cn | = cosφ. |
[in] | dn | = sqrt(1 − k2 sin2φ). |
Definition at line 412 of file EllipticFunction.cpp.
References GeographicLib::Math::copysign().
Math::real GeographicLib::EllipticFunction::D | ( | real | sn, |
real | cn, | ||
real | dn | ||
) | const |
Jahnke's incomplete elliptic integral in terms of Jacobi elliptic functions.
[in] | sn | = sinφ. |
[in] | cn | = cosφ. |
[in] | dn | = sqrt(1 − k2 sin2φ). |
Definition at line 400 of file EllipticFunction.cpp.
References GeographicLib::Math::copysign().
Math::real GeographicLib::EllipticFunction::G | ( | real | sn, |
real | cn, | ||
real | dn | ||
) | const |
Legendre's geodesic longitude integral in terms of Jacobi elliptic functions.
[in] | sn | = sinφ. |
[in] | cn | = cosφ. |
[in] | dn | = sqrt(1 − k2 sin2φ). |
Definition at line 427 of file EllipticFunction.cpp.
References GeographicLib::Math::copysign().
Math::real GeographicLib::EllipticFunction::H | ( | real | sn, |
real | cn, | ||
real | dn | ||
) | const |
Cayley's geodesic longitude difference integral in terms of Jacobi elliptic functions.
[in] | sn | = sinφ. |
[in] | cn | = cosφ. |
[in] | dn | = sqrt(1 − k2 sin2φ). |
Definition at line 440 of file EllipticFunction.cpp.
References GeographicLib::Math::copysign().
Math::real GeographicLib::EllipticFunction::deltaF | ( | real | sn, |
real | cn, | ||
real | dn | ||
) | const |
The periodic incomplete integral of the first kind.
[in] | sn | = sinφ. |
[in] | cn | = cosφ. |
[in] | dn | = sqrt(1 − k2 sin2φ). |
Definition at line 454 of file EllipticFunction.cpp.
References GeographicLib::Math::pi().
Math::real GeographicLib::EllipticFunction::deltaE | ( | real | sn, |
real | cn, | ||
real | dn | ||
) | const |
The periodic incomplete integral of the second kind.
[in] | sn | = sinφ. |
[in] | cn | = cosφ. |
[in] | dn | = sqrt(1 − k2 sin2φ). |
Definition at line 460 of file EllipticFunction.cpp.
References GeographicLib::Math::pi().
Referenced by GeographicLib::GeodesicExact::InverseLine().
Math::real GeographicLib::EllipticFunction::deltaEinv | ( | real | stau, |
real | ctau | ||
) | const |
The periodic inverse of the incomplete integral of the second kind.
[in] | stau | = sinτ. |
[in] | ctau | = sinτ. |
Definition at line 558 of file EllipticFunction.cpp.
References GeographicLib::Math::pi().
Math::real GeographicLib::EllipticFunction::deltaPi | ( | real | sn, |
real | cn, | ||
real | dn | ||
) | const |
The periodic incomplete integral of the third kind.
[in] | sn | = sinφ. |
[in] | cn | = cosφ. |
[in] | dn | = sqrt(1 − k2 sin2φ). |
Definition at line 466 of file EllipticFunction.cpp.
References GeographicLib::Math::pi().
Math::real GeographicLib::EllipticFunction::deltaD | ( | real | sn, |
real | cn, | ||
real | dn | ||
) | const |
The periodic Jahnke's incomplete elliptic integral.
[in] | sn | = sinφ. |
[in] | cn | = cosφ. |
[in] | dn | = sqrt(1 − k2 sin2φ). |
Definition at line 472 of file EllipticFunction.cpp.
References GeographicLib::Math::pi().
Referenced by GeographicLib::GeodesicExact::InverseLine().
Math::real GeographicLib::EllipticFunction::deltaG | ( | real | sn, |
real | cn, | ||
real | dn | ||
) | const |
Legendre's periodic geodesic longitude integral.
[in] | sn | = sinφ. |
[in] | cn | = cosφ. |
[in] | dn | = sqrt(1 − k2 sin2φ). |
Definition at line 478 of file EllipticFunction.cpp.
References GeographicLib::Math::pi().
Math::real GeographicLib::EllipticFunction::deltaH | ( | real | sn, |
real | cn, | ||
real | dn | ||
) | const |
Cayley's periodic geodesic longitude difference integral.
[in] | sn | = sinφ. |
[in] | cn | = cosφ. |
[in] | dn | = sqrt(1 − k2 sin2φ). |
Definition at line 484 of file EllipticFunction.cpp.
References GeographicLib::Math::pi().
Referenced by GeographicLib::GeodesicExact::InverseLine().
void GeographicLib::EllipticFunction::sncndn | ( | real | x, |
real & | sn, | ||
real & | cn, | ||
real & | dn | ||
) | const |
The Jacobi elliptic functions.
[in] | x | the argument. |
[out] | sn | sn(x, k). |
[out] | cn | cn(x, k). |
[out] | dn | dn(x, k). |
Definition at line 312 of file EllipticFunction.cpp.
References GEOGRAPHICLIB_PANIC.
Referenced by GeographicLib::TransverseMercatorExact::Forward(), GeographicLib::TransverseMercatorExact::Reverse(), and GeographicLib::TransverseMercatorExact::UTM().
|
inline |
The Δ amplitude function.
[in] | sn | sinφ. |
[in] | cn | cosφ. |
Definition at line 581 of file EllipticFunction.hpp.
Referenced by GeographicLib::Rhumb::GenDirect(), GeographicLib::JacobiConformal::x(), and GeographicLib::JacobiConformal::y().
|
static |
Symmetric integral of the first kind RF.
[in] | x | |
[in] | y | |
[in] | z |
RF is defined in http://dlmf.nist.gov/19.16.E1
\[ R_F(x, y, z) = \frac12 \int_0^\infty\frac1{\sqrt{(t + x) (t + y) (t + z)}}\, dt \]
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 29 of file EllipticFunction.cpp.
|
static |
Complete symmetric integral of the first kind, RF with one argument zero.
[in] | x | |
[in] | y |
Definition at line 66 of file EllipticFunction.cpp.
References GeographicLib::Math::pi().
|
static |
Degenerate symmetric integral of the first kind RC.
[in] | x | |
[in] | y |
RC is defined in http://dlmf.nist.gov/19.2.E17
\[ R_C(x, y) = \frac12 \int_0^\infty\frac1{\sqrt{t + x}(t + y)}\,dt \]
Definition at line 81 of file EllipticFunction.cpp.
References GeographicLib::Math::asinh().
|
static |
Symmetric integral of the second kind RG.
[in] | x | |
[in] | y | |
[in] | z |
RG 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 \]
See also http://dlmf.nist.gov/19.16.E3. 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 96 of file EllipticFunction.cpp.
|
static |
Complete symmetric integral of the second kind, RG with one argument zero.
[in] | x | |
[in] | y |
Definition at line 104 of file EllipticFunction.cpp.
References GeographicLib::Math::pi(), and GeographicLib::Math::sq().
|
static |
Symmetric integral of the third kind RJ.
[in] | x | |
[in] | y | |
[in] | z | |
[in] | p |
RJ is defined in http://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 \]
Definition at line 127 of file EllipticFunction.cpp.
References GeographicLib::Math::sq().
|
static |
Degenerate symmetric integral of the third kind RD.
[in] | x | |
[in] | y | |
[in] | z |
RD is defined in http://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 \]
Definition at line 179 of file EllipticFunction.cpp.