 
SPKDIFF User's Guide
===========================================================================
 
   Last revised on 2012 FEB 15 by B. V. Semenov.
 
 
Abstract
--------------------------------------------------------
 
   SPKDIFF provides means for comparing the trajectories of two bodies or
   sampling the trajectory of a single body using data from SPICE kernels.
 
 
Summary
--------------------------------------------------------
 
   SPKDIFF provides means for comparing the trajectories of two bodies or
   sampling the trajectory of a single body known to SPICE and supported by
   data from SPICE kernels.
 
   To compare trajectories the program computes a set of geometric states
   of a body as seen from a center in a reference frame over an interval of
   time with a fixed or variable time step using one SPK file, computes a
   set of geometric states for the same or different body-center-frame
   combination at the same times using the other SPK file, and then
   subtracts the corresponding states from each other. Depending on the
   type of output report requested the program prints to the screen only
   the maximum differences in position and velocity, or a complete table of
   position and velocity differences, or a complete table of differences
   expressed in ``view frame'' coordinates, or results of a simple
   statistical analysis of the differences expressed in ``view frame''
   coordinates.
 
   To sample trajectory of a body the program computes a set of geometric
   states of a body as seen from a center in a reference frame over an
   interval of time with fixed or variable time step, using a given set of
   kernel files, and prints to the screen a table containing these states.
 
 
If You Are in a Hurry
--------------------------------------------------------
 
   This section shows four very common SPKDIFF usage scenarios with just
   enough explanations to get you going. An extensive set of detailed
   examples is provided at the end of this User's Guide.
 
 
To Check if Two SPK Files Provide Identical Data
 
   To check if two SPK files containing trajectories for the same body with
   respect to the same center in the same reference frame provide identical
   data, run SPKDIFF as follows:
 
      % spkdiff -s <step> <spk1> <spk2>
 
   where ``<spk1>'' and ``<spk2>'' are the names of the two SPK files, and
   ``step'' is the time step, in seconds. If the maximum position and
   velocity difference magnitudes in the output are zero (or close to zero,
   accounting for round off), then the SPKs contain the same data.
 
 
To Assess Difference Between Two SPK Files
 
   To assess the difference between two SPK files containing trajectories
   for the same body with respect to the same center in the same reference
   frame as a function of time, run SPKDIFF as follows:
 
      % spkdiff -t dump -s <step> <spk1> <spk2>
 
   where ``<spk1>'' and ``<spk2>'' are the names of the two SPK files; ``-t
   dump'' sets the output format to the dump report showing differences
   between individual states computed from the files; and ``step'' is the
   time step, in seconds. The program's output, which can be rather
   lengthy, can be re-directed to a file using the ``>'' pipe. Using the
   data captured in the file the difference in position (columns 2-4) and
   velocity (columns 5-7) can be plotted against time, given as TDB seconds
   (column 1), to analyze the difference between the trajectories. To print
   output time tags as UTC in ISO date format instead of TDB seconds, add
 
      -k <lsk> -f 'YYYY-MM-DDTHR:MN:SC.### ::RND'
 
   before the ``-t'' option. These additional options specify the name of
   an LSK file required to convert times to any form other than TDB seconds
   and the desired output time format using the SPICE TIMOUT routine output
   time picture notation. To use the view frame dump report output instead
   of the dump report output, replace ``dump'' with ``dumpvf'', like this:
 
      % spkdiff -t dumpvf -s <step> <spk1> <spk2>
 
 
To Sample Trajectory from an SPK File
 
   To sample a trajectory provided in an SPK file, run SPKDIFF as follows:
 
      % spkdiff -s <step> <spk>
 
   where ``<spk>'' is the name of an SPK file and ``step'' is the time
   step, in seconds. The program's output -- position (columns 2-4) and
   velocity (columns 5-7) tagged with time, given as TDB seconds past J2000
   (column 1) -- can be re-directed to a file using the ``>'' pipe. To
   print output time tags as UTC in ISO date format, add
 
      -k <lsk> -f 'YYYY-MM-DDTHR:MN:SC.### ::RND'
 
   before ``-s''. These additional options specify the name of an LSK file
   required to convert times to any form other than TDB seconds and the
   desired output time format using the SPICE TIMOUT routine output time
   picture notation. If the SPK file contains data for more than one body
   and a body different from the body picked by SPKDIFF as default is
   desired, the name or NAIF ID of the desired body can be specified using
   ``-b1 <body>'' option, like this:
 
      % spkdiff -b1 <body> -s <step> <spk>
 
 
To Sample Trajectory from a set of Kernels
 
   To sample the trajectory for a body relative to a center in a reference
   frame provided by a set of kernels or meta-kernels, run SPKDIFF as
   follows (the command line below is wrapped to fit the page width):
 
      % spkdiff -k <kernels> -s <step>
                -b1 <body> -c1 <center> -r1 <frame>
 
   where ``<kernels>'' are the names of SPK and other kernel files and/or
   meta-kernels needed to compute trajectory; ``step'' is the time step, in
   TDB seconds; ``<body>'' and ``<center>'' are the names or NAIF IDs of
   the body and center; and ``<frame>'' is the name of the reference frame.
   For lengthy reports the program's output should be re-directed to a file
   using the ``>'' pipe.
 
 
Usage
--------------------------------------------------------
 
   SPKDIFF is a command line program with the following usage:
 
      % spkdiff [options] <first SPK name> <second SPK name>
      % spkdiff [options] <SPK name>
      % spkdiff [options]
 
   The options are:
 
      -k  <supporting kernel(s) name(s)>
      -b1 <first body name or ID>
      -c1 <first center name or ID>
      -r1 <first reference frame name>
      -k1 <additional supporting kernel(s) for first SPK>
      -b2 <second body name or ID>
      -c2 <second center name or ID>
      -r2 <second reference frame name>
      -k2 <additional supporting kernel(s) for second SPK>
      -b  <interval start time>
      -e  <interval stop time>
      -s  <time step in seconds>
      -n  <number of states: 2 to 1000000 (default: 1000)>
      -f  <output time format (default: TDB seconds past J2000)>
      -d  <number of significant digits: 6 to 17 (default: 14)>
      -t  <report type: basic|stats|dump|dumpvf|dumpc|dumpg
          (def.: basic|dump)>
 
   The order of options and case of the option keys are not significant.
   The values provided after the option keys must be separated from the
   keys by one or more spaces. Un-recognized options are not specifically
   checked for; instead they are treated as continuation of the value
   provided using the preceding recognized option.
 
 
Options
--------------------------------------------------------
 
   Kernel file names and control parameters are provided to the program
   using the following command line options (only a brief description of
   each option is given in the list below; details, defaults, and
   dependencies are discussed later in this document):
 
         <first SPK name>    is the name of the first SPK file. When two
                             SPK files are provided to the program this
                             name must be the second to last item on the
                             command line.
 
         <second SPK name>   is the name of the second SPK file. When two
                             SPK files are provided to the program this
                             name must be the last item on the command
                             line.
 
         <SPK name>          is the name of the only SPK file. When only
                             one SPK file is provided to the program this
                             name must be the last item on the command
                             line.
 
         -k <kernels>        is used to specify the list of additional
                             kernels or meta-kernels that are needed for
                             both trajectories to be computed. File names
                             following ``-k'' must be separated by spaces.
 
         -b1 <body>          is used to specify the body for the first
                             trajectory to be computed. This body can be
                             specified using its NAIF ID or name. If the
                             name is used, it must be either built into
                             SPICE or defined by kernels provided using the
                             ``-k'' and ``-k1'' options.
 
         -c1 <body>          is used to specify the center for the first
                             trajectory to be computed. This center can be
                             specified using its NAIF ID or name. If the
                             name is used, it must be either built into
                             SPICE or defined by kernels provided using the
                             ``-k'' and ``-k1'' options.
 
         -r1 <frame>         is used to specify the name of the reference
                             frame for the first trajectory to be computed.
                             The frame can be any of the frames built into
                             SPICE or frames defined by kernels provided
                             using the ``-k'' and ``-k1'' options.
 
         -k1 <kernels>       is used to specify the list of additional
                             kernels or meta-kernels that are needed only
                             for the first trajectory to be computed. File
                             names following ``-k1'' must be separated by
                             spaces.
 
         -b2 <body>          is used to specify the body for the second
                             trajectory to be computed. This body can be
                             specified using its NAIF ID or name. If the
                             name is used, it must be either built into
                             SPICE or defined by kernels provided using the
                             ``-k'' and ``-k1'' options.
 
         -c2 <body>          is used to specify the center for the second
                             trajectory to be computed. This center can be
                             specified using its NAIF ID or name. If the
                             name is used, it must be either built into
                             SPICE or defined by kernels provided using the
                             ``-k'' and ``-k1'' options.
 
         -r2 <frame>         is used to specify the name of the reference
                             frame for the second trajectory to be
                             computed. The frame can be any of the frames
                             built into SPICE or frames defined by kernels
                             provided using the ``-k'' and ``-k2'' options.
 
         -k2 <kernels>       is used to specify the list of additional
                             kernels or meta-kernels that are needed only
                             for the second trajectory to be computed. File
                             names following ``-k2'' must be separated by
                             spaces.
 
         -b <time>           is used to specify the coverage window begin
                             time. The time string provided using this
                             option can be in any form accepted by SPICE's
                             str2et_c function. If this option is provided,
                             the name of an LSK file must be provided with
                             the ``-k'', ``-k1'', or ``-k2'' option.
 
         -e <time>           is used to specify the coverage window end
                             time. The time string provided using this
                             option can be in any form accepted by SPICE's
                             str2et_c function. If this option is provided,
                             the name of an LSK file must be provided with
                             the ``-k'', ``-k1'', or ``-k2'' option.
 
         -s <step>           is used to specify the step, in TDB seconds,
                             for determining points within the coverage
                             window, for which the trajectory(ies) are to
                             be computed. The step must be greater than
                             1E-8. This option supersedes ``-n''.
 
         -n <number>         is used to specify the number of points within
                             the coverage window, for which the
                             trajectory(ies) are to be computed. The number
                             must be an integer between 2 and 1,000,000.
                             The default value is 1000. This option is
                             superseded by ``-s''.
 
         -f <time_type>      is used to specify the output time format
                             other than the default TDB seconds past J2000.
                             The value can be any time format picture
                             accepted by the timout_c function, for example
                             to display time tags as UTCs in ISO date
                             format use
 
                               'YYYY-MM-DDTHR:MN:SC.### ::RND'
 
                             to display time tags as TDB Julian days use:
 
                               'JULIAND.######### ::TDB'
 
         -d <number>         is used to specify the number of significant
                             digits in the output numeric times (TDB
                             seconds past J2000) and state component values
                             or state component difference values included
                             in the dump, coverage and coverage gap
                             reports. The number must be an integer between
                             6 and 17. The default value is 14.
 
         -t <report_type>    is used to specify the type of report that the
                             program should display:
 
                                basic   to display only the absolute and
                                        relative maximum and average
                                        differences in magnitude of
                                        position and velocity vectors
 
                                stats   to display statistics on position
                                        differences rotated into the view
                                        frame
 
                                dump    to display a table of positions and
                                        velocities or their differences
 
                                dumpvf  to display a table of position and
                                        velocity differences rotated into
                                        the view frame
 
                                dumpc   to display a table of coverage
                                        intervals
 
                                dumpg   to display a table of gaps in
                                        coverage
 
                             Only ``dump'', ``dumpc'', and ``dumpg'' are
                             applicable for sampling runs. ``basic'' is the
                             default for comparison runs while ``dump'' is
                             the default for sampling runs.
 
         -v                  causes the program to display only the version
                             line. This option overrides all other options.
 
         -u                  causes the program to display the usage
                             message. This option overrides all other
                             options except ``-v''.
 
         -h                  causes the program to display a brief help
                             message. This option overrides all other
                             options except ``-v'' and ``-u''.
 
 
Kernel Files
--------------------------------------------------------
 
   In all cases at least one SPK file must be provided to the program to
   perform comparison or sampling of trajectories. Frequently more than one
   SPK and one or more additional kernels of other types are given to
   compute trajectories chaining data for multiple bodies and/or with
   respect to non-inertial reference frames. Depending on how the SPKs are
   provided, they fall into one of two categories -- primary SPK files and
   additional SPK or other kernel files.
 
   Primary SPK files -- two, one, or none -- are provided at the end of the
   command line without any command line keys. Normally these SPKs are the
   ones containing trajectories that differ (for example, predicted and
   reconstructed SPKs for the same body and time period), or the trajectory
   to be sampled. These SPK files are also examined by the program to
   determine the default values for the body, center, and frame, and to
   determine the coverage window boundaries.
 
   Additional kernel files -- none, or as many as needed -- are provided
   anywhere on the command line (except at the very end) using the ``-k'',
   ``-k1'', and ``-k2'' keys. Normally these kernel files contain
   additional SPICE data needed to compute requested trajectories or
   generate other than TDB seconds time tags for output (for example, an
   LSK file providing supporting time conversion data, FK files providing
   frame definitions needed by SPICE to recognize specified frames, PCK
   files providing rotation data for computing trajectories in body-fixed
   frames, etc).
 
 
