Procedure

     KPSOLV ( Solve Kepler's Equation --- Vector Form )

     DOUBLE PRECISION FUNCTION KPSOLV ( EVEC )

Abstract

     Solve the equation X = < EVEC, U(X) > where U(X) is the unit
     vector [ COS(X), SIN(X) ] and  < , > denotes the two-dimensional
     dot product.

Required_Reading

     None.

Keywords

     ROOTS

Declarations

     IMPLICIT NONE

     DOUBLE PRECISION      EVEC ( 2 )

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     EVEC       I   A 2-vector whose magnitude is less than 1.

     The function returns the solution to X = < EVEC, U(X) >

Detailed_Input

     EVEC     is any two dimensional vector whose magnitude is
              less than 1.

Detailed_Output

     The function returns the value X such that the equation

        X = EVEC(1)COS(X) + EVEC(2)SIN(X).

Parameters

     None.

Exceptions

     1)  If the magnitude of EVEC is greater than or equal to 1,
         the error SPICE(EVECOUTOFRANGE) is signaled.

Files

     None.

Particulars

     This routine uses bisection and Newton's method to find
     the root of the equation

        X = EVEC(1)COS(X) + EVEC(2)SIN(X).

     This equation is just a "vector form" of Kepler's equation.

Examples

     Suppose you need to solve the equation

         M = E - e SIN(E)                           [ 1 ]

     for E. If we let X = E - M the equation is transformed to

        0 = X - e SIN( X + M )

          = X - e SIN( M ) COS(X) - e COS(M) SIN ( X )

     Thus if we solve the equation

        X = e SIN(M) COS(X) + e COS(M) SIN(X)

     we can find the value of X we can compute E.

     The code fragment below illustrates how this routine can
     be used to solve equation [1].

         EVEC(1) = ECC * DSIN(M)
         EVEC(2) = ECC * DCOS(M)
         E       = M   + KPSOLV( EVEC )

Restrictions

     None.

Literature_References

     None.

Author_and_Institution

     J. Diaz del Rio    (ODC Space)
     W.L. Taber         (JPL)

Version

    SPICELIB Version 1.1.1, 26-OCT-2021 (JDR)

        Edited the header to comply with NAIF standard.

    SPICELIB Version 1.1.0, 26-AUG-1997 (WLT)

        KPSOLV is now given an initial value of zero so that
        if an error condition is detected, KPSOLV will have
        a return value.

    SPICELIB Version 1.0.0, 03-JAN-1997 (WLT)