Procedure

     SPKGEO ( S/P Kernel, geometric state )

     SUBROUTINE SPKGEO ( TARG, ET, REF, OBS, STATE, LT )

Abstract

     Compute the geometric state (position and velocity) of a target
     body relative to an observing body.

Required_Reading

     SPK

Keywords

     EPHEMERIS

Declarations

     IMPLICIT NONE

     INCLUDE               'ninert.inc'
     INCLUDE               'zzctr.inc'

     INTEGER               TARG
     DOUBLE PRECISION      ET
     CHARACTER*(*)         REF
     INTEGER               OBS
     DOUBLE PRECISION      STATE    ( 6 )
     DOUBLE PRECISION      LT

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     TARG       I   Target body.
     ET         I   Target epoch.
     REF        I   Target reference frame.
     OBS        I   Observing body.
     STATE      O   State of target.
     LT         O   Light time.

Detailed_Input

     TARG     is the standard NAIF ID code for a target body.

     ET       is the epoch (ephemeris time) at which the state
              of the target body is to be computed.

     REF      is the name of the reference frame to
              which the vectors returned by the routine should
              be rotated. This may be any frame supported by
              the SPICELIB subroutine FRMCHG.

     OBS      is the standard NAIF ID code for an observing body.

Detailed_Output

     STATE    is a 6-dimensional vector that contains the geometric
              position and velocity of the target body, relative to the
              observing body, at epoch ET. STATE has six elements: the
              first three contain the target's position; the last three
              contain the target's velocity. These vectors are
              transformed into the specified reference frame. Units are
              always km and km/sec.

     LT       is the one-way light time in seconds from the
              observing body to the geometric position of the
              target body at the specified epoch.

Parameters

     None.

Exceptions

     1)  If insufficient ephemeris data has been loaded to compute
         the necessary states, the error SPICE(SPKINSUFFDATA) is
         signaled.

Files

     See $Restrictions.

Particulars

     SPKGEO computes the geometric state, T(t), of the target
     body and the geometric state, O(t), of the observing body
     relative to the first common center of motion. Subtracting
     O(t) from T(t) gives the geometric state of the target
     body relative to the observer.


        CENTER ----- O(t)
            |      /
            |     /
            |    /
            |   /  T(t) - O(t)
            |  /
           T(t)


     The one-way light time, tau, is given by


               | T(t) - O(t) |
        tau = -----------------
                      c


     For example, if the observing body is -94, the Mars Observer
     spacecraft, and the target body is 401, Phobos, then the
     first common center is probably 4, the Mars Barycenter.
     O(t) is the state of -94 relative to 4 and T(t) is the
     state of 401 relative to 4.

     The center could also be the Solar System Barycenter, body 0.
     For example, if the observer is 399, Earth, and the target
     is 299, Venus, then O(t) would be the state of 399 relative
     to 0 and T(t) would be the state of 299 relative to 0.

     Ephemeris data from more than one segment may be required
     to determine the states of the target body and observer
     relative to a common center. SPKGEO reads as many segments
     as necessary, from as many files as necessary, using files
     that have been loaded by previous calls to FURNSH or SPKLEF
     (load ephemeris file).

     SPKGEO is similar to SPKEZ but returns geometric states
     only, with no option to make planetary (light-time) nor
     stellar aberration corrections. The geometric states
     returned by SPKEZ and SPKGEO are the same.