Primary Kernel Files
 
   The primary SPK files are provided as the last or the last two items on
   the command line. Since the primary kernel files do not require specific
   command line keys, the program determines if they were given by
   examining the last two words on the command line as follows:
 
       --   If the last word on the command line is not the name of an
            existing SPK file, the program assumes that no primary SPK
            files were given.
 
       --   If the last word on the command line is the name of an existing
            SPK file but the second to last word is not, the program
            assumes that only one primary SPK file was given.
 
       --   If both the last two words are names of existing SPK files, the
            program assumes that it was given two primary SPK files
 
   Due to the parsing approach described above, misspelling a primary SPK
   name or not including the path if the file is not in the current
   directory leads to the program deciding that it either runs with no
   primary SPK files (if the last file name is misspelled) or that it runs
   with one primary SPK instead of two (if the second to last file name is
   misspelled). In either case, the misspelled file name(s) is(are) treated
   as a part of the value of the command line option immediately preceding
   it(them) causing the program to signal an error indicating an incorrect
   option value.
 
   On the other hand, if any of the options for specifying additional
   kernel files (``-k'', ``-k1'', ``-k2'') followed by actual file names is
   provided at the end of the command line (for the case of no primary
   SPKs) or immediately preceding the only primary SPK file (for the case
   of one primary SPK), and the last one or the last two additional kernels
   are SPKs, they are mistakenly picked as the primary kernel(s). In this
   situation the program usually signals an error indicating that
   trajectory could not be computed because insufficient data was loaded.
 
 
Additional Kernel Files
 
   Unlike primary kernels that must be SPKs, additional kernels can be of
   any type -- PCK, FK, SCLK, LSK, CK, or even meta-kernels (MK). Unlike
   primary kernels, additional kernels are specified using the dedicated
   ``-k'', ``-k1'', and ``-k2'' keys. Any number of additional kernels or
   meta-kernels can be provided using any of the three keys, with kernel
   file names listed in any order, separated by blanks. While in many cases
   no additional kernel files are required, in all cases when ``-f'',
   ``-b'', and/or ``-e'' are given, an LSK file must be specified using one
   of these keys. The additional kernels are used by the program as
   follows:
 
       --   All additional kernel files provided using the ``-k'' are
            loaded and used for both trajectories (body-center-frame
            combinations).
 
       --   All additional kernel files provided using ``-k1'' are loaded
            and used only for the first trajectory (first body-center-frame
            combination).
 
       --   All additional kernel files provided using ``-k2'' are loaded
            and used only for the second trajectory (second
            body-center-frame combination).
 
   Neither the combined set of additional kernel files given using
   ``-k''/``-k1'' nor the combined set of additional kernel files given
   using ``-k''/``-k2'' can contain enough data to compute corresponding
   trajectories at any time in the time buffer without loading the
   corresponding primary SPK file(s). If they do, the program signals an
   error. The only exception from this requirement is when no primary
   kernel files are specified, then the additional kernel files given using
   ``-k''/``-k1'' and ``-k''/``-k2'' must contain enough data to compute
   the corresponding trajectories.
 
 
Comparison Runs vs. Sampling Runs
--------------------------------------------------------
 
   The program automatically decides whether it should compare two
   trajectories or sample one trajectory, based on the primary kernels
   provided at the end of the command line, additional kernel files
   provided using the ``-k1'' and ``-k2'' keys, and on the
   body-center-frame combinations specified on the command line using the
   ``-b1'', ``-c1'', ``-r1'', ``-b2'', ``-c2'', and ``-r2'' keys and/or
   determined from the primary SPK data.
 
   To run the program in comparison mode, it is enough to satisfy any of
   the following guidelines for specifying inputs that tell the program to
   compute two different trajectories:
 
       --   provide two different primary SPKs
 
       --   provide two different sets of trajectory-specific additional
            kernels using ``-k1'' and ``-k2''
 
       --   specify two different bodies using ``-b1'' and ``-b2''
 
       --   specify two different centers using ``-c1'' and ``-c2''
 
       --   specify two different reference frames using ``-r1'' and
            ``-r2''
 
   To run the program in sampling mode, it is required to satisfy all of
   the following guidelines telling the program to compute a single
   trajectory:
 
       --   provide only one primary SPK or no primary SPKs
 
       --   provide no trajectory-specific additional kernels using ``-k1''
            and ``-k2'' or provide the same files listed in the same order
            using both of these keys
 
       --   specify only one body using either ``-b1'' or ``-b2'', specify
            the same body using both of these keys, or specify no bodies at
            all
 
       --   specify only one center using either ``-c1'' or ``-c2'',
            specify the same center using both of these keys, or specify no
            centers at all
 
       --   specify only one reference frame using either ``-r1'' or
            ``-r2'', specify the same reference frame using both of these
            keys, or specify no reference frames at all
 
 
Runs with Two, One, and No Primary SPK(s)
--------------------------------------------------------
 
   The number of primary SPK files and the mode in which the program is run
   (``comparing'' vs. ``sampling'') directly affect the requirements in
   regards to which command line options must be provided, approaches for
   determining default values for omitted options, and ways in which
   kernels are loaded and trajectories are computed. The three subsections
   below discuss specifics of runs with two, one, and no primary SPK files.
 
 
Runs with Two Primary SPK Files
 
   When two primary SPK files are provided on the command line:
 
       --   All ``-*1'' and ``-*2'' options, and ``-b'' and ``-e'' options
            can be omitted because defaults for these options can be picked
            from the first of these files.
 
       --   Since the program is run in comparison mode in such cases, the
            first primary SPK file and the additional kernel files given
            using ``-k'' and ``-k1'' are loaded and states for the first
            default/specified body-center-frame combination are computed at
            times within the default/specified time window, then the second
            primary SPK file and the additional kernel files given using
            ``-k'' and ``-k2'' are loaded and states for the second
            default/specified body-center-frame combination are computed at
            the same times within the default/specified time window, then
            the differences between the corresponding states are computed
            and printed in the specified format.
 
 
Runs with One Primary SPK File
 
   When one primary SPK file is provided on the command line:
 
       --   All ``-*1'' and ``-*2'' options, and ``-b'' and ``-e'' options
            can be omitted because defaults for these options can be picked
            from the file.
 
       --   If the program is run in comparison mode, the primary file and
            the additional kernel files given using ``-k'' and ``-k1'' are
            loaded and states for the first body-center-frame combination
            are computed at times within the default/specified time window,
            then the primary file and the additional kernel files given
            using ``-k'' and ``-k2'' are loaded and states for the second
            body-center-frame combination are computed at the same times
            within the default/specified time window, then the differences
            between corresponding states are computed and printed in the
            specified format.
 
       --   If the program is run in sampling mode, the primary SPK file
            and the additional kernel files given using ``-k'' and ``-k1''
            are loaded and states for the first body-center-frame
            combination are computed at times within the default/specified
            time window and then printed in the specified format.
 
 
Runs Without Primary SPK Files
 
   When no primary SPK files are specified on the command line:
 
       --   ``-b1'' or ``-b2'' or both, ``-c1'' or ``-c2'' or both, and
            ``-r1'' or ``-r2'' or both must be specified because the
            program has no way of picking defaults for the
            body-center-frame combination(s) when it is not given any
            primary kernel(s) to examine.
 
       --   If the program is run in comparison mode, the additional kernel
            files given using ``-k'' and ``-k1'' are loaded and states for
            the first body-center-frame combination are computed at times
            within the default/specified time window, then the additional
            kernel files given using ``-k'' and ``-k2'' are loaded and
            states for the second body-center-frame combination are
            computed at the same times within the default/specified time
            window, then the differences between corresponding states are
            computed and printed in the specified format.
 
       --   If the program is run in sampling mode, the additional kernel
            files given using ``-k'' and ``-k1'' are loaded and states for
            the first body-center-frame combination are computed at times
            within the default/specified time window and then printed in
            the specified format.
 
 
Specifying/Picking Defaults for Bodies, Centers, and Frames
--------------------------------------------------------
 
   The program has six command line keys -- ``-b1'', ``-c1'', ``-r1'',
   ``-b2'', ``-c2'', and ``-r2'' -- to specify body-center-frame
   combinations to be used to compute trajectories. A single object can be
   specified using each of the ``-b*'' and ``-c*'' options using the object
   name or ID and a single frame can be specified using each of the ``-r*''
   options using the frame name.
 
   If a body or a center is specified using its name, this name must be
   known to SPICE, i.e. it must either be the name of a built-in object or
   one of the names defined in the text kernels provided as additional
   kernels. If the name specified on the command line is not recognized
   after loading the kernel files provided using ``-k''/``-k1'' for the
   ``-b1'' and ``-c1'' names, or provided using ``-k''/``-k2'' for the
   ``-b2'' and ``-c2''names, the program signals an error.
 
   The name of a frame specified on the command line or associated with the
   frame ID picked from one of the primary SPK files must be known to SPICE
   as well. It must either be a name of a built-in frame or of one of the
   frames defined in the FK file(s) provided as additional kernels. If the
   frame name specified on the command line or frame ID picked from the
   primary SPK file is not recognized after loading the kernel files
   provided using ``-k''/``-k1'' for the ``-r1'' frames, or provided using
   ``-k''/``-k2'' for the ``-r2'' frames, the program signals an error.
 
   Not all six items have to be specified for every program run. In many
   cases only one body, center, or frame is given and the program will set
   the rest to default values based on the given body, center, or frame
   and/or by examining the primary SPK file(s). The three subsections below
   discuss specifying and picking defaults for the bodies, centers, and
   frames frames.
 
 
Specifying/Picking Defaults for Bodies
 
   The following rules apply to specifying and picking defaults for the
   bodies:
 
       --   If both ``-b1'' and ``-b2'' are specified, trajectories are
            computed for these bodies.
 
       --   If only ``-b1'' or only ``-b2'' is specified, the specified
            body is used for both bodies.
 
       --   If neither ``-b1'' nor ``-b2'' is specified and only one
            primary SPK file is given, the body to be used for both
            trajectories is determined by examining segments in this SPK
            file. If the SPK file contains segments for one or more
            spacecraft (i.e. segments for bodies with negative IDs), the
            body from the spacecraft data segment closest to the end of the
            file is picked. If the SPK file does not contain data for any
            spacecraft, the body from the very last segment of the file is
            picked.
 
       --   If neither ``-b1'' nor ``-b2'' is specified and both primary
            SPK files are are provided, the body to be used for both
            trajectories is determined by examining segments in the first
            primary SPK file in the same way as in the case of only one
            primary SPK (see above).
 
       --   If neither ``-b1'' nor ``-b2'' is specified and no primary SPK
            files are given, the program signals an error.
 
 
