 
Geometric Event Finding Hands-On Lesson, using TGO (FORTRAN)
===========================================================================
 
   May 21, 2018
 
 
Overview
--------------------------------------------------------
 
   This lesson illustrates how the Geometry Finder (GF) subsystem of the
   SPICE Toolkit can be used to find time intervals when specified
   geometric conditions are satisfied.
 
   In this lesson the student is asked to construct a program that finds
   the time intervals, within a specified time range, when the ExoMars-16
   Trace Gas Orbiter (TGO) is visible from ESA's deep space station in New
   Norcia. Possible occultation of the spacecraft by Mars is to be
   considered.
 
 
Note About HTML Links
--------------------------------------------------------
 
   The HTML version of this lesson contains links pointing to various HTML
   documents provided with the Toolkit. All of these links are relative
   and, in order to function, require this document to be in a certain
   location in the Toolkit HTML documentation directory tree.
 
   In order for the links to be resolved, if not done already by installing
   the lessons package under the Toolkit's ``doc/html'' directory, create a
   subdirectory called ``lessons'' under the ``doc/html'' directory of the
   ``toolkit/'' tree and copy this document to that subdirectory before
   loading it into a Web browser.
 
 
References
--------------------------------------------------------
 
   This section lists SPICE documents referred to in this lesson.
 
   Of these documents, the ``Tutorials'' contains the highest level
   descriptions with the least number of details while the ``Required
   Reading'' documents contain much more detailed specifications. The most
   complete specifications are provided in the ``API Documentation''.
 
   In some cases the lesson explanations also refer to the information
   provided in the meta-data area of the kernels used in the lesson
   examples. It is especially true in case of the FK and IK files, which
   often contain comprehensive descriptions of the frames, instrument FOVs,
   etc. Since both FK and IK are text kernels, the information provided in
   them can be viewed using any text editor, while the meta information
   provided in binary kernels -- SPKs and CKs -- can be viewed using
   ``commnt'' or ``spacit'' utility programs located in ``toolkit/exe'' of
   Toolkit installation tree.
 
 
Tutorials
 
   The following SPICE tutorials serve as references for the discussions in
   this lesson:
 
 
      Name              Lesson steps/routines it describes
      ----------------  -----------------------------------------------
      Time              Time Conversion
      SCLK and LSK      Time Conversion
      SPK               Obtaining Ephemeris Data
      Frames            Reference Frames
      Using Frames      Reference Frames
      PCK               Planetary Constants Data
      Lunar-Earth PCK   Lunar and Earth Orientation Data
      GF                The SPICE Geometry Finder (GF) subsystem
      DSK               Detailed Target Shape (Topography) Data
 
   These tutorials are available from the NAIF ftp server at JPL:
 
      http://naif.jpl.nasa.gov/naif/tutorials.html
 
 
Required Readings
 
   The Required Reading documents are provided with the Toolkit and are
   located under the ``toolkit/doc'' directory in the SPICE Toolkit
   installation tree.
 
      Name             Lesson steps/routines that it describes
      ---------------  -----------------------------------------
      cells.req        Cell/window initialization
      frames.req       Using reference frames
      gf.req           The SPICE geometry finder (GF) subsystem
      kernel.req       Loading SPICE kernels
      naif_ids.req     Body and reference frame names
      pck.req          Obtaining planetary constants data
      spk.req          Computing positions and velocities
      time.req         UTC to ET time conversion
      windows.req      The SPICE window data type
 
 
The Permuted Index
 
   Another useful document distributed with the Toolkit is the permuted
   index. This is located under the ``toolkit/doc'' directory in the
   FORTRAN installation tree.
 
   This text document provides a simple mechanism by which users can
   discover which SPICE routines perform functions of interest, as well as
   the names of the source files that contain these routines. This is
   particularly useful for FORTRAN programmers because some of the routines
   are entry points; the names of these routines do not translate directly
   into the name of the respective source files that contain them.
 
 
API Documentation
 
   The most detailed specification of a given SPICE FORTRAN routine is
   contained in the header section of its source code. The source code is
   distributed with the Toolkit and is located under the
   ``toolkit/src/spicelib'' path.
 
   For example the path of the source code of the STR2ET routine is
 
      toolkit/src/spicelib/str2et.for
 
   Since some of the FORTRAN routines are entry points they may be part of
   a source file that has different name. The ``Permuted Index'' document
   mentioned above can be used to locate the name of their source file.
 
 
Kernels Used
--------------------------------------------------------
 
   The following kernels are used in examples provided in this lesson:
 
      1.  Solar System Ephemeris SPK, subsetted to cover only the time
          range of interest:
 
             de430.bsp
 
      2.  Martian Satellite Ephemeris SPK, subsetted to cover only the time
          range of interest:
 
             mar085.bsp
 
      3.  ESA stations SPK:
 
             estrack_v01.bsp
 
      4.  ESA stations frame definitions:
 
             estrack_v01.tf
 
      5.  EARTH_FIXED/ITRF93 frame connection:
 
             earthfixeditrf93.tf
 
      6.  Binary PCK for Earth:
 
             earth_070425_370426_predict.bpc
 
      7.  ExoMars-16 TGO Spacecraft Trajectory SPK, subsetted to cover only
          the time range of interest:
 
             em16_tgo_mlt_20171205_20230115_v01.bsp
 
      8.  Generic LSK:
 
             naif0012.tls
 
      9.  Generic PCK:
 
             pck00010.tpc
 
      10. Low-resolution Mars DSK:
 
             mars_lowres.bds
 
 
   These SPICE kernels are included in the lesson package available from
   the NAIF server at JPL:
 
      ftp://naif.jpl.nasa.gov/pub/naif/toolkit_docs/Lessons/
 
 
SPICE Modules Used
--------------------------------------------------------
 
   This section provides a complete list of the routines and kernels that
   are suggested for usage in each of the exercises in this lesson. (You
   may wish to not look at this list unless/until you ``get stuck'' while
   working on your own.)
 
      CHAPTER EXERCISE   ROUTINES   FUNCTIONS  KERNELS
      ------- ---------  ---------  ---------  ----------
         1    viewpr     FURNSH     RPD        1-9
                         TOSTDO     WNCARD
                         REPMC
                         REPMF
                         STR2ET
                         TIMOUT
                         SSIZED
                         WNINSD
                         GFPOSC
                         WNFETD
 
         2    visibl     FURNSH     RPD        1-10
                         TOSTDO     WNCARD
                         REPMC
                         REPMF
                         STR2ET
                         TIMOUT
                         SSIZED
                         WNINSD
                         GFPOSC
                         GFOCLT
                         WNDIFD
                         WNFETD
 
              extra (*)  GFDIST                1-2,7-9
                         KCLEAR
 
 
         (*) Additional APIs and kernels used in Extra Credit tasks.
 
   Refer to the headers of the various routines listed above, as detailed
   interface specifications are provided with the source code.
 
 
Find View Periods
===========================================================================
 
 
Task Statement
--------------------------------------------------------
 
   Write a program that finds the set of time intervals, within the time
   range
 
      2018 JUN 10 TDB
      2018 JUN 14 TDB
 
   when the ExoMars-16 Trace Gas Orbiter (TGO) is visible from ESA's New
   Norcia station. These time intervals are frequently called ``view
   periods.''
 
   The spacecraft is considered visible if its apparent position (that is,
   its position corrected for light time and stellar aberration) has
   elevation of at least 6 degrees in the topocentric reference frame
   NEW_NORCIA_TOPO. In this exercise, we ignore the possibility of
   occultation of the spacecraft by Mars.
 
   Use a search step size that ensures that no view periods of duration 5
   minutes or longer will be missed by the search.
 
   Display the start and stop times of these intervals using TDB calendar
   dates and millisecond precision.
 
 
