Index Page
oscelt
A  B  C  D  E  F  G  H  I  J  K  L  M  N  O  P  Q  R  S  T  U  V  W  X 

Procedure
Abstract
Required_Reading
Keywords
Declarations
Brief_I/O
Detailed_Input
Detailed_Output
Parameters
Exceptions
Files
Particulars
Examples
Restrictions
Literature_References
Author_and_Institution
Version

Procedure

      OSCELT ( Determine conic elements from state )
 
      SUBROUTINE OSCELT ( STATE, ET, MU, ELTS )
      IMPLICIT NONE
 

Abstract

     Determine the set of osculating conic orbital elements that
     corresponds to the state (position, velocity) of a body at
     some epoch.

Required_Reading

     None.

Keywords

     CONIC
     EPHEMERIS

Declarations

 
      DOUBLE PRECISION      STATE  ( 6 )
      DOUBLE PRECISION      ET
      DOUBLE PRECISION      MU
      DOUBLE PRECISION      ELTS   ( 8 )
 

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     STATE      I   State of body at epoch of elements.
     ET         I   Epoch of elements.
     MU         I   Gravitational parameter (GM) of primary body.
     ELTS       O   Equivalent conic elements.

Detailed_Input

     STATE      is the state (position and velocity) of the body
                at some epoch. Components are x, y, z, dx/dt, dy/dt,
                dz/dt. STATE must be expressed relative to an 
                inertial reference frame.  Units are km and km/sec.


     ET         is the epoch of the input state, in ephemeris seconds
                past J2000.

                                                       3    2
     MU         is the gravitational parameter (GM, km /sec ) of
                the primary body.

Detailed_Output

     ELTS        are equivalent conic elements describing the orbit
                 of the body around its primary. The elements are,
                 in order:

                    RP      Perifocal distance.
                    ECC     Eccentricity.
                    INC     Inclination.
                    LNODE   Longitude of the ascending node.
                    ARGP    Argument of periapsis.
                    M0      Mean anomaly at epoch.
                    T0      Epoch.
                    MU      Gravitational parameter.

                 The epoch of the elements is the epoch of the input
                 state. Units are km, rad, rad/sec. The same elements
                 are used to describe all three types (elliptic,
                 hyperbolic, and parabolic) of conic orbit.

Parameters

     None.

Exceptions

     1) If MU is not positive, the error SPICE(NONPOSITIVEMASS)
        is signaled.

     2) If the specific angular momentum vector derived from STATE
        is the zero vector, the error SPICE(DEGENERATECASE)
        is signaled.

     3) If the position or velocity vectors derived from STATE
        is the zero vector, the error SPICE(DEGENERATECASE)
        is signaled.

     4) If the inclination is determined to be zero or 180 degrees,
        the longitude of the ascending node is set to zero.  

     5) If the eccentricity is determined to be zero, the argument of
        periapse is set to zero.     
     
     6) If the eccentricy of the orbit is very close to but not
        equal to zero, the argument of periapse may not be accurately
        determined.

     7) For inclinations near but not equal to 0 or 180 degrees,
        the longitude of the ascending node may not be determined
        accurately.  The argument of periapse and mean anomaly may
        also be inaccurate.

     8) For eccentricities very close to but not equal to 1, the
        results of this routine are unreliable. 

     9) If the specific angular momentum vector is non-zero but
        "close" to zero, the results of this routine are unreliable.

    10) If STATE is expressed relative to a non-inertial reference
        frame, the resulting elements are invalid.  No error checking
        is done to detect this problem.

Files

     None.

Particulars

     The SPICELIB routine CONICS is the inverse of this routine:
     CONICS maps a set of osculating elements and a time to a state
     vector.

Examples

     Let VINIT contain the initial state of a spacecraft relative to
     the center of a planet at epoch ET, and let GM be the gravitation
     parameter of the planet. The call

        CALL OSCELT ( VINIT, ET, GM, ELTS )

     produces a set of osculating elements describing the nominal
     orbit that the spacecraft would follow in the absence of all
     other bodies in the solar system.

     Now let STATE contain the state of the same spacecraft at some
     other epoch, LATER. The difference between this state and the
     state predicted by the nominal orbit at the same epoch can be
     computed as follows.

        CALL CONICS ( ELTS, LATER, NOMINAL )
        CALL VSUBG  ( NOMINAL, STATE, 6, DIFF )

        WRITE (*,*) 'Perturbation in x, dx/dt = ', DIFF(1), DIFF(4)
        WRITE (*,*) '                y, dy/dt = ', DIFF(2), DIFF(5)
        WRITE (*,*) '                z, dz/dt = ', DIFF(3), DIFF(6)

Restrictions

     1) The input state vector must be expressed relative to an
        inertial reference frame.

     2) Osculating elements are generally not useful for
        high-accuracy work.

     3) Accurate osculating elements may be difficult to derive for
        near-circular or near-equatorial orbits. Osculating elements
        for such orbits should be used with caution.

     4) Extracting osculating elements from a state vector is a 
        mathematically simple but numerically challenging task.  The
        mapping from a state vector to equivalent elements is
        undefined for certain state vectors, and the mapping is
        difficult to implement with finite precision arithmetic for
        states near the subsets of R6 where singularities occur.

        In general, the elements found by this routine can have
        two kinds of problems:

           - The elements are not accurate but still represent
             the input state accurately.  The can happen in
             cases where the inclination is near zero or 180
             degrees, or for near-circular orbits.

           - The elements are garbage.  This can occur when
             the eccentricity of the orbit is close to but
             not equal to 1.   In general, any inputs that cause
             great loss of precision in the computation of the
             specific angular momentum vector or the eccentricity
             vector will result in invalid outputs.

        For further details, see the Exceptions section.

        Users of this routine should carefully consider whether
        it is suitable for their applications.  One recommended
        "sanity check" on the outputs is to supply them to the
        SPICELIB routine CONICS and compare the resulting state 
        vector with the one supplied to this routine.

Literature_References

     [1] Roger Bate, Fundamentals of Astrodynamics, Dover, 1971.

Author_and_Institution

     N.J. Bachman    (JPL)
     K.R. Gehringer  (JPL)
     I.M. Underwood  (JPL)
     E.D. Wright     (JPL)

Version

    SPICELIB Version 1.3.1, 28-FEB-2008 (NJB)

        Updated Index_Entries header section to use keywords
        "osculating" and "convert." Updated Particulars header
        section to refer to CONICS. Fixed typo in in-line
        comments.

    SPICELIB Version 1.3.0, 17-NOV-2005 (NJB)

        Updated to remove non-standard use of duplicate arguments
        in VSCL call.

        The Exceptions and Restrictions header sections were updated.

    SPICELIB Version 1.2.0, 28-JAN-2003 (NJB) (EDW)

        Bug fixes:  routine previously didn't correctly compute
        the argument of periapse or mean anomaly for some cases.
        Also, the arguments of the ACOS and DACOSH functions were
        able to go out of range, causing floating-point exceptions.

        The computations of M0 and INC were re-coded for improved 
        accuracy.

        Also, added error checks for non-positive MU, zero 
        position, velocity, and specific angular momentum vectors.

    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.2, 6-APR-1995 (WLT)

        A typo was fixed in the description of the node vector
        in the comments of the routine.

    SPICELIB Version 1.0.1, 10-MAR-1992 (WLT)

        Comment section for permuted index source lines was added
        following the header.

    SPICELIB Version 1.0.0, 31-JAN-1990 (IMU)
Wed Apr  5 17:46:59 2017