Specifying/Picking Defaults for Centers
 
   The following rules apply to specifying and picking defaults for
   centers:
 
       --   If ``-c1'' and ``-c2'' are specified, trajectories are computed
            relative to these centers.
 
       --   If only ``-c1'' or only ``-c2'' is specified, the specified
            center is used for both centers.
 
       --   If neither ``-c1'' nor ``-c2'' is specified and only one
            primary SPK file is given, the center to be used for both
            trajectories is determined by examining segments in this SPK
            file. The center is set to the center from the last segment in
            the file for the body determined using the rules for picking
            bodies (the rules for picking bodies are explained earlier in
            the ``Specifying/Picking Defaults for Bodies'' section of this
            User's Guide).
 
       --   If neither ``-c1'' nor ``-c2'' is specified and both primary
            SPK files are given, the center to be used for both
            trajectories is determined by examining segments in the first
            primary SPK file in the same way as in the case of only one
            primary SPK (see above).
 
       --   If neither ``-c1'' nor ``-c2'' is specified and no primary SPK
            files are given, the program signals an error.
 
 
Specifying/Picking Defaults for Frames
 
   The following rules apply to specifying and picking defaults for the
   frames:
 
       --   If ``-r1'' and ``-r2'' are specified, trajectories are computed
            relative to these frames..
 
       --   If only ``-r1'' or only ``-r2'' is specified, the specified
            frame is used for both frames.
 
       --   If neither ``-r1'' nor ``-r2'' is specified and only one
            primary SPK file is given, the frame to be used for both
            trajectories is determined by examining segments in this SPK
            file. The frame is set to the frame from the last segment in
            the file for the body determined using the rules for picking
            bodies (the rules for picking bodies are explained earlier in
            the ``Specifying/Picking Defaults for Bodies'' section of this
            User's Guide).
 
       --   If neither ``-r1'' nor ``-r2'' is specified and both primary
            SPK files are given, the frame to be used for both trajectories
            is determined by examining segments in the first primary SPK
            file in the same way as in the case of only one primary SPK
            (see above).
 
       --   If neither ``-r1'' nor ``-r2'' is specified and no primary SPK
            files are given, the program signals an error.
 
 
Body, Center, and Frame Selection Scenarios
 
   A few comparison run scenarios shown below illustrate when some or all
   of the options specifying body, center and frame can be omitted and when
   they must be provided to achieve the desired result:
 
       --   When comparing spacecraft trajectories for a spacecraft with
            the same ID provided in two SPK files, each containing data
            only for one spacecraft with or without planetary ephemeris
            data merged in, neither of the six options specifying body,
            center and frame combination is required. SPKDIFF determines
            body, center and frame from the last segment for that
            spacecraft from the first SPK file and uses these body, center
            and frame selections in calling SPKGEO to obtain states from
            both SPK files.
 
       --   When comparing spacecraft trajectories for the spacecraft with
            the same ID provided in two SPK files, each containing data for
            more than one spacecraft, the name/ID of that spacecraft needs
            to be specified using either the ``-b1'' option or the ``-b2''
            option to prevent SPKDIFF from automatically picking the other
            spacecraft, data for which is also provided in the files.
 
       --   When comparing spacecraft trajectories for the same spacecraft
            ``tagged'' with two different IDs (for example flight ID and
            simulation ID) provided in two SPK files, both IDs need to be
            specified using the ``-b1'' and ``-b2'' options to make sure
            that SPKDIFF uses the right ID for each of the files.
 
       --   When comparing ephemerides for a natural body provided in two
            planetary or satellite ephemeris SPK files, the name/ID of that
            body need to be specified using either the ``-b1'' option or
            the ``-b2'' option to prevent SPKDIFF from automatically
            picking a different body.
 
   A few sampling run scenarios shown below illustrate when some or all of
   the options specifying body, center and frame can be omitted and when
   they should be provided to achieve the desired result:
 
       --   When sampling trajectory for a spacecraft from an SPK file
            containing data just for that spacecraft or just for that
            spacecraft and some natural bodies, and expecting the sampled
            states to be relative to the same center and in the same frame
            as the spacecraft data in the SPK file, neither of the six
            options specifying body, center and frame combination is
            required. SPKDIFF determines body, center and frame from the
            last segment for that spacecraft from the SPK file and computes
            states for the associated body, center and frame.
 
       --   When sampling spacecraft trajectory for a spacecraft from an
            SPK file containing data for more than one spacecraft, the
            name/ID of that spacecraft needs to be specified using either
            the ``-b1'' option or the ``-b2'' option to prevent SPKDIFF
            from automatically picking another spacecraft, data for which
            is also provided in the file.
 
       --   When sampling spacecraft trajectory for a spacecraft or a
            natural body relative to a center different from the center
            with respect to which that spacecraft's trajectory is provided
            in the last segment of the given SPK file, the name/ID of that
            center needs to be specified using either the ``-c1'' option or
            the ``-c2'' option to prevent SPKDIFF from automatically
            picking the default center based on the data provided in the
            file.
 
       --   When sampling spacecraft trajectory for a spacecraft or a
            natural body relative to a frame different from the frame with
            respect to which that spacecraft's trajectory is provided in
            the last segment of the given SPK file, the name of that frame
            needs to be specified using either the ``-r1'' option or the
            ``-r2'' option to prevent SPKDIFF from automatically picking
            the default frame based in the data provided in the file.
 
       --   When sampling spacecraft trajectory without providing a primary
            SPK, for example using data from one or more meta-kernels
            specified using the ``-k'' option, all three items -- body,
            center, and frame -- must be specified using the ``-b1'' (or
            ``-b2''), ``-c1'' (or ``-c2''), and ``-r1'' (or ``-r2'')
            options because the program cannot pick any defaults without
            primary SPK(s).
 
   The list of scenarios and suggestions above is not comprehensive by any
   means. There are numerous applications in which not just bodies but also
   centers and references frames may need to be specified to override
   defaults. For example, a center may need to be specified to compare
   trajectories with respect to a center that is different from the center
   of motion specified in the SPK segment; two centers may need to be
   specified to compare two SPK files, in one of which the trajectory is
   given with respect to the planet center while in the other it is given
   with respect to the planet system barycenter; two different frames may
   need to be specified to see how different the trajectory from the same
   SPK file would appear if it was computed in a different frame; and so
   on.
 
 
Times for Comparison/Sampling
--------------------------------------------------------
 
   The program picks times at which states are computed based on the
   coverage window determined by examining the primary SPK files(s), SPKs
   provided as additional kernel files and listed in the meta-kernels
   provided as additional kernel files, and/or specified using the ``-b''
   and ``-e'' keys, and on either the number of points within that window
   specified using the ``-n'' key or the time step specified using the
   ``-s'' key''.
 
   The coverage window begin and end times specified using the ``-b'' and
   ``-e'' options can be in any format accepted by SPICE's str2et_c
   function (see str2et_c header for details). If one or both of these
   times are provided, an LSK file must be provided as one of the
   additional kernels.
 
   The number of points specified using the ``-n'' key must be an integer
   between 2 to 1,000,000 while the step specified using the ``-s'' key
   must be in seconds and be greater than 1.0E-8. If both ``-n'' and ``-s''
   are specified, ``-s'' takes precedence.
 
   The coverage window determined by examining the primary SPK file(s) or
   additional SPK files may consist of many intervals, some of which may be
   singletons (with the interval begin time equal to the interval end
   time). Whether the coverage window consists of only one interval or of
   many intervals, the program computes times within the window in such a
   way that the interval ends are always included in the set of points. The
   rest of times are distributed within the intervals, stepping from the
   beginning of each interval with the specified step. If the number of
   points is given instead of the step, the step is computed using the
   measure of the coverage window (the sum of the lengths of the individual
   intervals) and the specified number of points.
 
   Not all of the keys controlling selection of points have to be specified
   for every program run. In some cases none of these options are required.
   The two subsections below discuss specifics of providing and picking
   defaults for the coverage window and step or number of points.
 
 
Coverage Window
 
   The program determines the coverage window by examining the primary SPKs
   or the additional SPKs to get the ``default coverage window'' and by
   further restricting this window by the optional begin and/or end times
   provided using the ``-b'' and ``-e'' keys.
 
   The default coverage window is determined either from the primary SPK
   files or from the additional SPK files using SPICE's spkcov_c function
   to get coverages for the bodies either specified using the
   ``-b1''/``-b2'' keys or set to default values as described earlier in
   this document. Depending on the kernels provided to the program the
   default coverage window is determined as follows (in all cases below the
   first and the second bodies may be the same body or different bodies):
 
       --   When the two primary SPK files are provided, the default
            coverage window is set to the intersection of the coverage
            window for the first body determined from the first primary SPK
            and the coverage window for the second body determined from the
            second primary SPK.
 
       --   When one primary SPK file is provided, the default coverage
            window is set to the intersection of the coverage windows for
            the first and second bodies determined from this SPK.
 
       --   When no primary SPK files are provided, the default coverage
            window is set to the intersection of the coverage window for
            the first body determined from all additional SPKs provided
            with and/or listed in meta-kernels provided with the ``-k'' and
            ''-k1'' keys and the coverage window for the second body
            determined from all additional SPKs provided with and/or listed
            in meta-kernels provided with the ``-k'' and ''-k2'' keys.
 
   If the program is given no SPK files, the SPK files don't provide data
   for specified bodies, or the coverage windows for the first and second
   bodies do not overlap, the program signals an error.
 
   If either ``-b'' or ``-e'', or both ``-b'' and ``-e'' are specified, the
   default window is truncated according to these begin and end times. If
   the time specified using ``-b'' is before the start of the default
   window, this time is ignored. If the time specified using ``-b'' is
   after the end of the default coverage window, the program signals an
   error. If the time specified using ``-e'' is after the end of the
   default window, this time is ignored. If the time specified using ``-e''
   is before the start of the default coverage window, the program signals
   an error.
 
 
Times within Coverage Window
 
   The program picks times within the coverage window based on the number
   of points specified using the ``-n'' key or the time step specified
   using the ``-s'' key''.
 
   When neither the number of points is specified using ``-n'' nor the step
   is specified using ``-s'', the number of points is set to a default
   value determined by examining the coverage window. If the total number
   of endpoints -- 2 for each non-singleton interval, 1 for each singleton
   interval -- for all intervals in the coverage window is greater than
   1000, the number of points is set to the number of endpoints and the
   step is not computed. Otherwise it is set to 1000 or a number less than
   but close to 1000 (the actual number is determined at run-time based on
   the lengths of the intervals) and the step is computed by dividing the
   measure of the coverage window by the number of points minus the number
   of intervals.
 
   When the number of points is specified using ``-n'' but this number is
   less than the number of the coverage window interval endpoints, the
   value given using ``-n'' is ignored and the number of points is set to
   the number of interval endpoints and the step is not computed. Otherwise
   the number of points is set to the value provided using ``-n'' or a
   number less than but close to this value (the actual number is
   determined at run time based on the lengths of the intervals) and the
   step is computed by dividing the measure of the coverage window by the
   number of points minus the number of intervals.
 
   When step is specified using ``-s'', the number of points is computed by
   adding the number of interval endpoints to the total of the numbers of
   points that can fit within each non-singleton interval when it's stepped
   through with this step. If the resultant number of points is greater
   than 1,000,000, the program signals an error.
 
   Whether the step was provided or computed using the provided or default
   number of points, the set of times at which trajectory is computed
   includes all interval ends -- 2 for each non-singleton interval, 1 for
   each singleton interval -- plus additional points computed by stepping
   with this step within each non-singleton interval starting from the
   interval start time. The last point within each non-singleton interval
   is computed such that it always lies inside the 1.5*step to 0.5*step
   range off the interval end.
 
   In the very unlikely case of the comparison window containing a single
   singleton interval the program does not pick a single time for it.
   Depending on the values specified with ``-s'' and ``-n'' it picks the
   default number of times 1000 (no ``-s'' and ``-n''), 2 (for ``-s'' with
   any value), or the user specified number of times (``-n'' but no ``-s'')
   and sets all these times to the same time.
 
   Care should be taken when picking the step using ``-s'' or specifying
   the number of points using ``-n''. Picking a very small step for a large
   time window, or very many points for any window, leads to very long run
   times. In some cases the number of points computed using the step may
   even be greater that 1,000,000, preventing the program from running
   because its buffers are not large enough to deal with so many points. On
   the other hand, picking a large step or too few points prevents the
   program from doing a sufficiently dense sampling or a thorough
   comparison.
 
   Another important point to keep in mind, especially for the sampling
   runs, is that because of the possibility of multiple intervals within
   the coverage window and the approach used for picking the last step
   within each interval, the program will almost never produce a constant
   step output state or state difference table. One or more steps in the
   table will almost always be greater or smaller than the others,
   prohibiting use of the table in any application that requires a constant
   step size.
 
 
Times for Comparison/Sampling Selection Scenarios
 
   A few comparison run scenarios below illustrate when some or all of the
   options specifying the comparison time window and time step can be
   omitted and when they must be provided to achieve the desired result:
 
       --   If the program is run just to find out whether trajectories
            provided by two primary SPK files are different or not, all of
            the options in this category can be omitted. SPKDIFF finds the
            overlapping coverage from the file data, computes a default
            number of samples over that window and performs a comparison of
            these samples.
 
       --   If the goal is to assess differences during a particular time
            interval, which is usually much shorter than the overlap in
            coverage between the two primary SPK files (for example for a
            time window around a single pericenter for two files, each
            covering many orbits), both the begin and end times should be
            specified to constrain SPKDIFF to that window.
 
       --   If the time step automatically computed by SPKDIFF using the
            default or specified number of steps is too large to produce a
            meaningful set of samples for a given trajectory (for example
            the automatically computed step is 10 hours for an orbiter with
            a 2 hour period), a more appropriate time step should be
            specified on the command line.
 
       --   Another situation when the time step should be specified on the
            command line is when the program is used to generate a dump of
            differences. In this case using a time step that is an integer
            number of seconds results in a cleaner and more understandable
            output report.
 
   A few sampling run scenarios below illustrate when some or all of the
   options specifying the comparison time window and time step can be
   omitted and when they should be provided to achieve the desired result:
 
       --   If the program is run just to sample a trajectory from the
            primary SPK file or from a set of additional SPK files over the
            whole period for which the coverage of the body of interest is
            desired, normally only the step needs to be specified because
            it is not likely that the step picked by default will result in
            the desired output. SPKDIFF finds the overlapping coverage from
            the file data, picks sample times based on the given step over
            that window and samples the trajectory at these times.
 
       --   If the goal is to sample a trajectory during a particular time
            interval, which is usually much shorter than the default
            coverage window determined from the primary or additional SPK
            files (for example for a time window around a single pericenter
            for SPKs covering many orbits), both the begin and end times
            should be specified to constrain SPKDIFF to that window.
 
       --   Often specifying a time step as an integer number of seconds
            results in a cleaner and more understandable output report.
 
   As with the body, center, frame combination this list of scenarios for
   using the time window/step related options is not comprehensive. There
   are applications in which specifying only the begin time (to examine
   only the ``tail'' portion of the overlap window) or only the end time
   (to examine only the ``head'' portion of the overlap window) would be
   appropriate. There are other applications, for which providing just a
   small number of steps (to perform faster but less thorough sampling over
   the whole overlap window between the files) or a large number of steps
   (to perform slower but more thorough sampling over the whole overlap
   window between the files) is all that is needed.
 
 
Output
===========================================================================
 
   In a successful run the program prints to the screen a report consisting
   of the report header and report data. The report header provides
   complete information about the kernels and control parameters used by
   the program. The report data provides information about the trajectory
   differences (for comparison runs) or trajectories (for sampling reports)
   in a variety of ways, called report types.
 
 
Overview of Report Types
--------------------------------------------------------
 
   The report data can be one of the following types depending on the value
   provided using the ``-t'' key:
 
         basic    the basic report, applicable only to comparison runs,
                  showing only the absolute and relative maximum and
                  average differences in magnitude of position and velocity
                  vectors. This type of output is useful for a quick
                  assessment of whether the two trajectories are different,
                  and finding the maximum magnitude of this difference.
                  This is the default report displayed for comparison runs
                  when ``-t'' is omitted.
 
         stats    the statistics report, applicable only to comparison
                  runs, providing a set of values resulting from
                  statistical analysis of the state differences rotated
                  into the view frame -- +X down track along velocity
                  vector, +Y normal to the orbit plane, computed as the
                  cross product of position and velocity vectors, and +Z in
                  the orbit plane, completing the right handed frame --
                  based on the state computed for the first
                  body-center-frame combination. Among values included in
                  this report are the average and RMS view frame components
                  of the differences as well as the view frame components
                  for maximum relative and maximum absolute differences.
                  This report is useful for obtaining a more useful
                  assessment of the differences between trajectories, for
                  which using the view frame is appropriate.
 
         dump     the state or state difference dump report, applicable to
                  sampling and comparison runs, containing a table with
                  time tagged states (for sampling runs) or state
                  differences (for comparison runs). This report is useful
                  for subsequent plotting of trajectories or differences
                  between trajectories over time or for generating
                  trajectory data tables for input to other applications
                  (e.g. MKSPK). This is the default report displayed for
                  sampling runs when ``-t'' is omitted.
 
         dumpvf   the view frame state difference dump report, applicable
                  only to comparison runs, containing a table with time
                  tagged differences between individual states computed for
                  the two body-center-frame combinations, rotated into the
                  view frame based on states computed for the first
                  combination. This report is useful for plotting of the
                  difference between trajectories expressed in the view
                  frame, as a function of time.
 
         dumpc    the coverage intervals dump report containing a table
                  listing the start and stop times and durations for the
                  intervals inside the coverage window, during which
                  trajectory(ies) can be computed.
 
         dumpg    the coverage gaps dump report containing a table listing
                  the start and stop times and duration for the gaps inside
                  the coverage window, during which trajectory(ies) cannot
                  be computed.
 
   In comparison runs, the ``basic'' and ``stats'' reports are useful for
   obtaining a quick assessment of whether and by how much two trajectories
   differ while the ``dump'' and ``dumpvf'' reports are useful to capture
   detailed information about trajectory differences.
 
   In sampling runs, the ``dump'' report is the main report used to
   generate desired trajectory data tables.
 
   The ``dumpc'' and ``dumpg'' reports are useful for SPK coverage and
   coverage overlap analysis.
 
   All reports have rigid formats. The only item in the reports that can be
   altered by command line options is the format of time tags in ``dump''
   and ``dumpvf'' reports, which can be changed using the ``-f'' key.
 
 
Time Tag Format for ``dump*'' Reports
 
   The format of the time tags in the ``dump*'' reports is controlled using
   the ``-f'' key. By default, time tags in the ``dump*'' report data are
   given as TDB seconds past J2000. This default format can be changed by
   specifying ``-f'' followed by a time format picture acceptable to the
   timout_c function. For example:
 
      YYYY-MM-DDTHR:MN:SC.### ::RND    for UTC ISO date
      YYYY-DOYTHR:MN:SC.### ::RND      for UTC ISO DOY
      JULIAND.######### ::TDB          for Julian day TDB
 
   ``-f'' does not apply to times in the report header and the statistics
   report, in which the times are always displayed as TDB in calendar and
   seconds past J2000 formats.
 
 
Numeric Format for ``dump*'' Reports
 
   The default format of numeric time tags (TDB seconds past J2000), state
   component values, and state component difference values in all ``dump*''
   reports is the scientific format with 14 significant digits (e.g.
   +1.2345678901234E+01). A different number of significant digits can be
   specified using the ``-d'' option as an integer in the range from 6 to
   17. If specified, the number of significant digits is used for all
   numeric items in the ``dump*'' report data part (table) but is not used
   for any numbers in the table header or in the data part of the
   non-``dump*'' (``basic'' and ``stats'') reports.
 
   The default format, with 14 significant digits, is usually adequate for
   output from all comparison runs and from all sampling runs that are
   intended to produce tables of states for plotting but, due to round off,
   it may not be adequate for sampling runs that are intended to generate
   tables of states for subsequent interpolation or packaging into SPK
   files. For such outputs the number of significant digits should be
   increased to 16 -- if output states are planned to be packaged into an
   SPK file using the MKSPK program that employs a custom parser to ingest
   input numeric data -- or 17 -- if output states will read by an
   application that uses language-native means to parse input numeric
   data).
 
 
Report Header
--------------------------------------------------------
 
   The top portion of each report generated by the program is occupied by
   the report header providing complete information about the kernels and
   control parameters used by the program. The format and the set of
   information provided in the report header depends on
 
       --   the type of run (comparison vs. sampling)
 
       --   the type of report (data dump, coverage dump, etc.)
 
       --   the set of kernels that were provided
 
       --   and various miscellaneous control parameters.
 
   All lines in the report header have
 
      #
 
   as the first character. This allows common plotting programs, such as
   GNUPLOT, to skip these header lines when plotting the ``dump''-type
   reports generated by the program.
 
   Neither the ``-f'' nor ``-d'' options used to control the time and
   numeric formats in the data part of the output have any effect on the
   time and number formats used in all headers.
 
 
Report Header for Comparing Two Trajectories
 
   For runs comparing two trajectories the report header has either the
   ``old'' format used in version 1.0.0 of the program and preserved for
   backward compatibility for comparison runs with two primary SPKs, over
   comparison window comprised of a single interval, and without
   trajectory-specific additional kernels provided using the ``-k1'' and
   ``-k2'' options (the line numbers shown on the left in this and the next
   header are not present in the actual reports; they are provided for
   referencing purposes only):
 
       1 #
       2 # Comparison of N 'FRAME1NAME'-referenced geometric states
       3 #
       4 #    of 'BODY1NAME' (BODY1ID) relative to 'CEN1NAME' (CEN1ID)
       5 #    from SPK 'SPK1NAME'
       6 #
       7 # with N 'FRAME2NAME'-referenced geometric states
       8 #
       9 #    of 'BODY2NAME' (BODY2ID) relative to 'CEN2NAME' (CEN2ID)
      10 #    from SPK 'SPK2NAME'
      11 #
      12 # evenly-spaced with STEPSEC second (STEPDHMS) step size
      13 # within the time interval
      14 #
      15 #    from 'YYYY MON DD HR:MN:SC.### TDB' (SSSS.### TDB seconds)
      16 #    to   'YYYY MON DD HR:MN:SC.### TDB' (SSSS.### TDB seconds)
      17 #
      18 # using additional data from these kernels
      19 #
      20 #    -K/KERNEL1 -K/KERNEL2 ... -K/KERNELn
      21 #
 
   or the ``new'' format used for all other comparison cases:
 
       1 #
       2 # Comparison of N 'FRAME1NAME'-referenced geometric states
       3 #
       4 #    of 'BODY1NAME' (BODY1ID) relative to 'CEN1NAME' (CEN1ID)
       5 #    computed using
       6 #
       7 #       -K/KERNEL1  -K/KERNEL2  ... -K/KERNELn
       8 #       -K1/KERNEL1 -K1/KERNEL2 ... -K1/KERNELm
       9 #       SPK1NAME
      10 #
      11 # with N 'FRAME2NAME'-referenced geometric states
      12 #
      13 #    of 'BODY2NAME' (BODY2ID) relative to 'CEN2NAME' (CEN2ID)
      14 #    computed using
      15 #
      16 #       -K/KERNEL1  -K/KERNEL2  ... -K/KERNELn
      17 #       -K2/KERNEL1 -K2/KERNEL2 ... -K2/KERNELm
      18 #       SPK2NAME
      19 #
      20 # with a STEPSEC second (STEPDHMS) step size
      21 # within the continuous time period
      22 #
      23 #    from 'YYYY MON DD HR:MN:SC.### TDB' (SSSS.### TDB seconds)
      24 #    to   'YYYY MON DD HR:MN:SC.### TDB' (SSSS.### TDB seconds)
      25 #
      26 # TIMESPEC
      27 #
 
   where:
 
       --   on lines 2 and 7 (old) or 11 (new) ``N'' is replaced with the
            actual number of comparison points while ``FRAME1NAME'' and
            ``FRAME2NAME'' are replaced with the actual names of the frames
            used to compute states for comparison
 
       --   on lines 4, and 9 (old) or 13 (new) ``BODY1NAME'', ``BODY1ID'',
            ``CEN1NAME'', ``CEN1ID'', ``BODY2NAME'', ``BODY2ID'',
            ``CEN2NAME'', and ``CEN2ID'' are replaced with the actual
            names/IDs of the bodies and centers used to compute states for
            comparison
 
       --   lines 5, 10, and 20 (old) or 7, 8, 9, 16, 17, and 18 (new)
            contain names of primary kernels provided at the end of the
            command line and names of additional kernels provided using the
            ``-k'', ``-k1'', and ``-k2'' keys. In the old report, lines 18,
            19, 20, and 21 are omitted if no additional kernels were
            provided using the ``-k'' option. In the new report any of the
            specified lines are present only when corresponding kernel
            files are given on the command line; if they are present, the
            kernels on the lines are listed in the order in which they were
            loaded by the program.
 
       --   on line 12 (old) or 20 (new) the actual step printed with 14
            significant digits replaces ``STEPSEC'' while the actual step
            expressed as days, hours, minutes, seconds in the old
 
                 DDd HRh MMm SS.###s
 
            format or the new
 
                 DDD:MN:HR:SC.######
 
            format replaces ``STEPDHMS''. If states are computed only at
            the interval endpoints, the whole line in the new header is
            replaced with the following string: ``at continuous coverage
            intervals' endpoints''.
 
       --   line 21 (new) has the form shown above when there are no gaps
            in the coverage window. Otherwise the whole line is replaced
            with the following string: ``within the non-continuous (with M
            gaps) time period'' where ``M'' is replaced with the actual
            number of gaps.
 
       --   on lines 15 and 16 (old) or 23 and 24 (new) times are replaced
            with the first and last times from the set of times for which
            the comparison was made.
 
       --   lines 26 and 27 are displayed for all report types except
            ``basic'' and ``stats''. If no output time type was specified
            using the ``-f'' key, TIMESPEC is replaced ``Times are TDB
            seconds past J2000.'' If an output time type was specified
            using the ``-f'' key, TIMESPEC is replaced ``Times were
            generated by TIMOUT using '<format>' format.''
 
 
Report Header for Coverage/Gaps for Two Trajectories
 
   For runs displaying coverage or gaps in coverage for two trajectories
   the report header has the following format (the line numbers given on
   the left are not present in the actual report; they are provided only
   for referencing purposes):
 
       1 #
       2 # Coverage overlap for 'FRAME1NAME'-referenced geometric states
       3 #
       4 #    of 'BODY1NAME' (BODY1ID) relative to 'CEN1NAME' (CEN1ID)
       5 #    computed using
       6 #
       7 #       -K/KERNEL1  -K/KERNEL2  ... -K/KERNELn
       8 #       -K1/KERNEL1 -K1/KERNEL2 ... -K1/KERNELm
       9 #       SPK1NAME
      10 #
      11 # and 'FRAME2NAME'-referenced geometric states
      12 #
      13 #    of 'BODY2NAME' (BODY2ID) relative to 'CEN2NAME' (CEN2ID)
      14 #    computed using
      15 #
      16 #       -K/KERNEL1  -K/KERNEL2  ... -K/KERNELn
      17 #       -K2/KERNEL1 -K2/KERNEL2 ... -K2/KERNELm
      18 #       SPK2NAME
      19 #
      20 # with a STEPSEC second (STEPDHMS) step size
      21 # within the continuous time period
      22 #
      23 #    from 'YYYY MON DD HR:MN:SC.### TDB' (SSSS.### TDB seconds)
      24 #    to   'YYYY MON DD HR:MN:SC.### TDB' (SSSS.### TDB seconds)
      25 #
      26 # TIMESPEC
      27 #
 
   where:
 
       --   on lines 2 and 11 ``FRAME1NAME'' and ``FRAME2NAME'' are
            replaced with the actual names of the frames used to compute
            states for comparison
 
       --   on lines 4 and 13 ``BODY1NAME'', ``BODY1ID'', ``CEN1NAME'',
            ``CEN1ID'', ``BODY2NAME'', ``BODY2ID'', ``CEN2NAME'', and
            ``CEN2ID'' are replaced with the actual names/IDs of the bodies
            and centers used to compute states for comparison
 
       --   lines 7, 8, 9, 16, 17, and 18 contain names of primary kernels
            provided at the end of the command line and names of additional
            kernels provided using the ``-k'', ``-k1'', and ``-k2'' keys.
            Any of these lines are present only when corresponding kernel
            files are given on the command line; if they are present, the
            kernels on the lines are listed in the order in which they were
            loaded by the program.
 
       --   on line 20 the actual step printed with 14 significant digits
            replaces ``STEPSEC'' while the actual step expressed as days,
            hours, minutes, seconds in the
 
                 DDD:MN:HR:SC.######
 
            format replaces ``STEPDHMS''. If states are computed only at
            the interval endpoints, the whole line in the new header is
            replaced with the following string: ``at continuous coverage
            intervals' endpoints''.
 
       --   line 21 has the form shown above when there are no gaps in the
            coverage window. Otherwise the whole line is replaced with the
            following string: ``within the non-continuous (with M gaps)
            time period'' where ``M'' is replaced with the actual number of
            gaps.
 
       --   on lines 23 and 24 times are replaced with the first and last
            times from the set of times for which the comparison was made.
 
       --   on line 26 ``TIMESPEC'' is replaced with ``Times are TDB
            seconds past J2000.'' if no output time type was specified
            using the ``-f'' key or with ``Times were generated by TIMOUT
            using '<format>' format.'' if an output time type was specified
            using the ``-f'' key.
 
 
Report Header for Sampling Trajectory
 
   For runs sampling a trajectory the report header has the following
   format (the line numbers given on the left are not present in the actual
   report; they are provided for referencing purposes only):
 
       1 #
       2 # Sampling of N 'FRAMENAME'-referenced geometric states
       3 #
       4 #    of 'BODYNAME' (BODYID) relative to 'CENNAME' (CENID)
       5 #    computed using
       6 #
       7 #       -K/KERNEL1  -K/KERNEL2  ... -K/KERNELn
       8 #       -K1/KERNEL1 -K1/KERNEL2 ... -K1/KERNELm
       9 #       SPKNAME
      10 #
      11 # with a STEPSEC second (STEPDHMS) step size
      12 # within the continuous time period
      13 #
      14 #    from 'YYYY MON DD HR:MN:SC.### TDB' (SSSS.### TDB seconds)
      15 #    to   'YYYY MON DD HR:MN:SC.### TDB' (SSSS.### TDB seconds)
      16 #
      17 # TIMESPEC
      18 #
 
   where:
 
       --   on line 2 ``N'' is replaced with the actual number of sample
            points while ``FRAMENAME'' is replaced with the actual name of
            the frame used to compute sampled states
 
       --   on line 4 ``BODYNAME'', ``BODYID'', ``CENNAME'', and ``CENID''
            are replaced with the actual names/IDs of the body and center
            used to compute sampled states
 
       --   lines 7, 8, and 9 contain names of the primary SPK provided at
            the end of the command line and names of additional kernels
            provided using the ``-k'' and ``-k1'' keys. Any of these lines
            are present only when corresponding kernel files are given on
            the command line; if they are present, the kernels on the lines
            are listed in the order in which they were loaded by the
            program.
 
       --   on line 11 the actual step printed with 14 significant digits
            replaces ``STEPSEC'' while the actual step expressed as days,
            hours, minutes, seconds in the
 
                 DDD:MN:HR:SC.######
 
            format replaces ``STEPDHMS''. If states are computed only at
            the interval endpoints, the whole line in the new header is
            replaced with the following string: ``at continuous coverage
            intervals' endpoints''.
 
       --   line 12 has the form shown above when there are no gaps in the
            coverage window. Otherwise the whole line is replaced with the
            following string: ``within the non-continuous (with M gaps)
            time period'' where ``M'' is replaced with the actual number of
            gaps.
 
       --   on lines 14 and 15 times are replaced with the first and last
            times from the set of times for which the comparison was made.
 
       --   on line 17 ``TIMESPEC'' is replaced with ``Times are TDB
            seconds past J2000.'' if no output time type was specified
            using the ``-f'' key or with ``Times were generated by TIMOUT
            using '<format>' format.'' if an output time type was specified
            using the ``-f'' key.
 
 
Report Header for Coverage/Gaps for Trajectory
 
   For runs displaying coverage or gaps in coverage for a trajectory the
   report header has the following format (the line numbers given on the
   left are not present in the actual report; they are provided for
   referencing purposes only):
 
       1 #
       2 # Coverage for 'FRAMENAME'-referenced geometric states
       3 #
       4 #    of 'BODYNAME' (BODYID) relative to 'CENNAME' (CENID)
       5 #    computed using
       6 #
       7 #       -K/KERNEL1  -K/KERNEL2  ... -K/KERNELn
       8 #       -K1/KERNEL1 -K1/KERNEL2 ... -K1/KERNELm
       9 #       SPKNAME
      10 #
      11 # with a STEPSEC second (STEPDHMS) step size
      12 # within the continuous time period
      13 #
      14 #    from 'YYYY MON DD HR:MN:SC.### TDB' (SSSS.### TDB seconds)
      15 #    to   'YYYY MON DD HR:MN:SC.### TDB' (SSSS.### TDB seconds)
      16 #
      17 # TIMESPEC
      18 #
 
   where:
 
       --   on line 2 ``FRAMENAME'' is replaced with the actual name of the
            frame used to compute sampled states
 
       --   on line 4 ``BODYNAME'', ``BODYID'', ``CENNAME'', and ``CENID''
            are replaced with the actual names/IDs of the body and center
            used to compute sampled states
 
       --   lines 7, 8, and 9 contain names of the primary SPK provided at
            the end of the command line and names of additional kernels
            provided using the ``-k'' and ``-k1'' keys. Any of these lines
            are present only when corresponding kernel files are given on
            the command line; if they are present, the kernels on the lines
            are listed in the order in which they were loaded by the
            program.
 
       --   on line 11 the actual step printed with 14 significant digits
            replaces ``STEPSEC'' while the actual step expressed as days,
            hours, minutes, seconds in the
 
                 DDD:MN:HR:SC.######
 
            format replaces ``STEPDHMS''. If states are computed only at
            the interval endpoints, the whole line in the new header is
            replaced with the following string: ``at continuous coverage
            intervals' endpoints''.
 
       --   line 12 has the form shown above when there are no gaps in the
            coverage window. Otherwise the whole line is replaced with the
            following string: ``within the non-continuous (with M gaps)
            time period'' where ``M'' is replaced with the actual number of
            gaps.
 
       --   on lines 14 and 15 times are replaced with the first and last
            times from the set of times for which the comparison was made.
 
       --   on line 17 ``TIMESPEC'' is replaced with ``Times are TDB
            seconds past J2000.'' if no output time type was specified
            using the ``-f'' key or with ``Times were generated by TIMOUT
            using '<format>' format.'' if an output time type was specified
            using the ``-f'' key.
 
 
Report Formats
--------------------------------------------------------
 
 
Basic Report (no ``-t'' option or with ``-t basic'')
 
   The basic report shows only the absolute and relative maximum and
   average differences in magnitude of position and velocity vectors. The
   absolute differences are computed by simple subtraction of position and
   velocity components for the second trajectory from the corresponding
   position and velocity components for the first trajectory while the
   relative differences are computed by dividing the absolute differences
   in the positions and velocities by the magnitudes of the positions and
   velocities for the first trajectory.
 
   This report is generated only for comparison runs if the ``-t'' option
   is omitted or if it is followed by the value ``basic''. This report has
   the following format (as for all other comparison reports it follows one
   of the two comparison information headers):
 
      Relative differences in state vectors:
 
                                   maximum                 average
 
       Position:             n.nnnnnnnnnnnnnE-nn      n.nnnnnnnnnnnnnE-nn
       Velocity:             n.nnnnnnnnnnnnnE-nn      n.nnnnnnnnnnnnnE-nn
 
 
      Absolute differences in state vectors:
 
                                   maximum                 average
 
       Position (km):        n.nnnnnnnnnnnnnE-nn      n.nnnnnnnnnnnnnE-nn
       Velocity (km/s):      n.nnnnnnnnnnnnnE-nn      n.nnnnnnnnnnnnnE-nn
 
 
   where ``n.nnnnnnnnnnnnnE-nn'' are the relative and absolute maximum and
   average differences in magnitude of position and velocity vectors.
 
   It is important to remember that these maximum values are picked from
   the sets of states sampled from the SPK files within the given/default
   comparison windows using the given/default time step, rather than by a
   true search for the maximum within the window. Thus any change in the
   window begin and end time and/or time step will result in a different
   set of states being sampled at different times and then used in the
   comparison, leading to different maximum and average values appearing in
   the report.
 
 
View Frame Statistics Report (``-t stats'')
 
   The view frame statistics report shows a set of values resulting from a
   statistical analysis of the state differences rotated into the view
   frame. This report is generated only for comparison runs if the ``-t''
   option is followed by the value ``stats''.
 
   The view frame into which the differences between states are rotated for
   statistical analysis is based on states computed using the
   body-center-frame combination and is defined as follows:
 
       --   +X is down track, in the direction of the velocity vector.
 
       --   +Y is normal to the orbit plane. It is computed as the cross
            product of the position and velocity vectors.
 
       --   +Z is in the orbit plane. It completes the right handed frame
            and is computed as the cross product of +X and +Y.
 
   This report has the following format (as for all other comparison
   reports it follows one of the two comparison information headers):
 
      1) Average components of position difference vectors in view
         frame coordinates:
 
         1a) Down track (km):                        n.nnnnnnnnnnnnnn
 
         1b) In orbit plane (km):                    n.nnnnnnnnnnnnnn
 
         1c) Normal to orbit plane (km):             n.nnnnnnnnnnnnnn
 
         1d) Average delta time down track (sec):    n.nnnnnnnnnnnnnn
 
 
      2) Average |components| of position difference vectors in view
         frame coordinates:
 
         2a) Down track (km):                        n.nnnnnnnnnnnnnn
 
         2b) In orbit plane (km):                    n.nnnnnnnnnnnnnn
 
         2c) Normal to orbit plane (km):             n.nnnnnnnnnnnnnn
 
         2d) Average |delta time| down track (sec):  n.nnnnnnnnnnnnnn
 
 
      3) RMS of position difference vectors in view frame coordinates:
 
         3a) Down track (km):                        n.nnnnnnnnnnnnnn
 
         3b) In orbit plane (km):                    n.nnnnnnnnnnnnnn
 
         3c) Normal to orbit plane (km):             n.nnnnnnnnnnnnnn
 
         3d) RMS delta time down track (sec):        n.nnnnnnnnnnnnnn
 
 
      4) Components of the position difference vector in view frame
         coordinates for the states with the MAXIMUM RELATIVE
         difference in position:
 
         4a) Down track (km):                        n.nnnnnnnnnnnnnn
 
         4b) In orbit plane (km):                    n.nnnnnnnnnnnnnn
 
         4c) Normal to orbit plane (km):             n.nnnnnnnnnnnnnn
 
         4d) Delta time down track (sec):            n.nnnnnnnnnnnnnn
 
         4e) Epoch (TDB, seconds past J2000):        nnnnnnnnn.nnnnnn
 
         4f) Epoch (TDB, calendar format):           YYYY-MON-DD-HR:MN:SC
 
 
      5) Components of the position difference vector in view frame
         coordinates for the states with the MAXIMUM ABSOLUTE
         difference in position:
 
         5a) Down track (km):                        n.nnnnnnnnnnnnnn
 
         5b) In orbit plane (km):                    n.nnnnnnnnnnnnnn
 
         5c) Normal to orbit plane (km):             n.nnnnnnnnnnnnnn
 
         5d) Delta time down track (sec):            n.nnnnnnnnnnnnnn
 
         5e) Epoch (TDB, seconds past J2000):        nnnnnnnnn.nnnnnn
 
         5f) Epoch (TDB, calendar format):           YYYY-MON-DD-HR:MN:SC
 
 
   In addition to the average, average of absolute values, RMS, maximum
   relative, and maximum absolute down track, in orbit plane and normal to
   orbit plane components, the program includes in each category a delta
   time down track in seconds. For the maximum relative and maximum
   absolute differences the report also provides the times -- as TDB
   seconds past J2000 and calendar format TDB -- at which these states were
   computed.
 
   As with the basic report the statistically determined maximum values are
   based on the sets of states sampled from the SPK files within the
   given/default comparison windows using the given/default time step
   rather than by a true search for the maximum within the window. Thus any
   change in the window begin and end time and/or time step will result in
   a different set of states being sampled at different times and then used
   in the comparison, leading to different maximum and average values
   appearing in the report.
 
   While this type of report can be requested for any combination of body,
   center, and frame, for some of them the notion of the view frame would
   not be applicable because the motion of the body with respect to the
   center would be too different from the ``normal'' orbital motion for
   which using the view frame makes the most sense. In such cases this
   report may contain meaningless or even incomprehensible numbers. There
   is also a possibility that the view frame simply cannot be constructed
   for one or more states computed for the first trajectory because
   position and velocity components of this state are linearly dependent.
   In such cases the program reports this fact and does not generate the
   report.
 
   To facilitate parsing, each of the items included in this report is
   provided on a separate line tagged with a distinct item ``identifier''
   (1a, 2b, 5d, etc.), with the value appearing as the last word on the
   line.
 
 