Learning Goals
--------------------------------------------------------
 
   Exposure to SPICE GF event finding routines. Familiarity with SPICE
   windows and routines that manipulate them. Exposure to SPICE time
   parsing and output formatting routines.
 
 
Approach
--------------------------------------------------------
 
 
Solution steps
 
   A possible solution could consist of the following steps:
 
   Preparation:
 
       1.   Review the SPICELIB cell and window Required Reading.
 
       2.   Decide what SPICE kernels are necessary. Use the SPICE summary
            tool BRIEF to examine the coverage of the binary kernels and
            verify the availability of required data.
 
       3.   Create a meta-kernel listing the SPICE kernels to be loaded.
            (Hint: consult a programming example tutorial, or the
            Introduction to Kernels tutorial, for a reminder of how to do
            this.)
 
            Name the meta-kernel 'viewpr.tm'.
 
   Next, write a program that performs the following steps:
 
       1.   Use FURNSH to load the meta-kernel.
 
       2.   Declare confinement and output SPICELIB windows and initialize
            them using SSIZED.
 
       3.   Insert the given time bounds into the confinement window using
            WNINSD.
 
       4.   Select a step size for searching for visibility state
            transitions: in this case, each target rise or set event is a
            state transition.
 
            The step size must be large enough so the search proceeds with
            reasonable speed, but small enough so that no visibility
            transition events---that is, target rise or set events---are
            missed.
 
       5.   Use the GF routine GFPOSC to find the window of times, within
            the confinement window, during which the ExoMars-16 TGO
            spacecraft is above the elevation limit as seen from ESA's New
            Norcia station, in the reference frame NEW_NORCIA_TOPO.
 
            Use light time and stellar aberration corrections for the
            apparent position of the spacecraft as seen from the station.
 
       6.   Fetch and display the contents of the result window. Use WNFETD
            to extract from the result window the start and stop times of
            each time interval. Display each of the intervals in the result
            window as a pair of start and stop times. Express each time as
            a TDB calendar date using the routine TIMOUT.
 
            The SPICELIB ``replace marker'' routines REPxxx are useful for
            substituting values into output strings. Consult, for example,
            the header of REPMC.
 
   You may find it useful to consult the references listed above. In
   particular, the header of the SPICE GF routine GFPOSC contains pertinent
   documentation.
 
 
Solution
--------------------------------------------------------
 
 
Solution Meta-Kernel
 
   The meta-kernel we created for the solution to this exercise is named
   'viewpr.tm'. Its contents follow:
 
      KPL/MK
 
         This is the meta-kernel used in the solution of the tasks in the
         Geometric Event Finding Hands On Lesson.
 
         The names and contents of the kernels referenced by this
         meta-kernel are as follows:
 
            1.  Solar System Ephemeris SPK, subsetted to cover only the
                time range of interest:
 
                   de430.bsp
 
            2.  Martian Satellite Ephemeris SPK, subsetted to cover only
                the time range of interest:
 
                   mar085.bsp
 
            3.  ESA stations SPK:
 
                   estrack_v01.bsp
 
            4.  ESA stations frame definitions:
 
                   estrack_v01.tf
 
            5.  EARTH_FIXED/ITRF93 frame connection:
 
                   earthfixeditrf93.tf
 
            6.  Binary PCK for Earth:
 
                   earth_070425_370426_predict.bpc
 
            7.  ExoMars-16 TGO Spacecraft Trajectory SPK, subsetted to
                cover only the time range of interest:
 
                   em16_tgo_mlt_20171205_20230115_v01.bsp
 
            8.  Generic LSK:
 
                   naif0012.tls
 
            9.  Generic PCK:
 
                  pck00010.tpc
 
 
      \begindata
 
         KERNELS_TO_LOAD = (
 
            'kernels/spk/de430.bsp'
            'kernels/spk/mar085.bsp',
            'kernels/spk/estrack_v01.bsp'
            'kernels/fk/estrack_v01.tf'
            'kernels/fk/earthfixeditrf93.tf'
            'kernels/pck/earth_070425_370426_predict.bpc'
            'kernels/lsk/naif0012.tls'
            'kernels/spk/em16_tgo_mlt_20171205_20230115_v01.bsp'
            'kernels/pck/pck00010.tpc'
 
                           )
 
      \begintext
 
 
 
