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