Dump Report (no ``-t'' option or with ``-t dump'')
 
   The dump report contains a table with time tagged states computed for
   the specified/default body, center, frame combination (for sampling
   cases) or differences between individual states computed for the two
   specified/default body, center, frame combinations (for comparison
   cases). This report is generated if the ``-t'' option is followed by the
   value ``dump'' or if the ``-t'' option is omitted in a sampling run.
 
   For comparison runs this report has the following format (as for all
   other comparison reports it follows one of the two comparison
   information headers):
 
 
      # time, (x1-x2), (y1-y2), (z1-z2), (vx1-vx2), (vy1-vy2), (vz1-vz2)
      TIME DELTA_X DELTA_Y DELTA_Z DELTA_VX DELTA_VY DELTA_VZ
      TIME DELTA_X DELTA_Y DELTA_Z DELTA_VX DELTA_VY DELTA_VZ
      ...  ...     ...     ...     ...      ...      ...
      TIME DELTA_X DELTA_Y DELTA_Z DELTA_VX DELTA_VY DELTA_VZ
 
 
   For sampling runs this report has the following format (as for all other
   sampling reports it follows the sampling information header):
 
 
      # time, x, y, z, vx, vy, vz
      TIME X       Y       Z       VX       VY       VZ
      TIME X       Y       Z       VX       VY       VZ
      ...  ...     ...     ...     ...      ...      ...
      TIME X       Y       Z       VX       VY       VZ
 
 
   The first line of the report ``names'' the items provided in the table.
   As for the lines in the header that this line immediately follows, it is
   prefixed using the
 
      #
 
   character in order to be ignored by common plotting utilities.
 
   Each of the subsequent lines contain seven space-delimited items -- a
   time tag in the format specified using the ``-f'' option (if ``-f'' was
   not provided the time tag is the number of TDB seconds past J2000)
   followed by the X, Y, Z, Vx, Vy, and Vz components of the state or the
   difference between the states. The position components or their
   differences are provided in kilometers, the velocity components or their
   differences are provided in kilometers per second. All numbers in the
   table -- times as TDB seconds past J2000 and state or state difference
   components -- are printed in scientific notation, +n.nnnnnnnnnnnnnE+nn,
   either with the default 14 significant digits or with the number of
   significant digits specified using the ``-d'' option.
 
 