Solution Code
 
   The example program below shows one possible solution.
 
            PROGRAM VIEWPR
            IMPLICIT NONE
      C
      C     Find and display the window of times when the ExoMars-16
      C     TGO spacecraft is above a specified elevation limit in the
      C     topocentric reference frame of ESA's New Norcia station.
      C
 
      C
      C     SPICELIB functions
      C
            DOUBLE PRECISION      RPD
            INTEGER               WNCARD
 
      C
      C     Global GF parameters: we import from this file
      C     the definition of the GF workspace size parameter
      C
      C        NWMAX
      C
            INCLUDE 'gf.inc'
 
      C
      C     Local parameters
      C
      C     Format string for time output:
      C
            CHARACTER*(*)         TDBFMT
            PARAMETER           ( TDBFMT =
           .                    'YYYY MON DD HR:MN:SC.### (TDB) ::TDB' )
 
      C
      C     The meta-kernel:
      C
            CHARACTER*(*)         METAKR
            PARAMETER           ( METAKR = 'viewpr.tm' )
 
 
      C
      C     Maximum number of intervals in any window:
      C
            INTEGER               MAXIVL
            PARAMETER           ( MAXIVL = 1000 )
 
      C
      C     Maximum result window size:
      C
            INTEGER               MAXWIN
            PARAMETER           ( MAXWIN = 2 * MAXIVL )
 
      C
      C     SPICELIB cell bound:
      C
            INTEGER               LBCELL
            PARAMETER           ( LBCELL = -5 )
 
      C
      C     String length parameters:
      C
            INTEGER               CORLEN
            PARAMETER           ( CORLEN = 10 )
 
            INTEGER               FRNMLN
            PARAMETER           ( FRNMLN = 32 )
 
            INTEGER               LNSIZE
            PARAMETER           ( LNSIZE = 200 )
 
            INTEGER               NAMLEN
            PARAMETER           ( NAMLEN = 32 )
 
            INTEGER               OPLEN
            PARAMETER           ( OPLEN  = 50 )
 
            INTEGER               TIMLEN
            PARAMETER           ( TIMLEN = 50 )
 
      C
      C     Local variables
      C
            CHARACTER*(CORLEN)    ABCORR
            CHARACTER*(NAMLEN)    CRDSYS
            CHARACTER*(NAMLEN)    COORD
            CHARACTER*(LNSIZE)    LINE
            CHARACTER*(FRNMLN)    OBSFRM
            CHARACTER*(OPLEN)     RELATE
            CHARACTER*(NAMLEN)    SRFPT
            CHARACTER*(TIMLEN)    START
            CHARACTER*(TIMLEN)    STOP
            CHARACTER*(NAMLEN)    TARGET
            CHARACTER*(TIMLEN)    TIMSTR
            CHARACTER*(LNSIZE)    TITLE
 
            DOUBLE PRECISION      ADJUST
 
      C
      C     Confinement window used to store interval to be searched:
      C
            DOUBLE PRECISION      CNFINE ( LBCELL : MAXWIN )
            DOUBLE PRECISION      ELVLIM
            DOUBLE PRECISION      ETBEG
            DOUBLE PRECISION      ETEND
            DOUBLE PRECISION      INTBEG
            DOUBLE PRECISION      INTEND
            DOUBLE PRECISION      REVLIM
 
      C
      C     STEPSZ is the step size, measured in seconds, used to search
      C     for times bracketing a state transition.
      C
            DOUBLE PRECISION      STEPSZ
 
      C
      C     Result window used to store rise/set times:
      C
            DOUBLE PRECISION      RISWIN ( LBCELL : MAXWIN )
 
      C
      C     Workspace array:
      C
            DOUBLE PRECISION      WORK   ( LBCELL : MAXWIN,  NWMAX )
 
 
            INTEGER               I
            INTEGER               WINSIZ
 
      C
      C     Load the meta-kernel.
      C
            CALL FURNSH ( METAKR )
 
      C
      C     Assign the inputs for our search.
      C
      C     Since we're interested in the apparent location of the
      C     target, we use light time and stellar aberration
      C     corrections.  We use the "converged Newtonian" form
      C     of the light time correction because this choice may
      C     increase the accuracy of the occultation times we'll
      C     compute using GFOCLT.
      C
            SRFPT  = 'NEW_NORCIA'
            OBSFRM = 'NEW_NORCIA_TOPO'
            TARGET = 'TGO'
            ABCORR = 'CN+S'
            START  = '2018 JUN 10 TDB'
            STOP   = '2018 JUN 14 TDB'
            ELVLIM =  6.0D0
      C
      C     The elevation limit above has units of degrees; we convert
      C     this value to radians for computation using SPICE routines.
      C     We'll store the equivalent value in radians in REVLIM.
      C
            REVLIM = RPD() * ELVLIM
 
      C
      C     Since SPICE doesn't directly support the AZ/EL coordinate
      C     system, we use the equivalent constraint
      C
      C        latitude > REVLIM
      C
      C     in the latitudinal coordinate system, where the reference
      C     frame is topocentric and is centered at the viewing location.
      C
            CRDSYS = 'LATITUDINAL'
            COORD  = 'LATITUDE'
            RELATE = '>'
 
      C
      C     The adjustment value only applies to absolute extrema
      C     searches; simply give it an initial value of zero
      C     for this inequality search.
      C
            ADJUST = 0.D0
 
      C
      C     STEPSZ is the step size, measured in seconds, used to search
      C     for times bracketing a state transition. Since we don't expect
      C     any events of interest to be shorter than five minutes, and
      C     since the separation between events is well over 5 minutes,
      C     we'll use this value as our step size. Units are seconds.
      C
            STEPSZ = 300.D0
 
      C
      C     Display a banner for the output report:
      C
            TITLE  = 'Inputs for target visibility search:'
            CALL TOSTDO ( ' '   )
            CALL TOSTDO ( TITLE )
            CALL TOSTDO ( ' '   )
 
            LINE   = '   Target                       = #'
            CALL REPMC  ( LINE, '#', TARGET, LINE )
            CALL TOSTDO ( LINE )
 
            LINE   = '   Observation surface location = #'
            CALL REPMC  ( LINE, '#', SRFPT,  LINE )
            CALL TOSTDO ( LINE )
 
            LINE   = '   Observer''s reference frame   = #'
            CALL REPMC  ( LINE, '#', OBSFRM,  LINE )
            CALL TOSTDO ( LINE )
 
            LINE   = '   Elevation limit (degrees)    = #'
            CALL REPMF ( LINE, '#', ELVLIM, 7, 'F', LINE )
            CALL TOSTDO ( LINE )
 
            LINE   = '   Aberration correction        = #'
            CALL REPMC  ( LINE, '#', ABCORR, LINE )
            CALL TOSTDO ( LINE )
 
            LINE   = '   Step size (seconds)          = #'
            CALL REPMF ( LINE, '#', STEPSZ, 9, 'F', LINE )
            CALL TOSTDO ( LINE )
 
      C
      C     Convert the start and stop times to ET.
      C
            CALL STR2ET ( START, ETBEG )
            CALL STR2ET ( STOP,  ETEND )
 
      C
      C     Display the search interval start and stop times
      C     using the format shown below.
      C
      C        2004 MAY 06 20:15:00.000 (TDB)
      C
            CALL TIMOUT ( ETBEG, TDBFMT, TIMSTR )
            LINE = '   Start time                   = '//TIMSTR
            CALL TOSTDO ( LINE )
 
            CALL TIMOUT ( ETEND, TDBFMT, TIMSTR )
            LINE = '   Stop time                    = '//TIMSTR
            CALL TOSTDO ( LINE )
 
            CALL TOSTDO ( ' ' )
 
      C
      C     Every SPICELIB window must have its size initialized.
      C
      C     Initialize the "confinement" window with the interval
      C     over which we'll conduct the search.
      C
            CALL SSIZED ( MAXWIN, CNFINE )
 
            CALL WNINSD ( ETBEG,  ETEND, CNFINE )
 
      C
      C     Initialize the result window; this window will contain
      C     the rise/set times found by our search.
      C
            CALL SSIZED ( MAXWIN, RISWIN )
 
      C
      C     In the call below, the workspace dimensions are
      C
      C        ( MAXWIN, NWMAX )
      C
      C     Now search for the time period, within our confinement
      C     window, during which the apparent target has elevation
      C     at least equal to the elevation limit.
      C
            CALL GFPOSC ( TARGET, OBSFRM, ABCORR, SRFPT,
           .              CRDSYS, COORD,  RELATE, REVLIM,
           .              ADJUST, STEPSZ, CNFINE, MAXWIN,
           .              NWMAX,  WORK,   RISWIN         )
 
      C
      C     The function WNCARD returns the number of intervals
      C     in a SPICE window.
      C
            WINSIZ = WNCARD( RISWIN )
 
            IF ( WINSIZ .EQ. 0 ) THEN
 
               WRITE (*,*) 'No events were found.'
 
            ELSE
      C
      C        Display the view periods.
      C
               LINE = 'Visibility times of # as seen from #:'
               CALL REPMC ( LINE, '#', TARGET, LINE )
               CALL REPMC ( LINE, '#', SRFPT,  LINE )
 
               CALL TOSTDO ( LINE )
               CALL TOSTDO ( ' '  )
 
               DO I = 1, WINSIZ
      C
      C           Fetch the start and stop times of the Ith interval
      C           from the search result window RISWIN.
      C
                  CALL WNFETD ( RISWIN, I, INTBEG, INTEND )
 
      C
      C           Convert the rise time to a TDB calendar string.
      C
                  CALL TIMOUT ( INTBEG, TDBFMT, TIMSTR )
 
      C
      C           Write the string to standard output.
      C
                  IF ( I .EQ. 1 ) THEN
                     LINE = 'Visibility or window start time:  #'
                  ELSE
                     LINE = 'Visibility start time:            #'
                  END IF
 
                  CALL REPMC ( LINE, '#', TIMSTR, LINE )
                  CALL TOSTDO ( LINE )
 
      C
      C           Convert the set time to a TDB calendar string.
      C
                  CALL TIMOUT ( INTEND, TDBFMT, TIMSTR )
      C
      C           Write the string to standard output.
      C
                  IF ( I .EQ. WINSIZ ) THEN
                     LINE = 'Visibility or window stop time:   #'
                  ELSE
                     LINE = 'Visibility stop time:             #'
                  END IF
 
                  CALL REPMC ( LINE, '#', TIMSTR, LINE )
                  CALL TOSTDO ( LINE )
 
                  CALL TOSTDO ( ' ' )
 
               END DO
 
            END IF
 
            END
 
 
