 
STATES User's Guide
===========================================================================
 
   Last revised on 2002 DEC 13 by E. D. Wright.
 
 
Abstract
--------------------------------------------------------
 
   STATES is a cookbook program that demonstrates how to use Toolkit
   routines to obtain state vectors.
 
 
Summary
--------------------------------------------------------
 
   The STATES `cookbook' program illustrates the use of SPICE SPK files and
   CSPICE subroutines. The program performs look-ups of state vectors from
   an SPK file.
 
   STATES demonstrates the use of the following high-level subroutines:
 
         furnsh_c   Load SPICE kernels
 
         spkezr_c   SPK, easy reader
 
         str2et_c   Convert time string to ephemeris time
 
         et2utc_c   Convert ephemeris time to UTC string
 
   Examine the STATES source code for usage examples of these routines.
   Also, refer to the SPK Required Reading (spk.req) and the module headers
   for these routines to obtain additional information.
 
   To run STATES, you need a binary SPK ephemeris file and knowledge of the
   bodies and corresponding time intervals contained in that file. The
   utility program named BRIEF summarizes a binary SPK file; NAIF IDs
   Required Reading (naif_ids.req) lists body names and codes. In addition
   to an SPK file, you also require access to a leapseconds kernel (LSK).
 
   Below, find an example STATES session that calculates the state of the
   Moon relative to the Earth at various times during the first day of
   January, 1990.
 
   STATES prompts you for the integer codes or string names of target and
   observer bodies, a reference frame for the state evaluation, the
   aberration correction to use with the evaluation, the end-points
   (expressed in UTC) of a time interval, and the number of evaluations
   (state look-ups) to perform over the assigned time interval. Given this
   input, STATES displays to the terminal the state, (position and
   velocity) at each evaluation of the target body as seen from the
   observer in the declared reference frame adjusted for the specified
   aberration correction.
 
   Please note: FORTRAN and C versions of the program can output numerical
   values in slightly different formats.
 
   It is assumed the kernel files used by STATES exist in the current
   directory (i.e. the directory from which your execute STATES). This
   particular session was run on an Intel box using the LINUX operating
   system.
 
   First, create the binary SPK kernel "cook_01.bsp" by running the CSPICE
   Toolkit TOBIN application on the transfer format file "cook_01.tsp"
   located in the CSPICE data directory. The program also requires a
   leapseconds kernel to run; an example leapseconds kernel, 'cook_01.tls'
   exists within the same directory. Now, execute STATES:
 
 
                      Welcome to STATES
 
      This program demonstrates the use of NAIF S- and P-
      Kernel (SPK) files and subroutines by computing the
      state of a target body as seen from an observing
      body at a number of epochs within a given time
      interval.
 
 
      Enter the name of a leapseconds kernel file: cook_01.tls
 
      Enter the name of a binary SPK ephemeris file: cook_01.bsp
 
      Enter the name of the observing body: earth
 
      Enter the name of a target body: moon
 
      Enter the number of states to be calculated: 5
 
      Enter the beginning UTC time: 1 jan 1990
 
      Enter the ending UTC time: 2 jan 1990
 
      Enter the inertial reference frame (eg:J2000): j2000
 
      Type of correction                              Type of state
      -------------------------------------------------------------
      'LT+S'    Light-time and stellar aberration    Apparent state
      'LT'      Light-time only                      True state
      'NONE'    No correction                        Geometric state
 
      Enter LT+S, LT, or NONE: LT+S
 
      Working ... Please wait
 
      For time 1 of 5, the state of:
      Body            : moon
      Relative to body: earth
      In Frame        : j2000
      At UTC time     : 1990 JAN 01 00:00:00
 
                       Position (km)              Velocity (km/s)
                  -----------------------     -----------------------
                X:  3.1817356914228073e+05         5.3394535681481514e-01
                Y: -1.9411657590890554e+05         7.7051535844816144e-01
                Z: -7.7812550159748964e+04         4.3386380567914284e-01
        MAGNITUDE:  3.8074986290962604e+05      1.0329711339369498e+00
 
 
      Continue? (Enter Y or N): Y
      For time 2 of 5, the state of:
      Body            : moon
      Relative to body: earth
      In Frame        : j2000
      At UTC time     : 1990 JAN 01 06:00:00
 
                       Position (km)              Velocity (km/s)
                  -----------------------     -----------------------
                X:  3.2915688826278772e+05         4.8249639220368934e-01
                Y: -1.7715581503624297e+05         7.9947042534779911e-01
                Z: -6.8315337774688582e+04         4.4523496484754310e-01
        MAGNITUDE:  3.7999398056714883e+05      1.0344998324882222e+00
 
 
      Continue? (Enter Y or N): Y
      For time 3 of 5, the state of:
      Body            : moon
      Relative to body: earth
      In Frame        : j2000
      At UTC time     : 1990 JAN 01 12:00:00
 
                       Position (km)              Velocity (km/s)
                  -----------------------     -----------------------
                X:  3.3900715098782443e+05         4.2906743233110589e-01
                Y: -1.5959674510107530e+05         8.2587395364385063e-01
                Z: -5.8588018067307996e+04         4.5515161940699311e-01
        MAGNITUDE:  3.7924863259976875e+05      1.0360162380210756e+00
 
 
      Continue? (Enter Y or N): Y
      For time 4 of 5, the state of:
      Body            : moon
      Relative to body: earth
      In Frame        : j2000
      At UTC time     : 1990 JAN 01 18:00:00
 
                       Position (km)              Velocity (km/s)
                  -----------------------     -----------------------
                X:  3.4768335621335648e+05         3.7382616249951184e-01
                Y: -1.4149583716010855e+05         8.4960221441502703e-01
                Z: -4.8662586928824239e+04         4.6356151096043718e-01
        MAGNITUDE:  3.7851398321334057e+05      1.0375255162895767e+00
 
 
      Continue? (Enter Y or N): Y
      For time 5 of 5, the state of:
      Body            : moon
      Relative to body: earth
      In Frame        : j2000
      At UTC time     : 1990 JAN 02 00:00:00
 
                       Position (km)              Velocity (km/s)
                  -----------------------     -----------------------
                X:  3.5514823394910217e+05         3.1695019646037181e-01
                Y: -1.2291215332598702e+05         8.7053938526942165e-01
                Z: -3.8572119287635753e+04         4.7041716136973366e-01
        MAGNITUDE:  3.7779025119599997e+05      1.0390325086601906e+00
 
 
 