Examples

     The numerical results shown for this example may differ across
     platforms. The results depend on the SPICE kernels used as
     input, the compiler and supporting libraries, and the machine
     specific arithmetic implementation.

     1) Return the geometric state vector of Mars (499) as seen from
        Earth (399) in the J2000 frame and the one-way light time
        between them at the epoch July 4, 2003 11:00 AM PST.

        Use the meta-kernel shown below to load the required SPICE
        kernels.


           KPL/MK

           File: spkgeo_ex1.tm

           This meta-kernel is intended to support operation of SPICE
           example programs. The kernels shown here should not be
           assumed to contain adequate or correct versions of data
           required by SPICE-based user applications.

           In order for an application to use this meta-kernel, the
           kernels referenced here must be present in the user's
           current working directory.

           The names and contents of the kernels referenced
           by this meta-kernel are as follows:

              File name                        Contents
              ---------                        --------
              de430.bsp                        Planetary ephemeris
              mar097.bsp                       Mars satellite ephemeris
              naif0011.tls                     Leapseconds


           \begindata

              KERNELS_TO_LOAD = ( 'de430.bsp',
                                  'mar097.bsp',
                                  'naif0011.tls' )

           \begintext

           End of meta-kernel


        Example code begins here.


              PROGRAM SPKGEO_EX1
              IMPLICIT NONE

        C
        C     SPICELIB functions
        C
              DOUBLE PRECISION      VNORM

        C
        C     Local parameters.
        C
              INTEGER               NAMLEN
              PARAMETER           ( NAMLEN = 32 )

              INTEGER               TIMLEN
              PARAMETER           ( TIMLEN = 26 )

        C
        C     Local variables.
        C
              CHARACTER*(TIMLEN)    EPOCH
              CHARACTER*(NAMLEN)    REFFRM

              DOUBLE PRECISION      ET
              DOUBLE PRECISION      LT
              DOUBLE PRECISION      STATE ( 6 )

              INTEGER               I
              INTEGER               OBSRVR
              INTEGER               TARGET


        C
        C     Load a set of kernels: an SPK file, a PCK
        C     file and a leapseconds file. Use a meta
        C     kernel for convenience.
        C
              CALL FURNSH ( 'spkgeo_ex1.tm' )

        C
        C     Define parameters for a state lookup.
        C
              TARGET = 499
              EPOCH  = 'July 4, 2003 11:00 AM PST'
              REFFRM = 'J2000'
              OBSRVR = 399

        C
        C     Convert the epoch to ephemeris time.
        C
              CALL STR2ET ( EPOCH, ET )

        C
        C     Look-up the state for the defined parameters.
        C
              CALL SPKGEO ( TARGET, ET, REFFRM, OBSRVR, STATE, LT )

        C
        C     Output...
        C
              WRITE(*,'(A,I3)') 'The position of    : ', TARGET
              WRITE(*,'(A,I3)') 'As observed from   : ', OBSRVR
              WRITE(*,'(2A)')   'In reference frame : ', REFFRM
              WRITE(*,'(2A)')   'At epoch           : ', EPOCH
              WRITE(*,*) ' '

        C
        C     The first three entries of state contain the
        C     X, Y, Z position components. The final three contain
        C     the Vx, Vy, Vz velocity components.
        C
              WRITE(*,'(A,3F18.6)') 'R   (km):', ( STATE(I), I=1,3 )
              WRITE(*,'(A,3F18.6)') 'V (km/s):', ( STATE(I), I=4,6 )
              WRITE(*,*) ' '
              WRITE(*,'(A,F19.14)') 'Light time (s) between observer '
             .                   // 'and target: ', LT

              END


        When this program was executed on a Mac/Intel/gfortran/64-bit
        platform, the output was:


        The position of    : 499
        As observed from   : 399
        In reference frame : J2000
        At epoch           : July 4, 2003 11:00 AM PST

        R   (km):   73826216.435288  -27128030.732406  -18741973.868287
        V (km/s):         -6.809504          7.513814          3.001290

        Light time (s) between observer and target:  269.70264776317532

Restrictions

     1)  The ephemeris files to be used by SPKGEO must be loaded
         by FURNSH or SPKLEF before SPKGEO is called.

Literature_References

     None.

Author_and_Institution

     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)
     J.E. McLean        (JPL)
     B.V. Semenov       (JPL)
     W.L. Taber         (JPL)
     E.D. Wright        (JPL)

Version

    SPICELIB Version 3.1.0, 09-OCT-2021 (JDR) (NJB)

        Bug fix: added calls to FAILED after calls to SPKPVN.
        Previously only one call to SPKPVN was followed by a FAILED
        call. Moved some FAILED checks so they will be hit whether
        or not SPKSFS finds a segment.

        Edited the header to comply with NAIF standard. Added complete
        code example to $Examples section. Removed unnecessary
        $Revisions section.

        Added reference to FURNSH in $Particulars and $Restrictions
        sections.

    SPICELIB Version 3.0.0, 08-JAN-2014 (BVS)

        Updated to save the input frame name and POOL state counter
        and to do frame name-ID conversion only if the counter has
        changed.

        Updated to map the input frame name to its ID by first calling
        ZZNAMFRM, and then calling IRFNUM. The side effect of this
        change is that now the frame with the fixed name 'DEFAULT'
        that can be associated with any code via CHGIRF's entry point
        IRFDEF will be fully masked by a frame with identical name
        defined via a text kernel. Previously the CHGIRF's 'DEFAULT'
        frame masked the text kernel frame with the same name.

        Fixed description of STATE in Detailed Output. Replaced
        SPKLEF with FURNSH and fixed errors in $Examples.

    SPICELIB Version 2.4.0, 01-SEP-2005 (NJB)

        Updated to remove non-standard use of duplicate arguments
        in VADDG calls.

    SPICELIB Version 2.3.0, 05-JAN-2005 (NJB)

        Tests of routine FAILED() were added.

    SPICELIB Version 2.2.1, 20-OCT-2003 (EDW)

        Added mention that LT returns in seconds.

    SPICELIB Version 2.2.0, 11-APR-1997 (WLT)

        The routine was modified to take advantage of the fact
        that most state transformation are between inertial frames.
        Looking up a transformation between inertial frames is
        substantially faster than looking up non-inertial
        transformations. Consequently slightly more
        complex code produces about a 50% increase in speed for
        many users.

    SPICELIB Version 2.1.0, 26-JUL-1996 (WLT)

        The routine was upgraded so that potentially redundant
        computations are not performed.

    SPICELIB Version 2.0.0, 19-SEP-1995 (WLT)

        The routine was upgraded so that it can return states
        relative to rotating frames.

    SPICELIB Version 1.0.1, 10-MAR-1992 (WLT)

        Comment section for permuted index source lines was added
        following the header.

    SPICELIB Version 1.0.0, 18-JUL-1991 (JEM)