Solution Sample Output
 
   Numerical results shown for this example may differ across platforms
   since the results depend on the SPICE kernels used as input and on the
   host platform's arithmetic implementation.
 
   After compiling the program, execute it. The output is:
 
 
      Inputs for target visibility search:
 
         Target                       = TGO
         Observation surface location = NEW_NORCIA
         Observer's reference frame   = NEW_NORCIA_TOPO
         Elevation limit (degrees)    = 6.000000
         Aberration correction        = CN+S
         Step size (seconds)          = 300.000000
         Start time                   = 2018 JUN 10 00:00:00.000 (TDB)
         Stop time                    = 2018 JUN 14 00:00:00.000 (TDB)
 
      Visibility times of TGO as seen from NEW_NORCIA:
 
      Visibility or window start time:  2018 JUN 10 00:00:00.000 (TDB)
      Visibility stop time:             2018 JUN 10 02:11:17.355 (TDB)
 
      Visibility start time:            2018 JUN 10 13:19:58.777 (TDB)
      Visibility stop time:             2018 JUN 11 02:08:16.008 (TDB)
 
      Visibility start time:            2018 JUN 11 13:16:50.542 (TDB)
      Visibility stop time:             2018 JUN 12 02:05:12.548 (TDB)
 
      Visibility start time:            2018 JUN 12 13:13:38.573 (TDB)
      Visibility stop time:             2018 JUN 13 02:02:06.618 (TDB)
 
      Visibility start time:            2018 JUN 13 13:10:23.432 (TDB)
      Visibility or window stop time:   2018 JUN 14 00:00:00.000 (TDB)
 
 
 
Find Times when Target is Visible
===========================================================================
 
 
Task Statement
--------------------------------------------------------
 
   Extend the program of the previous chapter to find times when the
   ExoMars-16 TGO orbiter is:
 
       --   Above the elevation limit in the NEW_NORCIA_TOPO topocentric
            reference frame.
 
       --   and is not occulted by Mars
 
   Finding time intervals that satisfy the second condition requires a
   search for occultations of the spacecraft by Mars. Perform this search
   twice: once using an ellipsoidal shape model for Mars, and once using a
   DSK shape model.
 
   Compute the final results twice as well, using the results of both
   occultation searches.
 
   For each of the two shape model cases, store the set of time intervals
   when the spacecraft is visible in a SPICELIB window. We'll call this the
   ``result window.''
 
   Display each of the intervals in the result window as a pair of start
   and stop times. Express each time as a TDB calendar date using the same
   format as in the previous program.
 
 
Learning Goals
--------------------------------------------------------
 
   Familiarity with the GF occultation finding routine GFOCLT. Experience
   with Digital Shape Kernel (DSK) shape models. Further experience with
   the SPICELIB window routines.
 
 
Approach
--------------------------------------------------------
 
 
Solution steps
 
   A possible solution would consist of the following steps:
 
       1.   Use the meta-kernel from the previous chapter as the starting
            point. Add more kernels to it as needed.
 
            Name the meta-kernel 'visibl.tm'.
 
       2.   Include the code from the program of the previous chapter in a
            new source file; modify this code to create the new program.
 
       3.   Your program will need additional windows to capture the
            results of occultation searches performed using both
            ellipsoidal and DSK shape models. Additional windows will be
            needed to compute the set differences of the elevation search
            (``view period'') window and each of the occultation search
            windows. Further details are provided below.
 
            Declare additional output SPICELIB windows and initialize them
            using SSIZED.
 
       4.   The remaining steps can be performed twice: once using an
            ellipsoidal shape model for Mars, and once using a DSK Mars
            shape model. Alternatively, two copies of the entire solution
            program can be created: one for each shape model.
 
       5.   Search for occultations of the ExoMars-16 TGO orbiter as seen
            from New Norcia station using GFOCLT. Use as the confinement
            window for this search the result window from the elevation
            search performed by GFPOSC.
 
            Since occultations occur when the apparent ExoMars-16 TGO
            spacecraft position is behind the apparent figure of Mars,
            light time correction must be performed for the occultation
            search. To improve accuracy of the occultation state
            determination, use ``converged Newtonian'' light time
            correction.
 
       6.   Use the SPICELIB window subtraction routine WNDIFD to subtract
            the window of times when the spacecraft is occulted from the
            window of times when the spacecraft is above the elevation
            limit. The difference window is the final result.
 
       7.   Modify the code to display the contents of the difference
            window.
 
   This completes the assignment.
 
 
Solution
--------------------------------------------------------
 
 
Solution Meta-Kernel
 
   The meta-kernel we created for the solution to this exercise is named
   'visibl.tm'. Its contents follow:
 
      KPL/MK
 
         This is the meta-kernel used in the solution of the tasks in the
         Geometric Event Finding Hands On Lesson.
 
         The names and contents of the kernels referenced by this
         meta-kernel are as follows:
 
            1.  Solar System Ephemeris SPK, subsetted to cover only the
                time range of interest:
 
                   de430.bsp
 
            2.  Martian Satellite Ephemeris SPK, subsetted to cover only
                the time range of interest:
 
                   mar085.bsp
 
            3.  ESA stations SPK:
 
                   estrack_v01.bsp
 
            4.  ESA stations frame definitions:
 
                   estrack_v01.tf
 
            5.  EARTH_FIXED/ITRF93 frame connection:
 
                   earthfixeditrf93.tf
 
            6.  Binary PCK for Earth:
 
                   earth_070425_370426_predict.bpc
 
            7.  ExoMars-16 TGO Spacecraft Trajectory SPK, subsetted to
                cover only the time range of interest:
 
                   em16_tgo_mlt_20171205_20230115_v01.bsp
 
            8.  Generic LSK:
 
                   naif0012.tls
 
            9.  Generic PCK:
 
                  pck00010.tpc
 
           10. Low-resolution Mars DSK:
 
                  mars_lowres.bds
 
      \begindata
 
         KERNELS_TO_LOAD = (
 
            'kernels/spk/de430.bsp'
            'kernels/spk/mar085.bsp',
            'kernels/spk/estrack_v01.bsp'
            'kernels/fk/estrack_v01.tf'
            'kernels/fk/earthfixeditrf93.tf'
            'kernels/pck/earth_070425_370426_predict.bpc'
            'kernels/lsk/naif0012.tls'
            'kernels/spk/em16_tgo_mlt_20171205_20230115_v01.bsp'
            'kernels/pck/pck00010.tpc'
            'kernels/dsk/mars_lowres.bds'
 
                           )
 
      \begintext
 
 
 