View Frame Dump Report (``-t dumpvf'')
 
   The view frame dump report contains a table with time tagged differences
   between individual states computed for the two specified/default body,
   center, frame combinations, rotated into the view frame based on states
   for the first trajectory (see the ``View Frame Statistics Report''
   section above for the definition of the view frame). This report is
   generated only for comparison runs if the ``-t'' option is followed by
   the value ``dumpvf''. This report has the following format (as for all
   other comparison reports it follows one of the two comparison
   information headers):
 
 
      # time, down_track_p_diff, normal_to_plane_p_diff, in_plane_p_diff,
      down_track_v_diff, normal_to_plane_v_diff, in_plane_v_diff
      TIME DELTA_DT DELTA_NTP DELTA_IP DELTA_VDP DELTA_VNTP DELTA_VIP
      TIME DELTA_DT DELTA_NTP DELTA_IP DELTA_VDP DELTA_VNTP DELTA_VIP
      ...  ...     ...     ...     ...      ...      ...
      TIME DELTA_DT DELTA_NTP DELTA_IP DELTA_VDP DELTA_VNTP DELTA_VIP
 
 
   The first line of the report (which is shown as two lines above to fit
   into the width of the page) ``names'' the items provided in the table.
   As for the lines of the comparison information headers that this line
   immediately follows, it is prefixed using the
 
      #
 
   character in order to be ignored by common plotting utilities.
 
   Each of the subsequent lines contains seven space-delimited items -- a
   time tag in the format specified using the ``-f'' option (if the ``-f''
   option was not provided the time tag is the number of TDB seconds past
   J2000) followed by the down track, normal to orbit plane, in orbit
   plane, down track velocity, normal to orbit plane velocity, and in orbit
   plane velocity components of the difference between the state computed
   for the first trajectory and the state computed for the second
   trajectory, rotated into the view frame defined by the state for the
   first trajectory. The position component differences are provided in
   kilometers, the velocity component differences in kilometers per second.
   All numbers in the table -- times as TDB seconds past J2000 and state
   difference components -- are printed in scientific notation,
   +n.nnnnnnnnnnnnnE+nn, either with the default 14 significant digits or
   with the number of significant digits specified using the ``-d'' option.
 
   While this type of report can be requested for any combination of body,
   center, and frame, for some of them the notion of the view frame would
   not be applicable because the motion of the body with respect to the
   center would be too different from the ``normal'' orbital motion for
   which using the view frame makes the most sense. In such cases this
   report may contain meaningless or even incomprehensible numbers. There
   is also a possibility that the view frame simply cannot be constructed
   for one or more states computed for the first trajectory because
   position and velocity components of this state are linearly dependent.
   In such cases the program reports this fact and does not generate the
   report.
 
 
