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