Solution Code
 
            PROGRAM VISIBL
            IMPLICIT NONE
      C
      C     Find and display the window of times when the ExoMars-16
      C     TGO spacecraft is above a specified elevation limit in the
      C     topocentric reference frame of ESA's New Norcia station
      C     and is not occulted by Mars.
      C
 
      C
      C     SPICELIB functions
      C
            DOUBLE PRECISION      RPD
            INTEGER               WNCARD
 
      C
      C     Global GF parameters: we import from this file
      C     the definition of the GF workspace size parameter
      C
      C        NWMAX
      C
      C     and the occultation parameters
      C
      C        OCCLN
      C        SHPLEN
      C
            INCLUDE 'gf.inc'
 
      C
      C     Local parameters
      C
      C     Format string for time output:
      C
            CHARACTER*(*)         TDBFMT
            PARAMETER           ( TDBFMT =
           .                    'YYYY MON DD HR:MN:SC.### TDB ::TDB' )
      C
      C     The meta-kernel:
      C
            CHARACTER*(*)         METAKR
            PARAMETER           ( METAKR = 'visibl.tm' )
 
      C
      C     Maximum number of events we can handle in our event set:
      C
            INTEGER               MAXEVT
            PARAMETER           ( MAXEVT = 1000 )
 
      C
      C     Maximum result window size:
      C
            INTEGER               MAXWIN
            PARAMETER           ( MAXWIN = 2 * MAXEVT )
 
      C
      C     SPICELIB cell bound:
      C
            INTEGER               LBCELL
            PARAMETER           ( LBCELL = -5 )
 
      C
      C     String length parameters:
      C
            INTEGER               BDNMLN
            PARAMETER           ( BDNMLN = 36 )
 
            INTEGER               CORLEN
            PARAMETER           ( CORLEN = 10 )
 
            INTEGER               FRNMLN
            PARAMETER           ( FRNMLN = 32 )
 
            INTEGER               LNSIZE
            PARAMETER           ( LNSIZE = 78 )
 
            INTEGER               MTHLEN
            PARAMETER           ( MTHLEN = 100 )
 
            INTEGER               NAMLEN
            PARAMETER           ( NAMLEN = 32 )
 
            INTEGER               OPLEN
            PARAMETER           ( OPLEN  = 50 )
 
            INTEGER               TIMLEN
            PARAMETER           ( TIMLEN = 28 )
 
      C
      C     Local variables
      C
            CHARACTER*(CORLEN)    ABCORR
            CHARACTER*(BDNMLN)    BACK
            CHARACTER*(FRNMLN)    BFRAME
            CHARACTER*(MTHLEN)    BSHAPE
            CHARACTER*(TIMLEN)    BTMSTR
            CHARACTER*(NAMLEN)    CRDSYS
            CHARACTER*(NAMLEN)    COORD
            CHARACTER*(TIMLEN)    ETMSTR
            CHARACTER*(FRNMLN)    FFRAME
            CHARACTER*(FRNMLN)    FRAME
            CHARACTER*(BDNMLN)    FRONT
            CHARACTER*(MTHLEN)    FSHAPE
            CHARACTER*(LNSIZE)    LINE
            CHARACTER*(OCLLN)     OCCTYP
            CHARACTER*(OPLEN)     RELATE
            CHARACTER*(NAMLEN)    SRFPT
            CHARACTER*(TIMLEN)    START
            CHARACTER*(TIMLEN)    STOP
            CHARACTER*(NAMLEN)    TARGET
            CHARACTER*(LNSIZE)    TITLE
 
            DOUBLE PRECISION      ADJUST
 
      C
      C     Confinement window used to store interval to be searched:
      C
            DOUBLE PRECISION      CNFINE ( LBCELL : MAXEVT )
            DOUBLE PRECISION      DINTBG
            DOUBLE PRECISION      DINTEN
            DOUBLE PRECISION      ELVLIM
            DOUBLE PRECISION      ETBEG
            DOUBLE PRECISION      ETEND
            DOUBLE PRECISION      INTBEG
            DOUBLE PRECISION      INTEND
            DOUBLE PRECISION      REVLIM
 
      C
      C     STEPSZ is the step size, measured in seconds, used to search
      C     for times bracketing a state transition.
      C
            DOUBLE PRECISION      STEPSZ
 
      C
      C     Result window used to store occultation times:
      C
            DOUBLE PRECISION      OCCWIN ( LBCELL : MAXWIN )
 
      C
      C     Result window used to store occultation times
      C     computed using DSK data:
      C
            DOUBLE PRECISION      DOCWIN ( LBCELL : MAXWIN )
 
      C
      C     Result window used to store rise/set times:
      C
            DOUBLE PRECISION      RISWIN ( LBCELL : MAXWIN )
 
      C
      C     Result windows used to store visibility periods:
      C
            DOUBLE PRECISION      DVISWN ( LBCELL : MAXWIN )
            DOUBLE PRECISION      EVISWN ( LBCELL : MAXWIN )
 
      C
      C     Workspace array:
      C
            DOUBLE PRECISION      WORK   ( LBCELL : MAXWIN,  NWMAX )
 
 
            INTEGER               I
            INTEGER               WINSIZ
 
      C
      C     Load the meta-kernel.
      C
            CALL FURNSH ( METAKR )
 
      C
      C     Assign the inputs for our search.
      C
            SRFPT  = 'NEW_NORCIA'
            FRAME  = 'NEW_NORCIA_TOPO'
            TARGET = 'TGO'
            ABCORR = 'CN+S'
            START  = '2018 JUN 10 TDB'
            STOP   = '2018 JUN 14 TDB'
            ELVLIM =  6.0D0
 
      C
      C     The elevation limit above has units of degrees; we convert
      C     this value to radians for computation using SPICE routines.
      C     We'll store the equivalent value in radians in REVLIM.
      C
            REVLIM = RPD() * ELVLIM
 
      C
      C     Since we're interested in the apparent location of the
      C     target, we use light time and stellar aberration
      C     corrections.
      C
      C     Since SPICE doesn't directly support the AZ/EL coordinate
      C     system, we use the equivalent constraint
      C
      C        latitude > REVLIM
      C
      C     in the latitudinal coordinate system, where the reference
      C     frame is topocentric and is centered at the viewing location.
      C
            CRDSYS = 'LATITUDINAL'
            COORD  = 'LATITUDE'
            RELATE = '>'
 
      C
      C     STEPSZ is the step size, measured in seconds, used to search
      C     for times bracketing a state transition. Since we don't expect
      C     any events of interest to be shorter than five minutes, and
      C     since the separation between events is well over 5 minutes,
      C     we'll use this value as our step size. Units are seconds.
      C
            STEPSZ = 300.D0
 
      C
      C     We model the target shape as a point. We either model the
      C     blocking body's shape as an ellipsoid, or we represent its shap
      e
      C     using actual topographic data. No body-fixed reference frame is
      C     required for the target since its orientation is not used.
      C
      C     We'll set the shape specifications just before our calls to
      C     the GF occulation finding routine GFOCLT.
      C
            BACK   = TARGET
            BSHAPE = 'POINT'
            BFRAME = ' '
            FRONT  = 'MARS'
            FFRAME = 'IAU_MARS'
 
      C
      C     The occultation type should be set to 'ANY' for a point
      C     target.
      C
            OCCTYP = 'ANY'
 
      C
      C     Display a banner for the output report:
      C
            TITLE  = 'Inputs for target visibility search:'
            CALL TOSTDO ( ' '   )
            CALL TOSTDO ( TITLE )
            CALL TOSTDO ( ' '   )
 
            LINE   = '   Target                       = #'
            CALL REPMC  ( LINE, '#', TARGET, LINE )
            CALL TOSTDO ( LINE )
 
            LINE   = '   Observation surface location = #'
            CALL REPMC  ( LINE, '#', SRFPT,  LINE )
            CALL TOSTDO ( LINE )
 
            LINE   = '   Observer''s reference frame   = #'
            CALL REPMC  ( LINE, '#', FRAME,  LINE )
            CALL TOSTDO ( LINE )
 
            LINE   = '   Blocking body                = #'
            CALL REPMC  ( LINE, '#', FRONT, LINE )
            CALL TOSTDO ( LINE )
 
            LINE   = '   Blocker''s reference frame    = #'
            CALL REPMC  ( LINE, '#', FFRAME,  LINE )
            CALL TOSTDO ( LINE )
 
            LINE   = '   Elevation limit (degrees)    = #'
            CALL REPMF ( LINE, '#', ELVLIM, 7, 'F', LINE )
            CALL TOSTDO ( LINE )
 
            LINE   = '   Aberration correction        = #'
            CALL REPMC  ( LINE, '#', ABCORR, LINE )
            CALL TOSTDO ( LINE )
 
            LINE   = '   Step size (seconds)          = #'
            CALL REPMF ( LINE, '#', STEPSZ, 9, 'F', LINE )
            CALL TOSTDO ( LINE )
 
      C
      C     Convert the start and stop times to ET.
      C
            CALL STR2ET ( START, ETBEG )
            CALL STR2ET ( STOP,  ETEND )
 
      C
      C     Display the search interval start and stop times
      C     using the format shown below.
      C
      C        2004 MAY 06 20:15:00.000 (TDB)
      C
            CALL TIMOUT ( ETBEG, TDBFMT, BTMSTR )
            LINE = '   Start time                   = '//BTMSTR
            CALL TOSTDO ( LINE )
 
            CALL TIMOUT ( ETEND, TDBFMT, ETMSTR )
            LINE = '   Stop time                    = '//ETMSTR
            CALL TOSTDO ( LINE )
 
            CALL TOSTDO ( ' ' )
 
      C
      C     Every SPICELIB window must have its size initialized.
      C
      C     Initialize the "confinement" window with the interval
      C     over which we'll conduct the search.
      C
            CALL SSIZED ( MAXWIN, CNFINE )
 
            CALL WNINSD ( ETBEG,  ETEND, CNFINE )
 
      C
      C     Initialize the result window; this window will contain
      C     the rise/set times found by our search.
      C
            CALL SSIZED ( MAXWIN, RISWIN )
 
      C
      C     Initialize the occultation and visibility windows.
      C
            CALL SSIZED ( MAXWIN, OCCWIN )
            CALL SSIZED ( MAXWIN, DOCWIN )
            CALL SSIZED ( MAXWIN, EVISWN )
            CALL SSIZED ( MAXWIN, DVISWN )
 
      C
      C     The adjustment value only applies to absolute extrema
      C     searches;  simply give it an initial value of zero
      C     for this inequality search.
      C
            ADJUST = 0.D0
 
      C
      C     Note that the workspace dimensions are ( MAXWIN, NWMAX ).
      C
      C     Now search for the time period, within our confinement
      C     window, during which the apparent target has elevation
      C     at least equal to the elevation limit.
      C
            CALL GFPOSC ( TARGET, FRAME,  ABCORR, SRFPT,
           .              CRDSYS, COORD,  RELATE, REVLIM,
           .              ADJUST, STEPSZ, CNFINE, MAXWIN,
           .              NWMAX,  WORK,   RISWIN         )
 
      C
      C     Now find the times when the apparent target is above
      C     the elevation limit and is not occulted by the
      C     blocking body (Mars). We'll find the times when the target
      C     is above the elevation limit and *is* occulted, then subtract
      C     that window from the view period window RISWIN found above.
      C
      C     For this occultation search, we can use RISWIN as
      C     the confinement window because we're not interested in
      C     occultations that occur when the target is below the
      C     elevation limit.
      C
      C     Find occultations within the view period window.
      C
            FSHAPE = 'ELLIPSOID'
 
            WRITE (*,*) 'Searching using ellipsoid target shape model...'
 
            CALL GFOCLT ( OCCTYP, FRONT,  FSHAPE, FFRAME,
           .              BACK,   BSHAPE, BFRAME, ABCORR,
           .              SRFPT,  STEPSZ, RISWIN, OCCWIN )
            WRITE (*,*) 'Done.'
 
      C
      C     Subtract the occultation window from the view period
      C     window: this yields the time periods when the target
      C     is visible.
      C
            CALL WNDIFD ( RISWIN, OCCWIN, EVISWN )
 
      C
      C     Repeat the search using low-resolution DSK data
      C     for the front body.
      C
            FSHAPE = 'DSK/UNPRIORITIZED'
 
            WRITE (*,*) 'Searching using DSK target shape model...'
 
            CALL GFOCLT ( OCCTYP, FRONT,  FSHAPE, FFRAME,
           .              BACK,   BSHAPE, BFRAME, ABCORR,
           .              SRFPT,  STEPSZ, RISWIN, DOCWIN )
            WRITE (*,*) 'Done.'
 
            CALL WNDIFD ( RISWIN, DOCWIN, DVISWN )
 
      C
      C     The function WNCARD returns the number of intervals
      C     in a SPICE window.
      C
            WINSIZ = WNCARD( EVISWN )
 
            IF ( WINSIZ .EQ. 0 ) THEN
 
               WRITE (*,*) 'No events were found.'
 
            ELSE
      C
      C        Display the visibility time periods.
      C
               WRITE (*,*) ' '
               LINE = 'Visibility start and stop times of '
           .   //     '# as seen from #'
               CALL REPMC ( LINE, '#', TARGET, LINE )
               CALL REPMC ( LINE, '#', SRFPT,  LINE )
 
               WRITE (*, '(A)') LINE
               WRITE (*, '(A)') 'using both ellipsoidal and DSK '
           .   //               'target shape models:'
               WRITE (*,*) ' '
 
               DO I = 1, WINSIZ
      C
      C           Fetch the start and stop times of the Ith interval
      C           from the ellipsoid search result window EVISWN.
      C
                  CALL WNFETD ( EVISWN, I, INTBEG, INTEND )
      C
      C           Convert the start and stop times to TDB calendar
      C           strings. Write the results.
      C
                  CALL TIMOUT ( INTBEG, TDBFMT, BTMSTR )
                  CALL TIMOUT ( INTEND, TDBFMT, ETMSTR )
 
                  WRITE (*,'('' Ell: '',A, '' : '', A)' ) BTMSTR, ETMSTR
      C
      C           Fetch the start and stop times of the Ith interval
      C           from the DSK search result window DVISWN.
      C
                  CALL WNFETD ( DVISWN, I, DINTBG, DINTEN )
      C
      C           Convert the start and stop times to TDB calendar
      C           strings. Write the results.
      C
                  CALL TIMOUT ( DINTBG, TDBFMT, BTMSTR )
                  CALL TIMOUT ( DINTEN, TDBFMT, ETMSTR )
 
                  WRITE (*,'('' DSK: '',A, '' : '', A)' ) BTMSTR, ETMSTR
                  WRITE (*,*) ' '
 
               END DO
 
            END IF
 
            END
 
 
 
 