Coverage Intervals Dump Report (``-t dumpc''):
 
   The coverage intervals dump report displays the start and stop times for
   the intervals inside the coverage window, during which trajectories can
   be computed. The time tags are displayed in the format specified using
   the ``-f'' key, discussed earlier in the document.
 
   The coverage intervals dump report has the following format (and follows
   either sampling or comparison coverage/gap header):
 
      # int_start_time, int_end_time, int_duration_sec, int_duration_string
      STARTTIME STOPTIME SECONDS DAYS:HR:MN:SC.MMMMMM
      ...
      STARTTIME STOPTIME SECONDS DAYS:HR:MN:SC.MMMMMM
 
   where:
 
       --   Items on each data line are separated by spaces.
 
       --   The interval durations are printed as seconds in the
            ``x.xxxxxxxxxxxxxE+xx'' format (replaces SECONDS) and in days,
            hours, minutes, seconds format (replaces DAYS:HR:MN:SC.MMMMMM).
            The STARTTIMEs and STOPTIMEs are displayed in the format
            specified using the ``-f'' key or as TDB seconds past J2000 if
            ``-f'' was not provided. If the STARTTIMEs and STOPTIMEs are
            shown as TDB seconds past J2000, they are printed in scientific
            notation, +n.nnnnnnnnnnnnnE+nn, either with the default 14
            significant digits or with the number of significant digits
            specified using the ``-d'' option.
 
 
Coverage Gaps Dump Report (``-t dumpg'')
 
   The coverage gaps dump report displays the start and stop times for the
   gaps inside the coverage window, during which trajectories cannot be
   computed. The time tags are displayed in the format specified using the
   ``-f'' key, discussed earlier in this document.
 
   The coverage gaps dump report has the following format (and follows
   either sampling or comparison coverage/gap header):
 
      # gap_start_time, gap_end_time, gap_duration_sec, gap_duration_string
      STARTTIME STOPTIME SECONDS DAYS:HR:MN:SC.MMMMMM
      ...
      STARTTIME STOPTIME SECONDS DAYS:HR:MN:SC.MMMMMM
 
       --   Items on each data line are separated by spaces.
 
       --   The gap durations are printed as seconds in the
            ``x.xxxxxxxxxxxxxE+xx'' format (replaces SECONDS) and in days,
            hours, minutes, seconds format (replaces DAYS:HR:MN:SC.MMMMMM).
            The STARTTIMEs and STOPTIMEs are displayed in the format
            specified using the ``-f'' key or as TDB seconds past J2000 if
            ``-f'' was not provided. If the STARTTIMEs and STOPTIMEs are
            shown as TDB seconds past J2000, they are printed in scientific
            notation, +n.nnnnnnnnnnnnnE+nn, either with the default 14
            significant digits or with the number of significant digits
            specified using the ``-d'' option.
 
       --   If the coverage window has no gaps, the string ``There are no
            gaps in coverage.'' is printed instead of the data records.
 
 
Troubleshooting
--------------------------------------------------------
 
   There are many cases when SPKDIFF is not able to perform the requested
   sampling or comparison due to incorrect, inconsistent, or missing
   command line options. Some such cases and possible solutions are:
 
       --   The program reports an error if the specified begin time is
            greater than the specified end time. This case is usually the
            result of a simple typo; double-checking and fixing the command
            line options is the way to correct it.
 
       --   The program reports an error if the body or center names
            provided on the command line cannot be translated to NAIF IDs.
            In such cases bodies and/or centers should be specified by ID
            instead of the name, or a text kernel containing name/ID
            mapping for the given names should be provided using the
            ``-k'', ``-k1'', or ``-k2'' option.
 
       --   The program reports an error if it does not recognize any
            specified frame names. In such cases a frames kernel(s)
            defining these frames should be provided using the ``-k'',
            ``-k1'', or ``-k2'' option.
 
       --   The program reports an error when either of the two primary SPK
            files to be compared or any of the supporting kernels provided
            using the ``-k'', ``-k1'', or ``'-k2'' option does not exist or
            is not a SPICE kernel of the expected type. The ``offending''
            file names should be checked and corrected.
 
       --   The program reports an error when instead of a numeric value
            expected with some of the options (``-n'' and ``-s'') it
            detects a string that does not represent a number. These inputs
            must be corrected for the program to proceed.
 
       --   The program reports an error if it does not recognize the
            output report type provided on the command line. This
            unrecognized value should be replaced with one of the allowed
            values.
 
       --   The program reports an error if an unsupported command line
            option key is provided on the command line. Such keys and any
            values following them are treated as part of the value for the
            preceding option key, causing a parsing error to be reported.
            Any unsupported option should be removed from the command line
            for the program to proceed.
 
       --   The program reports an error if either of the primary SPK files
            together with supporting kernels does not provide data for the
            body specified/picked for that trajectory. The body
            specification should be re-examined and corrected for the
            program to proceed.
 
       --   The program reports an error if either of the primary SPK files
            does not provide enough coverage for the specified/default
            body, center, frame combination within the comparison window
            specified on the command line. The comparison window should be
            adjusted for the program to proceed.
 
       --   The program reports an error if the primary SPK files to be
            compared do not have overlap in coverage for the corresponding
            body, center, frame combinations. In such cases the comparison
            simply cannot be performed.
 
       --   The program reports an error if any of the supporting kernels
            needed to compute states for the specified body, center, frame
            combination do not provide sufficient data. Depending on the
            specifics of the request any number and types of supporting
            kernels -- from additional SPK files to FK and CK files -- may
            be needed to satisfy the request. For this reason no simple
            suggestion on picking additional kernels can be made. Instead
            the user is directed to familiarize himself/herself with
            contents of the SPK files in question and with mission-specific
            and generic SPICE data that might be used together with these
            SPK files in order to identify supporting kernels needed to
            perform comparison.
 
       --   The program does not generate either statistical or dump view
            frame report if the view frame cannot be constructed using one
            or more states computed for the first trajectory. In this case
            other types of reports should be used instead.
 
       --   The program reports an error if too many states were requested
            to be used in the comparison either by specifying a too large
            number of steps using the ``-n'' option or by specifying a too
            small time step using the ``-s'' option. The inputs should be
            adjusted accordingly to reduce the number to be below the
            limit. The maximum number of steps allowed is 1,000,000; this
            values is hard-coded into the program.
 
       --   The program reports an error if the specified time step is
            smaller than 1.E-8 seconds. The input time step should be
            adjusted for the program to proceed.
 
       --   The program reports an error if SPK file(s) provided as
            supporting kernels allow for computing states for either of the
            body, center, frame combinations without loading the primary
            SPK files to be compared. The set of supporting SPK files
            should be reconsidered and some of the SPK files provided in it
            should be removed to resolve this conflict.
 
 
Examples
--------------------------------------------------------
 
   This section provides a few examples showing how SPKDIFF can help answer
   common questions regarding differences between SPK files, or how it can
   be used to sample (dump) states from one or more SPK file.
 
 
