Class LegendreEllipticIntegral


  • public class LegendreEllipticIntegral
    extends Object
    Complete and incomplete elliptic integrals in Legendre form.

    The elliptic integrals are related to Jacobi elliptic functions.

    Beware that when computing elliptic integrals in the complex plane, many issues arise due to branch cuts. See the user guide for a thorough explanation.

    There are different conventions to interpret the arguments of Legendre elliptic integrals. In mathematical texts, these conventions show up using the separator between arguments. So for example for the incomplete integral of the first kind F we have:

    • F(φ, k): the first argument φ is an angle and the second argument k is the elliptic modulus: this is the trigonometric form of the integral
    • F(φ; m): the first argument φ is an angle and the second argument m=k² is the parameter: this is also a trigonometric form of the integral
    • F(x|m): the first argument x=sin(φ) is not an angle anymore and the second argument m=k² is the parameter: this is the Legendre form
    • F(φ\α): the first argument φ is an angle and the second argument α is the modular angle

    As we have no separator in a method call, we have to adopt one convention and stick to it. In Hipparchus, we adopted the Legendre form (i.e. F(x|m), with x=sin(φ) and m=k². These conventions are consistent with Wolfram Alpha functions EllipticF, EllipticE, ElliptiPI…

    Since:
    2.0
    See Also:
    Elliptic Integrals (Wikipedia), Complete Elliptic Integrals of the First Kind (MathWorld), Complete Elliptic Integrals of the Second Kind (MathWorld), Elliptic Integrals of the First Kind (MathWorld), Elliptic Integrals of the Second Kind (MathWorld), Elliptic Integrals of the Third Kind (MathWorld)
    • Method Detail

      • nome

        public static double nome​(double m)
        Get the nome q.
        Parameters:
        m - parameter (m=k² where k is the elliptic modulus)
        Returns:
        nome q
      • nome

        public static <T extends CalculusFieldElement<T>> T nome​(T m)
        Get the nome q.
        Type Parameters:
        T - the type of the field elements
        Parameters:
        m - parameter (m=k² where k is the elliptic modulus)
        Returns:
        nome q
      • bigKPrime

        public static double bigKPrime​(double m)
        Get the complete elliptic integral of the first kind K'(m).

        The complete elliptic integral of the first kind K'(m) is \[ \int_0^{\frac{\pi}{2}} \frac{d\theta}{\sqrt{1-(1-m) \sin^2\theta}} \] it corresponds to the imaginary quarter-period of Jacobi elliptic functions

        The algorithm for evaluating the functions is based on Carlson elliptic integrals.

        Parameters:
        m - parameter (m=k² where k is the elliptic modulus)
        Returns:
        complete elliptic integral of the first kind K'(m)
        See Also:
        bigK(double), Complete Elliptic Integrals of the First Kind (MathWorld), Elliptic Integrals (Wikipedia)
      • bigD

        public static double bigD​(double m)
        Get the complete elliptic integral D(m) = [K(m) - E(m)]/m.

        The complete elliptic integral D(m) is \[ \int_0^{\frac{\pi}{2}} \frac{\sin^2\theta}{\sqrt{1-m \sin^2\theta}} d\theta \]

        The algorithm for evaluating the functions is based on Carlson elliptic integrals.

        Parameters:
        m - parameter (m=k² where k is the elliptic modulus)
        Returns:
        complete elliptic integral D(m)
        See Also:
        bigD(double, double)
      • bigD

        public static <T extends CalculusFieldElement<T>> T bigD​(T m)
        Get the complete elliptic integral D(m) = [K(m) - E(m)]/m.

        The complete elliptic integral D(m) is \[ \int_0^{\frac{\pi}{2}} \frac{\sin^2\theta}{\sqrt{1-m \sin^2\theta}} d\theta \]

        The algorithm for evaluating the functions is based on Carlson elliptic integrals.

        Type Parameters:
        T - the type of the field elements
        Parameters:
        m - parameter (m=k² where k is the elliptic modulus)
        Returns:
        complete elliptic integral D(m)
        See Also:
        bigD(CalculusFieldElement, CalculusFieldElement)
      • bigD

        public static Complex bigD​(Complex m)
        Get the complete elliptic integral D(m) = [K(m) - E(m)]/m.

        The complete elliptic integral D(m) is \[ \int_0^{\frac{\pi}{2}} \frac{\sin^2\theta}{\sqrt{1-m \sin^2\theta}} d\theta \]

        The algorithm for evaluating the functions is based on Carlson elliptic integrals.

        Parameters:
        m - parameter (m=k² where k is the elliptic modulus)
        Returns:
        complete elliptic integral D(m)
        See Also:
        bigD(Complex, Complex)
      • bigD

        public static <T extends CalculusFieldElement<T>> FieldComplex<T> bigD​(FieldComplex<T> m)
        Get the complete elliptic integral D(m) = [K(m) - E(m)]/m.

        The complete elliptic integral D(m) is \[ \int_0^{\frac{\pi}{2}} \frac{\sin^2\theta}{\sqrt{1-m \sin^2\theta}} d\theta \]

        The algorithm for evaluating the functions is based on Carlson elliptic integrals.

        Type Parameters:
        T - the type of the field elements
        Parameters:
        m - parameter (m=k² where k is the elliptic modulus)
        Returns:
        complete elliptic integral D(m)
        See Also:
        bigD(FieldComplex, FieldComplex)
      • bigF

        public static double bigF​(double phi,
                                  double m)
        Get the incomplete elliptic integral of the first kind F(φ, m).

        The incomplete elliptic integral of the first kind F(φ, m) is \[ \int_0^{\phi} \frac{d\theta}{\sqrt{1-m \sin^2\theta}} \]

        The algorithm for evaluating the functions is based on Carlson elliptic integrals.

        Parameters:
        phi - amplitude (i.e. upper bound of the integral)
        m - parameter (m=k² where k is the elliptic modulus)
        Returns:
        incomplete elliptic integral of the first kind F(φ, m)
        See Also:
        bigK(double), Elliptic Integrals of the First Kind (MathWorld), Elliptic Integrals (Wikipedia)
      • bigF

        public static Complex bigF​(Complex phi,
                                   Complex m)
        Get the incomplete elliptic integral of the first kind F(φ, m).

        BEWARE! Elliptic integrals for complex numbers in the incomplete case are considered experimental for now, they have known issues.

        The incomplete elliptic integral of the first kind F(φ, m) is \[ \int_0^{\phi} \frac{d\theta}{\sqrt{1-m \sin^2\theta}} \]

        The algorithm for evaluating the functions is based on Carlson elliptic integrals.

        Parameters:
        phi - amplitude (i.e. upper bound of the integral)
        m - parameter (m=k² where k is the elliptic modulus)
        Returns:
        incomplete elliptic integral of the first kind F(φ, m)
        See Also:
        bigK(Complex), Elliptic Integrals of the First Kind (MathWorld), Elliptic Integrals (Wikipedia)
      • bigF

        public static Complex bigF​(Complex phi,
                                   Complex m,
                                   ComplexUnivariateIntegrator integrator,
                                   int maxEval)
        Get the incomplete elliptic integral of the first kind F(φ, m) using numerical integration.

        BEWARE! Elliptic integrals for complex numbers in the incomplete case are considered experimental for now, they have known issues.

        The incomplete elliptic integral of the first kind F(φ, m) is \[ \int_0^{\phi} \frac{d\theta}{\sqrt{1-m \sin^2\theta}} \]

        The algorithm for evaluating the functions is based on numerical integration. If integration path comes too close to a pole of the integrand, then integration will fail with a MathIllegalStateException even for very large maxEval. This is normal behavior.

        Parameters:
        phi - amplitude (i.e. upper bound of the integral)
        m - parameter (m=k² where k is the elliptic modulus)
        integrator - integrator to use
        maxEval - maximum number of evaluations (real and imaginary parts are evaluated separately, so up to twice this number may be used)
        Returns:
        incomplete elliptic integral of the first kind F(φ, m)
        See Also:
        bigK(Complex), Elliptic Integrals of the First Kind (MathWorld), Elliptic Integrals (Wikipedia)
      • bigF

        public static <T extends CalculusFieldElement<T>> FieldComplex<T> bigF​(FieldComplex<T> phi,
                                                                               FieldComplex<T> m,
                                                                               FieldComplexUnivariateIntegrator<T> integrator,
                                                                               int maxEval)
        Get the incomplete elliptic integral of the first kind F(φ, m).

        BEWARE! Elliptic integrals for complex numbers in the incomplete case are considered experimental for now, they have known issues.

        The incomplete elliptic integral of the first kind F(φ, m) is \[ \int_0^{\phi} \frac{d\theta}{\sqrt{1-m \sin^2\theta}} \]

        The algorithm for evaluating the functions is based on numerical integration. If integration path comes too close to a pole of the integrand, then integration will fail with a MathIllegalStateException even for very large maxEval. This is normal behavior.

        Type Parameters:
        T - the type of the field elements
        Parameters:
        phi - amplitude (i.e. upper bound of the integral)
        m - parameter (m=k² where k is the elliptic modulus)
        integrator - integrator to use
        maxEval - maximum number of evaluations (real and imaginary parts are evaluated separately, so up to twice this number may be used)
        Returns:
        incomplete elliptic integral of the first kind F(φ, m)
        See Also:
        bigK(CalculusFieldElement), Elliptic Integrals of the First Kind (MathWorld), Elliptic Integrals (Wikipedia)
      • bigE

        public static double bigE​(double phi,
                                  double m)
        Get the incomplete elliptic integral of the second kind E(φ, m).

        The incomplete elliptic integral of the second kind E(φ, m) is \[ \int_0^{\phi} \sqrt{1-m \sin^2\theta} d\theta \]

        The algorithm for evaluating the functions is based on Carlson elliptic integrals.

        Parameters:
        phi - amplitude (i.e. upper bound of the integral)
        m - parameter (m=k² where k is the elliptic modulus)
        Returns:
        incomplete elliptic integral of the second kind E(φ, m)
        See Also:
        bigE(double), Elliptic Integrals of the Second Kind (MathWorld), Elliptic Integrals (Wikipedia)
      • bigE

        public static Complex bigE​(Complex phi,
                                   Complex m)
        Get the incomplete elliptic integral of the second kind E(φ, m).

        BEWARE! Elliptic integrals for complex numbers in the incomplete case are considered experimental for now, they have known issues.

        The incomplete elliptic integral of the second kind E(φ, m) is \[ \int_0^{\phi} \sqrt{1-m \sin^2\theta} d\theta \]

        The algorithm for evaluating the functions is based on Carlson elliptic integrals.

        Parameters:
        phi - amplitude (i.e. upper bound of the integral)
        m - parameter (m=k² where k is the elliptic modulus)
        Returns:
        incomplete elliptic integral of the second kind E(φ, m)
        See Also:
        bigE(Complex), Elliptic Integrals of the Second Kind (MathWorld), Elliptic Integrals (Wikipedia)
      • bigE

        public static Complex bigE​(Complex phi,
                                   Complex m,
                                   ComplexUnivariateIntegrator integrator,
                                   int maxEval)
        Get the incomplete elliptic integral of the second kind E(φ, m) using numerical integration.

        BEWARE! Elliptic integrals for complex numbers in the incomplete case are considered experimental for now, they have known issues.

        The incomplete elliptic integral of the second kind E(φ, m) is \[ \int_0^{\phi} \sqrt{1-m \sin^2\theta} d\theta \]

        The algorithm for evaluating the functions is based on numerical integration. If integration path comes too close to a pole of the integrand, then integration will fail with a MathIllegalStateException even for very large maxEval. This is normal behavior.

        Parameters:
        phi - amplitude (i.e. upper bound of the integral)
        m - parameter (m=k² where k is the elliptic modulus)
        integrator - integrator to use
        maxEval - maximum number of evaluations (real and imaginary parts are evaluated separately, so up to twice this number may be used)
        Returns:
        incomplete elliptic integral of the second kind E(φ, m)
        See Also:
        bigE(Complex), Elliptic Integrals of the Second Kind (MathWorld), Elliptic Integrals (Wikipedia)
      • bigE

        public static <T extends CalculusFieldElement<T>> FieldComplex<T> bigE​(FieldComplex<T> phi,
                                                                               FieldComplex<T> m,
                                                                               FieldComplexUnivariateIntegrator<T> integrator,
                                                                               int maxEval)
        Get the incomplete elliptic integral of the second kind E(φ, m).

        BEWARE! Elliptic integrals for complex numbers in the incomplete case are considered experimental for now, they have known issues.

        The incomplete elliptic integral of the second kind E(φ, m) is \[ \int_0^{\phi} \sqrt{1-m \sin^2\theta} d\theta \]

        The algorithm for evaluating the functions is based on numerical integration. If integration path comes too close to a pole of the integrand, then integration will fail with a MathIllegalStateException even for very large maxEval. This is normal behavior.

        Type Parameters:
        T - the type of the field elements
        Parameters:
        phi - amplitude (i.e. upper bound of the integral)
        m - parameter (m=k² where k is the elliptic modulus)
        integrator - integrator to use
        maxEval - maximum number of evaluations (real and imaginary parts are evaluated separately, so up to twice this number may be used)
        Returns:
        incomplete elliptic integral of the second kind E(φ, m)
        See Also:
        bigE(FieldComplex), Elliptic Integrals of the Second Kind (MathWorld), Elliptic Integrals (Wikipedia)
      • bigD

        public static double bigD​(double phi,
                                  double m)
        Get the incomplete elliptic integral D(φ, m) = [F(φ, m) - E(φ, m)]/m.

        The incomplete elliptic integral D(φ, m) is \[ \int_0^{\phi} \frac{\sin^2\theta}{\sqrt{1-m \sin^2\theta}} d\theta \]

        The algorithm for evaluating the functions is based on Carlson elliptic integrals.

        Parameters:
        phi - amplitude (i.e. upper bound of the integral)
        m - parameter (m=k² where k is the elliptic modulus)
        Returns:
        incomplete elliptic integral D(φ, m)
        See Also:
        bigD(double)
      • bigD

        public static <T extends CalculusFieldElement<T>> T bigD​(T phi,
                                                                 T m)
        Get the incomplete elliptic integral D(φ, m) = [F(φ, m) - E(φ, m)]/m.

        The incomplete elliptic integral D(φ, m) is \[ \int_0^{\phi} \frac{\sin^2\theta}{\sqrt{1-m \sin^2\theta}} d\theta \]

        The algorithm for evaluating the functions is based on Carlson elliptic integrals.

        Type Parameters:
        T - the type of the field elements
        Parameters:
        phi - amplitude (i.e. upper bound of the integral)
        m - parameter (m=k² where k is the elliptic modulus)
        Returns:
        incomplete elliptic integral D(φ, m)
        See Also:
        bigD(CalculusFieldElement)
      • bigD

        public static Complex bigD​(Complex phi,
                                   Complex m)
        Get the incomplete elliptic integral D(φ, m) = [F(φ, m) - E(φ, m)]/m.

        BEWARE! Elliptic integrals for complex numbers in the incomplete case are considered experimental for now, they have known issues.

        The incomplete elliptic integral D(φ, m) is \[ \int_0^{\phi} \frac{\sin^2\theta}{\sqrt{1-m \sin^2\theta}} d\theta \]

        The algorithm for evaluating the functions is based on Carlson elliptic integrals.

        Parameters:
        phi - amplitude (i.e. upper bound of the integral)
        m - parameter (m=k² where k is the elliptic modulus)
        Returns:
        incomplete elliptic integral D(φ, m)
        See Also:
        bigD(Complex)
      • bigD

        public static <T extends CalculusFieldElement<T>> FieldComplex<T> bigD​(FieldComplex<T> phi,
                                                                               FieldComplex<T> m)
        Get the incomplete elliptic integral D(φ, m) = [F(φ, m) - E(φ, m)]/m.

        BEWARE! Elliptic integrals for complex numbers in the incomplete case are considered experimental for now, they have known issues.

        The incomplete elliptic integral D(φ, m) is \[ \int_0^{\phi} \frac{\sin^2\theta}{\sqrt{1-m \sin^2\theta}} d\theta \]

        The algorithm for evaluating the functions is based on Carlson elliptic integrals.

        Type Parameters:
        T - the type of the field elements
        Parameters:
        phi - amplitude (i.e. upper bound of the integral)
        m - parameter (m=k² where k is the elliptic modulus)
        Returns:
        incomplete elliptic integral D(φ, m)
        See Also:
        bigD(CalculusFieldElement)
      • bigPi

        public static double bigPi​(double n,
                                   double phi,
                                   double m)
        Get the incomplete elliptic integral of the third kind Π(n, φ, m).

        The incomplete elliptic integral of the third kind Π(n, φ, m) is \[ \int_0^{\phi} \frac{d\theta}{\sqrt{1-m \sin^2\theta}(1-n \sin^2\theta)} \]

        The algorithm for evaluating the functions is based on Carlson elliptic integrals.

        Parameters:
        n - elliptic characteristic
        phi - amplitude (i.e. upper bound of the integral)
        m - parameter (m=k² where k is the elliptic modulus)
        Returns:
        incomplete elliptic integral of the third kind Π(n, φ, m)
        See Also:
        bigPi(double, double), Elliptic Integrals of the Third Kind (MathWorld), Elliptic Integrals (Wikipedia)
      • bigPi

        public static Complex bigPi​(Complex n,
                                    Complex phi,
                                    Complex m)
        Get the incomplete elliptic integral of the third kind Π(n, φ, m).

        BEWARE! Elliptic integrals for complex numbers in the incomplete case are considered experimental for now, they have known issues.

        The incomplete elliptic integral of the third kind Π(n, φ, m) is \[ \int_0^{\phi} \frac{d\theta}{\sqrt{1-m \sin^2\theta}(1-n \sin^2\theta)} \]

        The algorithm for evaluating the functions is based on Carlson elliptic integrals.

        Parameters:
        n - elliptic characteristic
        phi - amplitude (i.e. upper bound of the integral)
        m - parameter (m=k² where k is the elliptic modulus)
        Returns:
        incomplete elliptic integral of the third kind Π(n, φ, m)
        See Also:
        bigPi(Complex, Complex), Elliptic Integrals of the Third Kind (MathWorld), Elliptic Integrals (Wikipedia)
      • bigPi

        public static Complex bigPi​(Complex n,
                                    Complex phi,
                                    Complex m,
                                    ComplexUnivariateIntegrator integrator,
                                    int maxEval)
        Get the incomplete elliptic integral of the third kind Π(n, φ, m) using numerical integration.

        BEWARE! Elliptic integrals for complex numbers in the incomplete case are considered experimental for now, they have known issues.

        The incomplete elliptic integral of the third kind Π(n, φ, m) is \[ \int_0^{\phi} \frac{d\theta}{\sqrt{1-m \sin^2\theta}(1-n \sin^2\theta)} \]

        The algorithm for evaluating the functions is based on numerical integration. If integration path comes too close to a pole of the integrand, then integration will fail with a MathIllegalStateException even for very large maxEval. This is normal behavior.

        Parameters:
        n - elliptic characteristic
        phi - amplitude (i.e. upper bound of the integral)
        m - parameter (m=k² where k is the elliptic modulus)
        integrator - integrator to use
        maxEval - maximum number of evaluations (real and imaginary
        Returns:
        incomplete elliptic integral of the third kind Π(n, φ, m)
        See Also:
        bigPi(Complex, Complex), Elliptic Integrals of the Third Kind (MathWorld), Elliptic Integrals (Wikipedia)
      • bigPi

        public static <T extends CalculusFieldElement<T>> FieldComplex<T> bigPi​(FieldComplex<T> n,
                                                                                FieldComplex<T> phi,
                                                                                FieldComplex<T> m,
                                                                                FieldComplexUnivariateIntegrator<T> integrator,
                                                                                int maxEval)
        Get the incomplete elliptic integral of the third kind Π(n, φ, m).

        BEWARE! Elliptic integrals for complex numbers in the incomplete case are considered experimental for now, they have known issues.

        The incomplete elliptic integral of the third kind Π(n, φ, m) is \[ \int_0^{\phi} \frac{d\theta}{\sqrt{1-m \sin^2\theta}(1-n \sin^2\theta)} \]

        The algorithm for evaluating the functions is based on numerical integration. If integration path comes too close to a pole of the integrand, then integration will fail with a MathIllegalStateException even for very large maxEval. This is normal behavior.

        Type Parameters:
        T - the type of the field elements
        Parameters:
        n - elliptic characteristic
        phi - amplitude (i.e. upper bound of the integral)
        m - parameter (m=k² where k is the elliptic modulus)
        integrator - integrator to use
        maxEval - maximum number of evaluations (real and imaginary parts are evaluated separately, so up to twice this number may be used)
        Returns:
        incomplete elliptic integral of the third kind Π(n, φ, m)
        See Also:
        bigPi(FieldComplex, FieldComplex), Elliptic Integrals of the Third Kind (MathWorld), Elliptic Integrals (Wikipedia)