Index Page
STATES User's Guide

Table of Contents 


   STATES User's Guide
      Abstract
      Summary


Top

STATES User's Guide




Last revised on 2002 DEC 13 by E. D. Wright.



Top

Abstract



STATES is a cookbook program that demonstrates how to use Toolkit routines to obtain state vectors.



Top

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