Comparison: Checking if Two SPKs Provide the Same Trajectory
 
   This very common check usually requires a simple ``yes'' or ``no''
   answer and zero or non-zero maximum differences shown by the basic
   report provide just that.
 
   In most cases spacecraft SPK files that are checked for ``sameness''
   have the same attributes -- storing spacecraft trajectory with respect
   to the same center in the same frame -- and need to be compared during
   the whole period of overlap between their coverages. Therefore, SPKDIFF
   can be run with ``bare minimum'' inputs -- just the names of the SPK
   files -- and be allowed to use defaults obtained by examining the files
   and/or hard-coded into the program.
 
   Below, SPKDIFF is invoked to answer this question for a regular,
   reconstructed SPK file and a merged reconstructed SPK file for Mars
   Global Surveyor. With just the SPK file names provided on the command
   line:
 
      > spkdiff spk_m_060508_OD32021-32092_rec_V1.bsp mgs_map_rec.bsp
 
   the program produces the following output:
 
      #
      # Comparison of 1000 'J2000'-referenced geometric states
      #
      #    of 'MGS' (-94) relative to 'MARS BARYCENTER' (4)
      #    from SPK 'spk_m_060508_OD32021-32092_rec_V1.bsp'
      #
      # with 1000 'J2000'-referenced geometric states
      #
      #    of 'MGS' (-94) relative to 'MARS BARYCENTER' (4)
      #    from SPK 'mgs_map_rec.bsp'
      #
      # evenly-spaced with 507.387 second (0d 00h 08m 27.387s) step size
      # within the time interval
      #
      #    from '2006 MAY 08 15:22:00.000 TDB' (200373720.0 TDB seconds)
      #    to   '2006 MAY 14 12:10:00.000 TDB' (200880600.0 TDB seconds)
      #
 
      Relative differences in state vectors:
 
                                   maximum                 average
 
        Position:            0.0000000000000E+00      0.0000000000000E+00
        Velocity:            0.0000000000000E+00      0.0000000000000E+00
 
 
      Absolute differences in state vectors:
 
                                   maximum                 average
 
        Position (km):       0.0000000000000E+00      0.0000000000000E+00
        Velocity (km/s):     0.0000000000000E+00      0.0000000000000E+00
 
 
   The fact that all differences in the output are zero means that both
   files provide the same trajectory for MGS relative to Mars Barycenter
   for the whole period of overlap (which should be the case because the
   regular reconstructed SPK file is one of the files that was used to
   create the merged SPK file).
 
 
Comparison: Checking if Two SPK files Differ Enough to Matter
 
   This is another very common check frequently used when it is known that
   two SPK files represent different trajectories but it is not known
   whether this difference is large enough to matter. In many such cases
   the magnitude of the maximum difference provided by the basic report
   provides the answer to this question.
 
   As in the previous example, the SPK files that are compared probably
   have the same attributes -- storing the spacecraft trajectory with
   respect to the same center in the same frame -- but the comparison
   window of interest is likely to be narrower than the whole overlap
   between the file coverages (for example only during closest approach or
   during a time window around pericenter). Thus, SPKDIFF should be allowed
   to get most defaults from the files but should be provided with the
   comparison window begin and end times on the command line.
 
   Below, SPKDIFF is run to check how different the reconstructed MGS
   trajectories provided by the Mars Global Surveyor Navigation team and
   the JPL Gravity Group are during the 30 minute window from 2001 APR 04
   02:30 to 03:30 UTC (a part of the illuminated portion of the MGS orbit
   9266). SPKDIFF, invoked with the comparison window boundaries, LSK file
   name (to support conversion of boundary UTC times to ET), and SPK file
   names:
 
      > spkdiff -b 2001 APR 04 02:30 -e 2001 APR 04 03:00 \
                -k naif0008.tls \
                mgs_ext2.bsp mgs_ext2_ipng_mgs75d.bsp
 
   produces the following output:
 
      #
      # Comparison of 1000 'J2000'-referenced geometric states
      #
      #    of 'MGS' (-94) relative to 'MARS BARYCENTER' (4)
      #    from SPK 'mgs_ext2.bsp'
      #
      # with 1000 'J2000'-referenced geometric states
      #
      #    of 'MGS' (-94) relative to 'MARS BARYCENTER' (4)
      #    from SPK 'mgs_ext2_ipng_mgs75d.bsp'
      #
      # evenly-spaced with 1.801 second (0d 00h 00m 01.801s) step size
      # within the time interval
      #
      #    from '2001 APR 04 02:30' (39623464.185 TDB seconds)
      #    to   '2001 APR 04 03:00' (39625264.185 TDB seconds)
      #
      # using additional data from these kernels
      #
      #    'naif0008.tls'
      #
 
      Relative differences in state vectors:
 
                                   maximum                 average
 
        Position:            1.5585888672802E-05      7.4593186410629E-06
        Velocity:            1.7161324644915E-05      1.4552469606438E-05
 
 
      Absolute differences in state vectors:
 
                                   maximum                 average
 
        Position (km):       5.9196225803226E-02      2.8215203092988E-02
        Velocity (km/s):     5.7990372644310E-05      4.9083689420832E-05
 
   The report shows that the maximum difference in position is about 60
   meters, which, given uncertainties in other data (timing, attitude,
   etc), may be deemed unimportant in processing data from a low resolution
   instrument.
 
 
Comparison: Checking the Down Track Timing Error
 
   This check is often needed when comparing preliminary and final
   predicted trajectories for orbiters that have to perform observations of
   a particular area on the surface of a target body. SPKDIFF provides
   estimates of the down track timing error in the view frame statistics
   report.
 
   Below, SPKDIFF is run to determine the down track timing error during
   the 10 minute window around pericenter of the MEX orbit 3040 ( 2006 MAY
   23 21:46 ... 21:56 UTC) for trajectories provided by long-term and
   short-term predicted SPK files. SPKDIFF, invoked with the comparison
   window boundaries, LSK file name (to support conversion of boundary UTC
   times to ET), report type ``stats'', and SPK file names:
 
      > spkdiff -b 2006 MAY 23 21:46 -e 2006 MAY 23 21:56 \
                -k NAIF0008.TLS \
                -t stats
                ORMM__060501000000_00253.BSP ORMF_______________00185.BSP
 
   produces the following output:
 
      #
      # Comparison of 1000 'J2000'-referenced geometric states
      #
      #    of 'MARS EXPRESS' (-41) relative to 'MARS' (499)
      #    from SPK 'ORMM__060501000000_00253.BSP'
      #
      # with 1000 'J2000'-referenced geometric states
      #
      #    of 'MARS EXPRESS' (-41) relative to 'MARS' (499)
      #    from SPK 'ORMF_______________00185.BSP'
      #
      # evenly-spaced with 0.600 second (0d 0h 0m 0.600000s) step size
      # within the time interval
      #
      #    from '2006 MAY 23 21:46' (201692825.18509 TDB seconds)
      #    to   '2006 MAY 23 21:56' (201693425.18509 TDB seconds)
      #
      # using additional data from these kernels
      #
      #    'NAIF0008.TLS'
      #
 
      1) Average components of position difference vectors in view
         frame coordinates:
 
         1a) Down track (km):                        30.552115284475
 
         1b) In orbit plane (km):                    1.2710676287493
 
         1c) Normal to orbit plane (km):            -0.011807645604121
 
         1d) Average delta time down track (sec):    7.1913943821391
 
 
      2) Average |components| of position difference vectors in view
         frame coordinates:
 
         2a) Down track (km):                        30.552115284475
 
         2b) In orbit plane (km):                    1.2710676287493
 
         2c) Normal to orbit plane (km):             0.011807645604121
 
         2d) Average |delta time| down track (sec):  7.1913943821391
 
 
      3) RMS of position difference vectors in view frame coordinates:
 
         3a) Down track (km):                        30.553065680244
 
         3b) In orbit plane (km):                    1.2720138468831
 
         3c) Normal to orbit plane (km):             0.012788802634391
 
         3d) RMS delta time down track (sec):        7.1917249241123
 
 
      4) Components of the position difference vector in view frame
         coordinates for the states with the MAXIMUM RELATIVE
         difference in position:
 
         4a) Down track (km):                        30.708369357832
 
         4b) In orbit plane (km):                    1.2758338375402
 
         4c) Normal to orbit plane (km):            -0.011447894251492
 
         4d) Delta time down track (sec):            7.1972290201441
 
         4e) Epoch (TDB, seconds past J2000):        201693107.46737
 
         4f) Epoch (TDB, calendar format):           2006-MAY-23-21:51:47
 
 
      5) Components of the position difference vector in view frame
         coordinates for the states with the MAXIMUM ABSOLUTE
         difference in position:
 
         5a) Down track (km):                        30.767205150213
 
         5b) In orbit plane (km):                    1.3086257963549
 
         5c) Normal to orbit plane (km):            -0.0080797486007561
 
         5d) Delta time down track (sec):            7.2439115051116
 
         5e) Epoch (TDB, seconds past J2000):        201692992.15206
 
         5f) Epoch (TDB, calendar format):           2006-MAY-23-21:49:52
 
 
   As seen in the report, the maximum down track timing error is about 7.2
   seconds at 2006-MAY-23-21:49:52 TBD.
 
 
Comparison: Checking Trajectory Differences Over Time
 
   In order to help with this check SPKDIFF should be run to produce either
   the difference dump or the view frame difference dump report that can
   then be plotted using a plotting utility.
 
   Below SPKDIFF is run to generate a view frame difference table for the
   Phobos ephemerides provided by the previous and the latest Martian
   satellite ephemeris files produced by the Solar System Dynamics group at
   JPL. To get detailed information on short-term difference trends, the
   comparison is done over 1 day, which is about three Phobos orbits, using
   a 30 minute time step (time boundaries and step specified using the
   ``-b'', ``-e'', and ``-s'' options). Since both SPK files contain data
   for multiple natural bodies, the body name is explicitly specified on
   the command line using the ``-b1'' option. Because the trajectory
   difference with respect to Mars is of interest, Mars is specified as the
   center using the ``-c1'' option. The time tag format for the output is
   set to the Julian date TDB using the ``-f'' option. SPKDIFF, run with
   all of these options and the names of the SPK files:
 
      > spkdiff -b 2006 MAY 10 -e 2006 MAY 11 \
                -s 1800 \
                -k naif0008.tls \
                -b1 PHOBOS -c1 MARS \
                -t dumpvf \
                -f 'JULIAND.######## ::TDB' \
                mar063.bsp mar080.bsp
 
   produces the following output:
 
      #
      # Comparison of 49 'J2000'-referenced geometric states
      #
      #    of 'PHOBOS' (401) relative to 'MARS' (499)
      #    from SPK 'mar063.bsp'
      #
      # with 49 'J2000'-referenced geometric states
      #
      #    of 'PHOBOS' (401) relative to 'MARS' (499)
      #    from SPK 'mar080.bsp'
      #
      # evenly-spaced with 1800.0000000000 second (0d 0h 30m 0.000000s) s
      # within the time interval
      #
      #    from '2006 MAY 10 00:01:05.185 TDB' (200491265.18535 TDB secon
      #    to   '2006 MAY 11 00:01:05.185 TDB' (200577665.18533 TDB secon
      #
      # using additional data from these kernels
      #
      #    'naif0010.tls'
      #
      # time, down_track_p_diff, normal_to_plane_p_diff, in_plane_p_diff,
       down_track_v_diff, normal_to_plane_v_diff, in_plane_v_diff
      2453865.50075450 -1.7677349027774E+00 -3.9612553944752E-01 -8.19662
      2453865.52158780 -1.7510452874102E+00 -2.3447359311290E-01 +5.14871
      2453865.54242110 -1.8363070174400E+00 -3.2619989185819E-02 +1.71661
      ...
      2453866.29242110 -2.9303145501717E+00 +4.4487716042933E-01 +1.12475
      2453866.31325450 -2.9793146648918E+00 +3.0429412064303E-01 -1.74350
      2453866.33408780 -2.9280026753345E+00 +1.1481152946733E-01 -1.45238
      ...
      2453866.45908780 -1.7640987370183E+00 -3.8347618122648E-01 -7.25770
      2453866.47992110 -1.7510926977361E+00 -2.1663590085367E-01 +5.79403
      2453866.50075440 -1.8437324018375E+00 -1.2674806851279E-02 +1.79887
 
   (To fit into the page width, all lines except for the last line of the
   header -- ``time, down_track_p_diff, ...'' -- were truncated at 67th
   position.)
 
   The table above shows that differences in Phobos' position provided by
   the SPK files are between -3 and -1.7 km down-track, between -0.6 and
   0.6 km normal to the orbit plane, and between -0.3 and 0.3 km in the
   orbit plane perpendicular to the down-track direction.
 
 