Solution Sample Output
 
   Numerical results shown for this example may differ across platforms
   since the results depend on the SPICE kernels used as input and on the
   host platform's arithmetic implementation.
 
   After compiling the program, execute it. The output is:
 
 
      Inputs for target visibility search:
 
         Target                       = TGO
         Observation surface location = NEW_NORCIA
         Observer's reference frame   = NEW_NORCIA_TOPO
         Blocking body                = MARS
         Blocker's reference frame    = IAU_MARS
         Elevation limit (degrees)    = 6.000000
         Aberration correction        = CN+S
         Step size (seconds)          = 300.000000
         Start time                   = 2018 JUN 10 00:00:00.000 TDB
         Stop time                    = 2018 JUN 14 00:00:00.000 TDB
 
       Searching using ellipsoid target shape model...
       Done.
       Searching using DSK target shape model...
       Done.
 
      Visibility start and stop times of TGO as seen from NEW_NORCIA
      using both ellipsoidal and DSK target shape models:
 
       Ell: 2018 JUN 10 00:00:00.000 TDB : 2018 JUN 10 01:00:30.640 TDB
       DSK: 2018 JUN 10 00:00:00.000 TDB : 2018 JUN 10 01:00:28.220 TDB
 
       Ell: 2018 JUN 10 01:41:03.610 TDB : 2018 JUN 10 02:11:17.355 TDB
       DSK: 2018 JUN 10 01:41:01.630 TDB : 2018 JUN 10 02:11:17.355 TDB
 
       Ell: 2018 JUN 10 13:28:28.785 TDB : 2018 JUN 10 14:45:38.197 TDB
       DSK: 2018 JUN 10 13:28:26.205 TDB : 2018 JUN 10 14:45:35.493 TDB
 
       Ell: 2018 JUN 10 15:26:21.981 TDB : 2018 JUN 10 16:43:32.192 TDB
       DSK: 2018 JUN 10 15:26:19.598 TDB : 2018 JUN 10 16:43:28.927 TDB
 
       Ell: 2018 JUN 10 17:24:17.290 TDB : 2018 JUN 10 18:41:27.535 TDB
       DSK: 2018 JUN 10 17:24:15.690 TDB : 2018 JUN 10 18:41:24.797 TDB
 
       Ell: 2018 JUN 10 19:22:13.628 TDB : 2018 JUN 10 20:39:21.785 TDB
       DSK: 2018 JUN 10 19:22:12.222 TDB : 2018 JUN 10 20:39:19.310 TDB
 
       Ell: 2018 JUN 10 21:20:08.856 TDB : 2018 JUN 10 22:37:12.445 TDB
       DSK: 2018 JUN 10 21:20:07.160 TDB : 2018 JUN 10 22:37:09.488 TDB
 
       Ell: 2018 JUN 10 23:18:00.834 TDB : 2018 JUN 11 00:35:01.034 TDB
       DSK: 2018 JUN 10 23:17:58.772 TDB : 2018 JUN 11 00:34:58.698 TDB
 
       Ell: 2018 JUN 11 01:15:50.883 TDB : 2018 JUN 11 02:08:16.008 TDB
       DSK: 2018 JUN 11 01:15:48.915 TDB : 2018 JUN 11 02:08:16.008 TDB
 
       Ell: 2018 JUN 11 13:16:50.542 TDB : 2018 JUN 11 14:20:09.789 TDB
       DSK: 2018 JUN 11 13:16:50.542 TDB : 2018 JUN 11 14:20:07.002 TDB
 
       Ell: 2018 JUN 11 15:01:08.370 TDB : 2018 JUN 11 16:18:03.385 TDB
       DSK: 2018 JUN 11 15:01:05.872 TDB : 2018 JUN 11 16:18:00.245 TDB
 
       Ell: 2018 JUN 11 16:59:03.014 TDB : 2018 JUN 11 18:15:58.739 TDB
       DSK: 2018 JUN 11 16:59:00.798 TDB : 2018 JUN 11 18:15:55.713 TDB
 
       Ell: 2018 JUN 11 18:56:59.199 TDB : 2018 JUN 11 20:13:54.308 TDB
       DSK: 2018 JUN 11 18:56:57.725 TDB : 2018 JUN 11 20:13:51.980 TDB
 
       Ell: 2018 JUN 11 20:54:55.301 TDB : 2018 JUN 11 22:11:47.045 TDB
       DSK: 2018 JUN 11 20:54:53.724 TDB : 2018 JUN 11 22:11:44.029 TDB
 
       Ell: 2018 JUN 11 22:52:48.925 TDB : 2018 JUN 12 00:09:35.868 TDB
       DSK: 2018 JUN 11 22:52:47.004 TDB : 2018 JUN 12 00:09:33.513 TDB
 
       Ell: 2018 JUN 12 00:50:39.046 TDB : 2018 JUN 12 02:05:12.548 TDB
       DSK: 2018 JUN 12 00:50:37.040 TDB : 2018 JUN 12 02:05:12.548 TDB
 
       Ell: 2018 JUN 12 13:13:38.573 TDB : 2018 JUN 12 13:54:43.524 TDB
       DSK: 2018 JUN 12 13:13:38.573 TDB : 2018 JUN 12 13:54:41.265 TDB
 
       Ell: 2018 JUN 12 14:35:54.054 TDB : 2018 JUN 12 15:52:36.256 TDB
       DSK: 2018 JUN 12 14:35:51.624 TDB : 2018 JUN 12 15:52:34.091 TDB
 
       Ell: 2018 JUN 12 16:33:47.502 TDB : 2018 JUN 12 17:50:30.988 TDB
       DSK: 2018 JUN 12 16:33:45.089 TDB : 2018 JUN 12 17:50:29.020 TDB
 
       Ell: 2018 JUN 12 18:31:42.896 TDB : 2018 JUN 12 19:48:26.827 TDB
       DSK: 2018 JUN 12 18:31:41.085 TDB : 2018 JUN 12 19:48:23.878 TDB
 
       Ell: 2018 JUN 12 20:29:39.039 TDB : 2018 JUN 12 21:46:20.933 TDB
       DSK: 2018 JUN 12 20:29:37.575 TDB : 2018 JUN 12 21:46:18.430 TDB
 
       Ell: 2018 JUN 12 22:27:33.596 TDB : 2018 JUN 12 23:44:11.473 TDB
       DSK: 2018 JUN 12 22:27:31.895 TDB : 2018 JUN 12 23:44:08.681 TDB
 
       Ell: 2018 JUN 13 00:25:24.992 TDB : 2018 JUN 13 01:42:00.777 TDB
       DSK: 2018 JUN 13 00:25:22.950 TDB : 2018 JUN 13 01:41:58.417 TDB
 
       Ell: 2018 JUN 13 13:10:23.432 TDB : 2018 JUN 13 13:29:19.789 TDB
       DSK: 2018 JUN 13 13:10:23.432 TDB : 2018 JUN 13 13:29:18.021 TDB
 
       Ell: 2018 JUN 13 14:10:38.985 TDB : 2018 JUN 13 15:27:11.882 TDB
       DSK: 2018 JUN 13 14:10:36.850 TDB : 2018 JUN 13 15:27:09.686 TDB
 
       Ell: 2018 JUN 13 16:08:31.566 TDB : 2018 JUN 13 17:25:06.068 TDB
       DSK: 2018 JUN 13 16:08:29.172 TDB : 2018 JUN 13 17:25:04.013 TDB
 
       Ell: 2018 JUN 13 18:06:26.219 TDB : 2018 JUN 13 19:23:01.820 TDB
       DSK: 2018 JUN 13 18:06:23.924 TDB : 2018 JUN 13 19:22:59.754 TDB
 
       Ell: 2018 JUN 13 20:04:22.175 TDB : 2018 JUN 13 21:20:57.296 TDB
       DSK: 2018 JUN 13 20:04:20.652 TDB : 2018 JUN 13 21:20:54.998 TDB
 
       Ell: 2018 JUN 13 22:02:17.650 TDB : 2018 JUN 13 23:18:49.624 TDB
       DSK: 2018 JUN 13 22:02:16.147 TDB : 2018 JUN 13 23:18:47.458 TDB
 
 
 
