Index Page
SPKDIFF User's Guide

Table of Contents


   SPKDIFF User's Guide
      Abstract
      Summary
      If You Are in a Hurry
         To Check if Two SPK Files Provide Identical Data
         To Assess Difference Between Two SPK Files
         To Sample Trajectory from an SPK File
         To Sample Trajectory from a set of Kernels
      Usage
      Options
      Kernel Files
         Primary Kernel Files
         Additional Kernel Files
      Comparison Runs vs. Sampling Runs
      Runs with Two, One, and No Primary SPK(s)
         Runs with Two Primary SPK Files
         Runs with One Primary SPK File
         Runs Without Primary SPK Files
      Specifying/Picking Defaults for Bodies, Centers, and Frames
         Specifying/Picking Defaults for Bodies
         Specifying/Picking Defaults for Centers
         Specifying/Picking Defaults for Frames
         Body, Center, and Frame Selection Scenarios
      Times for Comparison/Sampling
         Coverage Window
         Times within Coverage Window
         Times for Comparison/Sampling Selection Scenarios

   Output
      Overview of Report Types
         Time Tag Format for ``dump*'' Reports
         Numeric Format for ``dump*'' Reports
      Report Header
         Report Header for Comparing Two Trajectories
         Report Header for Coverage/Gaps for Two Trajectories
         Report Header for Sampling Trajectory
         Report Header for Coverage/Gaps for Trajectory
      Report Formats
         Basic Report (no ``-t'' option or with ``-t basic'')
         View Frame Statistics Report (``-t stats'')
         Dump Report (no ``-t'' option or with ``-t dump'')
         View Frame Dump Report (``-t dumpvf'')
         Coverage Intervals Dump Report (``-t dumpc''):
         Coverage Gaps Dump Report (``-t dumpg'')
      Troubleshooting
      Examples
         Comparison: Checking if Two SPKs Provide the Same Trajectory
         Comparison: Checking if Two SPK files Differ Enough to Matter
         Comparison: Checking the Down Track Timing Error
         Comparison: Checking Trajectory Differences Over Time
         Sampling: States from a Single SPK File
         Sampling: States from Many SPKs Listed in Meta-Kernel(s)
         Coverage: Coverage for a Single Body
         Coverage: Coverage Overlap for Two Bodies
         Coverage: Gaps in Coverage




Top

SPKDIFF User's Guide





Last revised on 2021 NOV 17 by B. V. Semenov.



Top

Abstract




SPKDIFF provides means for comparing the trajectories of two bodies or sampling the trajectory of a single body using data from SPICE kernels.



Top

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.



Top

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.



Top

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.



Top

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>


Top

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>


Top

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.



Top

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.



Top

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 routine. 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 routine. 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 routine, 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''.


Top

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).



Top

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.



Top

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.



Top

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



Top

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.



Top

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.



Top

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.



Top

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.



Top

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.



Top

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.



Top

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.



Top

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.



Top

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.



Top

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 routine (see STR2ET 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.



Top

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 routine 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.



Top

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.



Top

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.



Top

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.



Top

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.



Top

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 routine. 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.



Top

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).



Top

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.



Top

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.''



Top

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.



Top

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.



Top

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.



Top

Report Formats






Top

Basic Report (no ``-t'' option or with ``-t basic'')



The basic report shows only the maximum and average magnitudes of position and velocity vector absolute and relative differences. 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.



Top

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.



Top

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.



Top

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.



Top

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.



Top

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.



Top

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.



Top

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.



Top

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).



Top

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.



Top

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.



Top

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.



Top

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.)



Top

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.)



Top

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.



Top

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.



Top

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.