Procedure

     SPKE15 ( Evaluate a type 15 SPK data record)

     SUBROUTINE SPKE15 ( ET, RECIN, STATE )

Abstract

     Evaluate a single SPK data record from a segment of type 15
     (Precessing Conic Propagation).

Required_Reading

     SPK

Keywords

     EPHEMERIS

Declarations

     IMPLICIT NONE

     DOUBLE PRECISION      ET
     DOUBLE PRECISION      RECIN  ( * )
     DOUBLE PRECISION      STATE  ( 6 )

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     ET         I   Target epoch.
     RECIN      I   Data record.
     STATE      O   State (position and velocity).

Detailed_Input

     ET       is a target epoch, specified as ephemeris seconds past
              J2000, at which a state vector is to be computed.

     RECIN    is a data record which, when evaluated at epoch ET,
              will give the state (position and velocity) of some
              body, relative to some center, in some inertial
              reference frame.

              The structure of RECIN is:

              RECIN(1)             epoch of periapsis
                                   in ephemeris seconds past J2000.
              RECIN(2)-RECIN(4)    unit trajectory pole vector
              RECIN(5)-RECIN(7)    unit periapsis vector
              RECIN(8)             semi-latus rectum---p in the
                                   equation:

                                   r = p/(1 + ECC*COS(Nu))

              RECIN(9)             eccentricity
              RECIN(10)            J2 processing flag describing
                                   what J2 corrections are to be
                                   applied when the orbit is
                                   propagated.

                                   All J2 corrections are applied
                                   if this flag has a value that
                                   is not 1,2 or 3.

                                   If the value of the flag is 3
                                   no corrections are done.

                                   If the value of the flag is 1
                                   no corrections are computed for
                                   the precession of the line
                                   of apsides. However, regression
                                   of the line of nodes is
                                   performed.

                                   If the value of the flag is 2
                                   no corrections are done for
                                   the regression of the line of
                                   nodes. However, precession of the
                                   line of apsides is performed.

                                   Note that J2 effects are computed
                                   only if the orbit is elliptic and
                                   does not intersect the central
                                   body.

              RECIN(11)-RECIN(13)  unit central body pole vector
              RECIN(14)            central body GM
              RECIN(15)            central body J2
              RECIN(16)            central body radius

              Units are radians, km, seconds

Detailed_Output

     STATE    is the state produced by evaluating RECIN at ET.
              Units are km and km/sec.

Parameters

     None.

Exceptions

     1)  If the eccentricity is less than zero, the error
         SPICE(BADECCENTRICITY) is signaled.

     2)  If the semi-latus rectum is non-positive, the error
         SPICE(BADLATUSRECTUM) is signaled.

     3)  If the pole vector, trajectory pole vector or periapsis vector
         has zero length, the error SPICE(BADVECTOR) is signaled.

     4)  If the trajectory pole vector and the periapsis vector are not
         orthogonal, the error SPICE(BADINITSTATE) is signaled. The
         test for orthogonality is very crude. The routine simply
         checks that the absolute value of the dot product of the unit
         vectors parallel to the trajectory pole and periapse vectors
         is less than 0.00001. This check is intended to catch
         blunders, not to enforce orthogonality to double precision
         tolerance.

     5)  If the mass of the central body is non-positive, the error
         SPICE(NONPOSITIVEMASS) is signaled.

     6)  If the radius of the central body is negative, the error
         SPICE(BADRADIUS) is signaled.

Files

     None.

Particulars

     This algorithm applies J2 corrections for precessing the
     node and argument of periapse for an object orbiting an
     oblate spheroid.

     Note the effects of J2 are incorporated only for elliptic
     orbits that do not intersect the central body.

     While the derivation of the effect of the various harmonics
     of gravitational field are beyond the scope of this header
     the effect of the J2 term of the gravity model are as follows


        The line of node precesses. Over one orbit average rate of
        precession,  DNode/dNu,  is given by

                                3 J2
              dNode/dNu =  -  -----------------  DCOS( inc )
                                2 (P/RPL)**2

        (Since this is always less than zero for oblate spheroids, this
           should be called regression of nodes.)

        The line of apsides precesses. The average rate of precession
        DPeri/dNu is given by
                                   3 J2
              dPeri/dNu =     ----------------- ( 5*DCOS ( inc ) - 1 )
                                2 (P/RPL)**2

        Details of these formulae are given in the Battin's book (see
        literature references below).


     It is assumed that this routine is used in conjunction with
     the routine SPKR15 as shown here:

        CALL SPKR15 ( HANDLE, DESCR, ET, RECIN         )
        CALL SPKE15 (                ET, RECIN, STATE  )

     where it is known in advance that the HANDLE, DESCR pair points
     to a type 15 data segment.

Examples

     The SPKEnn routines are almost always used in conjunction with
     the corresponding SPKRnn routines, which read the records from
     SPK files.

     The data returned by the SPKRnn routine is in its rawest form,
     taken directly from the segment. As such, it will be meaningless
     to a user unless he/she understands the structure of the data type
     completely. Given that understanding, however, the SPKRnn
     routines might be used to examine raw segment data before
     evaluating it with the SPKEnn routines.


     C
     C     Get a segment applicable to a specified body and epoch.
     C
           CALL SPKSFS ( BODY, ET, HANDLE, DESCR, IDENT, FOUND )

     C
     C     Look at parts of the descriptor.
     C
           CALL DAFUS ( DESCR, 2, 6, DCD, ICD )
           CENTER = ICD( 2 )
           REF    = ICD( 3 )
           TYPE   = ICD( 4 )

           IF ( TYPE .EQ. 15 ) THEN

              CALL SPKR15 ( HANDLE, DESCR, ET, RECORD )
                  .
                  .  Look at the RECORD data.
                  .
              CALL SPKE15 ( ET, RECORD, STATE )
                  .
                  .  Check out the evaluated state.
                  .
           END IF

Restrictions

     None.

Literature_References

     [1]  J. Danby, "Fundamentals of Celestial Mechanics," 2nd Edition,
          pp.345-347, Willman-Bell, 1989.

     [2]  R. H. Battin, "Astronautical Guidance," pp.199, McGraw-Hill
          Book Company, 1964.

Author_and_Institution

     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)
     K.R. Gehringer     (JPL)
     S. Schlaifer       (JPL)
     W.L. Taber         (JPL)

Version

    SPICELIB Version 1.3.0, 14-APR-2021 (JDR)

        Edited the header to comply with NAIF standard. Removed
        unnecessary $Revisions section.

    SPICELIB Version 1.2.0, 02-SEP-2005 (NJB)

        Updated to remove non-standard use of duplicate arguments
        in VHAT, VROTV, and VSCL calls.

    SPICELIB Version 1.1.0, 29-FEB-1996 (KRG)

        The declaration for the SPICELIB function PI is now
        preceded by an EXTERNAL statement declaring PI to be an
        external function. This removes a conflict with any
        compilers that have a PI intrinsic function.

    SPICELIB Version 1.0.0, 15-NOV-1994 (WLT) (SS)