Sampling: States from a Single SPK File
 
   In the simplest case SPKDIFF can be run to sample states from an SPK
   file by giving the name of that SPK file as the sole argument on the
   command line. In this case the program will automatically pick the
   default body, center, and frame; determine the coverage window; sample
   1000 states; and print these states to the screen tagged with TDB
   seconds past J2000.
 
   While such default sampling may be useful in some situations, more
   commonly users would want to specify the step size using the ``-s''
   option to produce a more appropriate sampling for the type of trajectory
   in question, use the ``-b1'' or ``-b2'' (but not both) option to tell
   the program to generate states for a particular body rather than for the
   body picked by default, and supply an LSK file with the ``-k'' option
   and set the output time format picture with the ``-f'' option to
   generate more human friendly output time tags.
 
   As an example of a simple sampling, below SPKDIFF is run to generate a
   table of states (no ``-t'' option because ``-t dump'' is the default for
   sampling cases) of MRO relative to the Mars barycenter in the J2000
   inertial reference frame, computed with 60 second step (``-s 60''), with
   time tags printed as UTCs in ISO date format using options
 
      -k naif0010.tls -f 'YYYY-MM-DDTHR:MN:SC.### ::RND'
 
   from an MRO SPK file provided in the MRO SPICE archive
   (``mro_psp20.bsp''), containing data only for the MRO spacecraft. Note
   that in this run the program automatically picks the body, center,
   frame, and coverage window from the specified SPK file.
 
   SPKDIFF, run with the options mentioned above and the name of the SPK
   file:
 
      > spkdiff -k naif0010.tls \
                -f 'YYYY-MM-DDTHR:MN:SC.### ::RND' \
                -s 60 \
                mro_psp20.bsp
 
   produces the following output:
 
      #
      # Sampling of 132541 'J2000'-referenced geometric states
      #
      #    of 'MARS RECON ORBITER' (-74) relative to 'MARS BARYCENTER' (4
      #    computed using
      #
      #       naif0010.tls
      #       mro_psp20.bsp
      #
      # with a 60.000000000000 second (0:00:01:00.000000) step size
      # within the continuous time period
      #
      #    from '2011 JUL 01 00:01:06.184 TDB' (362750466.18413 TDB secon
      #    to   '2011 OCT 01 01:01:06.182 TDB' (370702866.18235 TDB secon
      #
      # Times were generated by TIMOUT using 'YYYY-MM-DDTHR:MN:SC.### ::R
      #
      # time, x, y, z, vx, vy, vz
      2011-07-01T00:00:00.000 -1.2631831919268E+03 -2.1050939423488E+03 -
      2011-07-01T00:01:00.000 -1.2070458592754E+03 -2.2708451713874E+03 -
      2011-07-01T00:02:00.000 -1.1470661740673E+03 -2.4293953426217E+03 -
      ...
      2011-10-01T00:59:00.002 +2.4573775413008E+03 -2.6139786726625E+03 +
      2011-10-01T01:00:00.000 +2.4222378126552E+03 -2.5767734595725E+03 +
 
   (To fit into the page width, the lines were truncated at the 67th
   position.)
 
 
Sampling: States from Many SPKs Listed in Meta-Kernel(s)
 
   One of the convenient SPKDIFF features is that the program can be used
   to sample trajectory data provided in a set of SPK files listed along
   with other kernels in a meta-kernel or a set of meta-kernels. In such
   cases the program will not be able pick default body, center, and frame
   because the meta-kernel(s) will need to be specified using the ``-k''
   option and no SPKs will be provided at the end of the command line. The
   user will need to specify the body, center, and frame for which states
   are to be sampled using the ``-b1'', ``-c1'', and ``-r1'' options. The
   user will not need to specify the coverage start and stop time because
   the program will automatically determine default coverage for the given
   body from all SPKs listed in the meta-kernel(s). The user might still
   want to specify the step size using the ``-s'' option to produce a more
   appropriate sampling for the type of the trajectory in question and set
   the output time format picture with the ``-f'' option to generate more
   human friendly output time tags.
 
   As an example of sampling trajectory from meta-kernels, below SPKDIFF is
   run to generate a table of states (no ``-t'' option because ``-t dump''
   is the default for sampling cases) of Stardust (``-b1 SDU'') relative to
   the Sun (``-c1 SUN'') in the Ecliptic of J2000 inertial reference frame
   (``-r1 ECLIPJ2000''), computed with 86400 second (1 day) step (``-s
   86400''), with time tags printed as UTCs in ISO DOY format
 
      -f 'YYYY-DOYTHR:MN:SC.### ::RND'
 
   using SPKs listed in the latest Stardust SPICE archive meta-kernel (``-k
   sdu_v03.tm''). Note that an LSK file does not need to be explicitly
   provided on the command line because the meta-kernel includes an LSK
   file.
 
   SPKDIFF, run with the options mentioned above:
 
      > spkdiff -k  sdu_v03.tm \
                -f  'YYYY-DOYTHR:MN:SC.### ::RND' \
                -b1 SDU \
                -c1 SUN \
                -r1 ECLIPJ2000 \
                -s  86400
 
   produces the following output:
 
      #
      # Sampling of 40968 'ECLIPJ2000'-referenced geometric states
      #
      #    of 'SDU' (-29) relative to 'SUN' (10)
      #    computed using
      #
      #       sdu_v03.tm
      #
      # with a 86400.000000000 second (1:00:00:00.000000) step size
      # within the non-continuous (with 2 gaps) time period
      #
      #    from '1999 FEB 07 21:32:10.699 TDB' (-28304869.300000 TDB seco
      #    to   '2111 APR 07 00:00:00.000 TDB' (3511080000.0000 TDB secon
      #
      # Times were generated by TIMOUT using 'YYYY-DOYTHR:MN:SC.### ::RND
      #
      # time, x, y, z, vx, vy, vz
      1999-038T21:31:06.515 -1.1081241906831E+08 +9.7436557730578E+07 -3.
      1999-040T00:58:55.815 -1.1308778501370E+08 +9.4731491300541E+07 -8.
      1999-040T00:58:55.816 -1.1308777975290E+08 +9.4731487534379E+07 -8.
      ...
      2111-095T00:58:53.818 -3.9989092550623E+07 -2.1645212911162E+08 -1.
      2111-096T00:58:53.818 -3.8191514897493E+07 -2.1733323167609E+08 -1.
      2111-096T23:58:53.814 -3.6465563483695E+07 -2.1815901299532E+08 -1.
 
   (To fit into the page width, the lines were truncated at the 67th
   position.)
 
 
Coverage: Coverage for a Single Body
 
   Because of its ability to determine default coverage from the primary
   SPK, in some cases SPKDIFF can be used instead of the SPK summary
   utility BRIEF to display coverage summary for a given body from a given
   SPK file. For that, the user should specify the ``-t dumpc'' option and
   provide the name of the SPK file. The program will pick the default body
   from the file using the rules described earlier in this User's Guide and
   will display a coverage summary for this body. If a summary for a body
   different from the default pick is desired, that body needs to be
   specified using the ``-b1'' (or ``-b2'') option. For coverage boundary
   times to be displayed in a format other that TDB seconds past J2000 the
   user can supply an LSK file with the ``-k'' option and set the output
   time format picture with the ``-f'' option.
 
   As an example of a simple coverage report, below SPKDIFF is run to show
   coverage (``-t dumpc'') for MRO with time tags printed as UTCs in the
   ISO date format using options
 
      -k naif0010.tls -f 'YYYY-MM-DDTHR:MN:SC.### ::RND'
 
   provided by the MRO SPK file (``mro_psp20.bsp'') containing data only
   for the MRO spacecraft. Note that in this run the program automatically
   picks the body from the specified SPK file.
 
   SPKDIFF, run with the options mentioned above and the name of the SPK
   file:
 
      > spkdiff -k naif0010.tls \
                -f 'YYYY-MM-DDTHR:MN:SC.### ::RND' \
                -t dumpc \
                mro_psp20.bsp
 
   produces the following output:
 
      #
      # Coverage for 'J2000'-referenced geometric states
      #
      #    of 'MARS RECON ORBITER' (-74) relative to 'MARS BARYCENTER' (4)
      #    computed using
      #
      #       ../lsk/naif0010.tls
      #       mro_psp20.bsp
      #
      # with a 7960.3603585812 second (0:02:12:40.360359) step size
      # within the continuous time period
      #
      #    from '2011 JUL 01 00:01:06.184 TDB' (362750466.18413 TDB secon
      #    to   '2011 OCT 01 01:01:06.182 TDB' (370702866.18235 TDB secon
      #
      # Times were generated by TIMOUT using 'YYYY-MM-DDTHR:MN:SC.### ::R
      #
      # interval_start, interval_stop, interval_duration_sec, interval_du
      2011-07-01T00:00:00.000 2011-10-01T01:00:00.000     7952399.998223
         92:00:59:59.998223
 
   (To fit into the page width, all lines but the last were truncated at
   the 67th position; the last line was wrapped.)
 
   As seen in the report, the MRO trajectory provided in this SPK covers
   approximately 92 days and 1 hour.
 
 
Coverage: Coverage Overlap for Two Bodies
 
   The coverage report can also be used to see the intervals over which
   comparison of two trajectories was performed or, in the more general
   case, to see the overlap between coverages of two trajectories provided
   in two SPKs given as primary kernels or two sets of SPKs given as
   additional kernels.
 
   In the example below SPKDIFF is run to show overlap in trajectory
   coverage (``-t dumpc'') for MRO between two MRO SPKs (``mro_psp19.bsp''
   and ``mro_psp20.bsp''), with time tags printed as UTCs in the ISO date
   format using options
 
      -k naif0010.tls -f 'YYYY-MM-DDTHR:MN:SC.### ::RND'
 
   Note that in this run the program automatically picks the body and all
   other defaults from the first SPK file.
 
   SPKDIFF, run with the options mentioned above and the names of the SPK
   files:
 
      > spkdiff -k naif0010.tls \
                -f 'YYYY-MM-DDTHR:MN:SC.### ::RND' \
                -t dumpc \
                mro_psp19.bsp \
                mro_psp20.bsp
 
   produces the following output:
 
      #
      # Coverage overlap for 'J2000'-referenced geometric states
      #
      #    of 'MARS RECON ORBITER' (-74) relative to 'MARS BARYCENTER' (4
      #    computed using
      #
      #       naif0010.tls
      #       mro_psp19.bsp
      #
      # and 'J2000'-referenced geometric states
      #
      #    of 'MARS RECON ORBITER' (-74) relative to 'MARS BARYCENTER' (4
      #    computed using
      #
      #       naif0010.tls
      #       mro_psp20.bsp
      #
      # with a 3.6036036024700 second (0:00:00:03.603604) step size
      # within the continuous time period
      #
      #    from '2011 JUL 01 00:01:06.184 TDB' (362750466.18413 TDB secon
      #    to   '2011 JUL 01 01:01:06.184 TDB' (362754066.18412 TDB secon
      #
      # Times were generated by TIMOUT using 'YYYY-MM-DDTHR:MN:SC.### ::R
      #
      # interval_start, interval_stop, interval_duration_sec, interval_du
      2011-07-01T00:00:00.000 2011-07-01T01:00:00.000        3599.999999
          0:00:59:59.999999
 
   (To fit into the page width, all lines but the last were truncated at
   the 67th position; the last line was wrapped.)
 
   As seen in the report, the overlap between MRO trajectories provided in
   these SPKs is approximately 1 hour.
 
 
Coverage: Gaps in Coverage
 
   The gap report is useful in determining the presence and size of gaps in
   coverage of a trajectory provided by a single SPK given as the sole
   primary kernel or a set of SPKs given as additional kernels, or gaps in
   the overlap between coverages of two trajectories provided in two SPKs
   given as primary kernels or two sets of SPKs given as additional
   kernels.
 
   In the example below SPKDIFF is run to show gaps in trajectory coverage
   (``-t dumpg'') of Stardust (``-b1 SDU'') relative to the Sun (``-c1
   SUN'') in the Ecliptic of J2000 inertial reference frame (``-r1
   ECLIPJ2000''), with time tags printed as UTCs in the ISO DOY format
 
      -f 'YYYY-DOYTHR:MN:SC.### ::RND'
 
   for all SPKs listed in the latest Stardust SPICE archive meta-kernel
   (``-k sdu_v03.tm''). Note that an LSK file does not need to be
   explicitly provided on the command line because the meta-kernel includes
   an LSK file.
 
   SPKDIFF, run with the mentioned above options and the names of the SPK
   files:
 
      > spkdiff -k  sdu_v03.tm \
                -f 'YYYY-DOYTHR:MN:SC.### ::RND' \
                -b1 SDU \
                -c1 SUN \
                -r1 ECLIPJ2000 \
                -t  dumpg
 
   produces the following output:
 
      #
      # Coverage for 'ECLIPJ2000'-referenced geometric states
      #
      #    of 'SDU' (-29) relative to 'SUN' (10)
      #    computed using
      #
      #       sdu_v03.tm
      #
      # with a 3550034.9742187 second (41:02:07:14.974219) step size
      # within the non-continuous (with 2 gaps) time period
      #
      #    from '1999 FEB 07 21:32:10.699 TDB' (-28304869.300000 TDB seco
      #    to   '2111 APR 07 00:00:00.000 TDB' (3511080000.0000 TDB secon
      #
      # Times were generated by TIMOUT using 'YYYY-DOYTHR:MN:SC.### ::RND
      #
      # gap_start, gap_stop, gap_duration_sec, gap_duration_string
      1999-040T00:58:55.815 1999-040T00:58:55.816           0.000982
      0:00:00:00.000982
      1999-121T00:58:55.815 1999-121T00:58:55.818           0.003000
      0:00:00:00.003000
 
   (To fit into the page width, all lines but the last two were truncated
   at the 67th position; the last two lines were wrapped.)
 
   As seen in the report, the SDU trajectory provided by the SPK files
   listed in this meta-kernel has two very small gaps (~0.001 and ~0.003
   seconds) close to the start of the coverage.
 