Extra Credit
===========================================================================
 
   In this ``extra credit'' section you will be presented with more complex
   tasks, aimed at improving your understanding of the geometry event
   finding subsystem and particularly the GFPOSC and GFDIST routines.
 
   These ``extra credit'' tasks are provided as task statements, and unlike
   the regular tasks, no approach or solution source code is provided. In
   the next section, you will find the numeric solutions to the questions
   asked in these tasks.
 
 
Task statements
--------------------------------------------------------
 
       1.   Write a program that finds the times, within the time range
 
            2018 JUN 10 TDB
            2018 JUN 11 TDB
 
            when the ExoMars-16 Trace Gas Orbiter (TGO) crosses Mars'
            equator. Display the results using TDB calendar dates and
            millisecond precision.
 
       2.   Write a program that finds the times, within the time range
 
            2018 JUN 10 TDB
            2018 JUN 11 TDB
 
            when the ExoMars-16 Trace Gas Orbiter (TGO) is at periapsis.
            Display the results using TDB calendar dates and millisecond
            precision.
 
       3.   Write a program that finds the times, within the time range
 
            2018 JUN 10 TDB
            2018 JUN 11 TDB
 
            when the ExoMars-16 Trace Gas Orbiter (TGO) is at apoapsis.
            Display the results using TDB calendar dates and millisecond
            precision.
 
 
