Index Page
oscltx_c
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
Brief_I/O
Detailed_Input
Detailed_Output
Parameters
Exceptions
Files
Particulars
Examples
Restrictions
Literature_References
Author_and_Institution
Version
Index_Entries

Procedure

   void oscltx_c ( ConstSpiceDouble state [6],
                   SpiceDouble      et,
                   SpiceDouble      mu,
                   SpiceDouble      elts  [SPICE_OSCLTX_NELTS] ) 

Abstract

 
   Determine the set of osculating conic orbital elements that 
   corresponds to the state (position, velocity) of a body at some 
   epoch. In additional to the classical elements, return the true 
   anomaly, semi-major axis, and period, if applicable. 
 

Required_Reading

 
   None. 
 

Keywords

 
   CONIC 
   ELEMENTS 
   EPHEMERIS 
 

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   Extended set of classical 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. 
                  NU      True anomaly at epoch. 
                  A       Semi-major axis. A is set to zero if 
                          it is not computable. 
                  TAU     Orbital period. Applicable only for 
                          elliptical orbits. Set to zero otherwise. 
 
               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 orbits. 

               See the Parameters section for information on the
               declaration of `elts'.

 

Parameters

 
   SPICE_OSCLTX_NELTS

               is the length of the output array `elts'.

               `elts' is intended to contain unused space to hold
               additional elements that may be added in a later version
               of this routine. In order to maintain forward
               compatibility, user applications should declare `elts'
               as follows:

                  SpiceDouble    elts[SPICE_OSCLTX_NELTS];

  

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 eccentricity 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. 
 
  11) The semi-major axis and period may not be computable for 
      orbits having eccentricity too close to 1. If the semi-major 
      axis is not computable, both it and the period are set to zero. 
      If the period is not computable, it is set to zero. 
 

Files

 
   None. 
 

Particulars

 
   This routine returns in the first 8 elements of the array `elts' 
   the outputs computed by oscelt_c, and in addition returns in 
   elements 9-11 the quantities: 
 
      elts[8]    true anomaly at `et', in radians. 
 
      elts[9]   orbital semi-major axis at `et', in km. Valid 
                if and only if this value is non-zero.
 
                The semi-major axis won't be computable if the 
                eccentricity of the orbit is too close to 1. 
                In this case A is set to zero. 
  
      elts[10]  orbital period. If the period is not computable, 
                TAU is set to zero. 
 
   The CSPICE routine conics_c is an approximate inverse of this 
   routine: conics_c 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

      oscltx_c ( 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.

      conics_c ( elts,    later, nominal );
      vsubg_c  ( nominal, state, 6, diff );

      printf( "Perturbation in x, dx/dt = %e %e\n", diff[0], diff[3] );
      printf( "                y, dy/dt = %e %e\n", diff[1], diff[4] );
      printf( "                z, dz/dt = %e %e\n", diff[2], diff[5] );
 

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 
      CSPICE routine conics_c 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

 
   -CSPICE Version 1.0.0, 25-JAN-2017 (NJB) (KRG) (IMU) (EDW)
   
      Original version 11-NOV-2014 (NJB) (KRG) (IMU) (EDW)

Index_Entries

 
   extended conic elements from state 
   extended osculating elements from state 
   convert state to extended osculating elements 
 
Wed Apr  5 17:54:40 2017