Solutions
--------------------------------------------------------
 
       1.   Solution for the equator crossing search, using GFPOSC for the
            ExoMars-16 Trace Gas Orbiter (TGO) spacecraft latitude in the
            Mars body-fixed frame equal to 0 degrees:
 
 
      Inputs for equator crossing search:
 
         Target                       = TGO
         Observer                     = MARS
         Observer's reference frame   = IAU_MARS
         Latitude limit (degrees)     = 0.000000
         Aberration correction        = NONE
         Step size (seconds)          = 300.000000
         Start time                   = 2018 JUN 10 00:00:00.000 (TDB)
         Stop time                    = 2018 JUN 11 00:00:00.000 (TDB)
 
      TGO MARS equator crossing times:
 
       Equator crossing or start time:  2018 JUN 10 00:14:08.836 (TDB)
       Equator crossing time:           2018 JUN 10 01:12:34.582 (TDB)
       Equator crossing time:           2018 JUN 10 02:12:00.375 (TDB)
       Equator crossing time:           2018 JUN 10 03:10:28.808 (TDB)
       Equator crossing time:           2018 JUN 10 04:09:53.955 (TDB)
       Equator crossing time:           2018 JUN 10 05:08:23.919 (TDB)
       Equator crossing time:           2018 JUN 10 06:07:48.630 (TDB)
       Equator crossing time:           2018 JUN 10 07:06:17.539 (TDB)
       Equator crossing time:           2018 JUN 10 08:05:42.659 (TDB)
       Equator crossing time:           2018 JUN 10 09:04:09.120 (TDB)
       Equator crossing time:           2018 JUN 10 10:03:34.270 (TDB)
       Equator crossing time:           2018 JUN 10 11:01:59.269 (TDB)
       Equator crossing time:           2018 JUN 10 12:01:22.866 (TDB)
       Equator crossing time:           2018 JUN 10 12:59:49.352 (TDB)
       Equator crossing time:           2018 JUN 10 13:59:13.289 (TDB)
       Equator crossing time:           2018 JUN 10 14:57:41.242 (TDB)
       Equator crossing time:           2018 JUN 10 15:57:07.576 (TDB)
       Equator crossing time:           2018 JUN 10 16:55:35.266 (TDB)
       Equator crossing time:           2018 JUN 10 17:55:02.773 (TDB)
       Equator crossing time:           2018 JUN 10 18:53:30.271 (TDB)
       Equator crossing time:           2018 JUN 10 19:52:56.383 (TDB)
       Equator crossing time:           2018 JUN 10 20:51:23.966 (TDB)
       Equator crossing time:           2018 JUN 10 21:50:47.729 (TDB)
       Equator crossing time:           2018 JUN 10 22:49:14.385 (TDB)
       Equator crossing or stop time:   2018 JUN 10 23:48:37.583 (TDB)
 
       2.   Solution for the periapsis search, using GFDIST for the
            ExoMars-16 Trace Gas Orbiter (TGO) spacecraft distance from
            Mars at a local minimum:
 
 
      Inputs for periapsis search:
 
         Target                       = TGO
         Observer                     = MARS
         Aberration correction        = NONE
         Step size (seconds)          = 300.000000
         Start time                   = 2018 JUN 10 00:00:00.000 (TDB)
         Stop time                    = 2018 JUN 11 00:00:00.000 (TDB)
 
      TGO periapsis times:
 
       Periapsis or start time:         2018 JUN 10 00:43:06.357 (TDB)
       Periapsis time:                  2018 JUN 10 02:40:47.168 (TDB)
       Periapsis time:                  2018 JUN 10 04:38:45.496 (TDB)
       Periapsis time:                  2018 JUN 10 06:36:32.706 (TDB)
       Periapsis time:                  2018 JUN 10 08:34:10.548 (TDB)
       Periapsis time:                  2018 JUN 10 10:31:49.108 (TDB)
       Periapsis time:                  2018 JUN 10 12:29:20.342 (TDB)
       Periapsis time:                  2018 JUN 10 14:27:07.089 (TDB)
       Periapsis time:                  2018 JUN 10 16:25:36.081 (TDB)
       Periapsis time:                  2018 JUN 10 18:24:02.653 (TDB)
       Periapsis time:                  2018 JUN 10 20:22:23.184 (TDB)
       Periapsis or end time:           2018 JUN 10 22:20:12.453 (TDB)
 
       3.   Solution for the apoapsis search, using GFDIST for the
            ExoMars-16 Trace Gas Orbiter (TGO) spacecraft distance from
            Mars at a local maximum:
 
 
      Inputs for apoapsis search:
 
         Target                       = TGO
         Observer                     = MARS
         Aberration correction        = NONE
         Step size (seconds)          = 300.000000
         Start time                   = 2018 JUN 10 00:00:00.000 (TDB)
         Stop time                    = 2018 JUN 11 00:00:00.000 (TDB)
 
      TGO apoapsis times:
 
       Apoapsis or start time:          2018 JUN 10 01:41:44.632 (TDB)
       Apoapsis time:                   2018 JUN 10 03:39:31.106 (TDB)
       Apoapsis time:                   2018 JUN 10 05:37:22.115 (TDB)
       Apoapsis time:                   2018 JUN 10 07:34:59.674 (TDB)
       Apoapsis time:                   2018 JUN 10 09:32:25.708 (TDB)
       Apoapsis time:                   2018 JUN 10 11:29:47.945 (TDB)
       Apoapsis time:                   2018 JUN 10 13:27:30.200 (TDB)
       Apoapsis time:                   2018 JUN 10 15:26:02.524 (TDB)
       Apoapsis time:                   2018 JUN 10 17:24:37.842 (TDB)
       Apoapsis time:                   2018 JUN 10 19:23:11.265 (TDB)
       Apoapsis time:                   2018 JUN 10 21:21:13.530 (TDB)
       Apoapsis or stop time:           2018 JUN 10 23:18:56.796 (TDB)
 
