 
SPKMERGE User's Guide
===========================================================================
 
   Last revised on 2014 JAN 21 by B. V. Semenov.
 
 
Abstract
--------------------------------------------------------
 
   SPKMERGE is a program that subsets or merges one or more SPK files into
   a single SPK file.
 
 
Introduction
--------------------------------------------------------
 
   SPKMERGE builds new SPK files by merging entire or subsets of one or
   more existing SPK files. SPKMERGE creates SPK kernels that have no
   overlapping ephemeris; the order in which source files are specified
   determines the precedence when source files contain overlapping data.
 
   SPKMERGE reads all its instructions from a command file. A command file
   is an ASCII formatted file containing `KEYWORD = value' assignments.
 
 
Running SPKMERGE
--------------------------------------------------------
 
   SPKMERGE will prompt for the name of the command file when you start the
   program. Alternately, you can name the command file as the only argument
   on the command line.
 
 
Command file syntax
--------------------------------------------------------
 
   Instructions are specified in a command file using `KEYWORD = value'
   assignments. The rules for forming assignments are listed here.
 
       --   Up to 6000 assignments may be specified in a single command
            file. Each assignment can be up to 350 characters long.
 
       --   An assignment must start on a line by itself. A keyword must
            appear first, followed by an equals sign, followed by a value.
 
       --   Keywords are not case sensitive---they may appear in upper,
            lower, or mixed case.
 
       --   Spaces and tabs are ignored, except for those embedded within
            values.
 
       --   Values other than file names may extend over multiple lines. No
            continuation characters are necessary.
 
       --   File names provided as values can be up to 255 characters long.
 
       --   Values other than file names can be up to 300 characters long.
 
       --   A semi-colon signals the beginning of a comment. All characters
            following a semi-colon on a line are ignored.
 
   In addition, there are other non-lexical rules that apply to
   assignments:
 
       --   Some assignments must be present in the command file, while
            others are optional.
 
       --   Most assignments can only follow certain other assignments.
 
       --   All assignments have restrictions on the number of times they
            can appear in the command file.
 
   These rules will be discussed as the keywords are introduced.
 
 
Command file keywords
--------------------------------------------------------
 
   A command file must contain at least these three keywords:
 
      LEAPSECONDS_KERNEL
      SPK_KERNEL
      SOURCE_SPK_KERNEL
 
   The `LEAPSECONDS_KERNEL' keyword must appear in the file before the
   first `SPK_KERNEL' keyword. An `SPK_KERNEL' keyword must appear before
   the first `SOURCE_SPK_KERNEL' keyword.
 
   The optional keywords are:
 
      LOG_FILE
      BODIES
      BEGIN_TIME
      END_TIME
      INCLUDE_COMMENTS
 
   Normally keywords must appear in the following order:
 
      LEAPSECONDS_KERNEL     = <LSK file name>          (required)
      SPK_KERNEL             = <output SPK name>        (required)
         LOG_FILE            = <log file name>             (optional)
         BODIES              = <body ID list>              (optional)
         BEGIN_TIME          = <begin time>                (optional)
         END_TIME            = <end time>                  (optional)
         ... more BEGIN_/END_TIME pairs can follow ...     (optional)
         SOURCE_SPK_KERNEL   = <source SPK name>        (required)
            INCLUDE_COMMENTS = <yes or no>                 (optional)
            BODIES           = <body ID list>              (optional)
            BEGIN_TIME       = <begin time>                (optional)
            END_TIME         = <end time>                  (optional)
            ... more BEGIN_/END_TIME pairs can follow ...  (optional)
         SOURCE_SPK_KERNEL   = <source SPK name>        (optional)
            INCLUDE_COMMENTS = <yes or no>                 (optional)
            BODIES           = <body ID list>              (optional)
            BEGIN_TIME       = <begin time>                (optional)
            END_TIME         = <end time>                  (optional)
         ... more SOURCE_SPK_KERNEL blocks can follow ...  (optional)
      SPK_KERNEL             = <output SPK name>        (optional)
         LOG_FILE            = <log file name>             (optional)
         BODIES              = <body ID list>              (optional)
         BEGIN_TIME          = <begin time>                (optional)
         END_TIME            = <end time>                  (optional)
         ... more BEGIN_/END_TIME pairs can follow ...     (optional)
         SOURCE_SPK_KERNEL   = <source SPK name>        (optional)
            INCLUDE_COMMENTS = <yes or no>                 (optional)
            BODIES           = <body ID list>              (optional)
            BEGIN_TIME       = <begin time>                (optional)
            END_TIME         = <end time>                  (optional)
            ... more BEGIN_/END_TIME pairs can follow ...  (optional)
         ... more SOURCE_SPK_KERNEL blocks can follow ...  (optional)
      ... more SPK_KERNEL blocks can follow ...            (optional)
 
   All the keywords are described in detail below.
 
 
LEAPSECONDS_KERNEL
 
   The value of this keyword must be the name of a SPICE leapseconds kernel
   file. This assignment must be present and must be the first assignment
   in the command file. If the leapseconds kernel does not reside in the
   current directory, remember to include the directory path of the file,
   as shown in this example:
 
      LEAPSECONDS_KERNEL  = /kernels/gen/lsk/naif0010.tls
 
 
SPK_KERNEL
 
   The value of this keyword must be the name of the SPK file that SPKMERGE
   is to create. After this assignment, the names of one or more source SPK
   files must be listed by using the `SOURCE_SPK_KERNEL' assignment.
 
   Multiple SPK files (up to 1000) can be created by SPKMERGE by repeating
   the `SPK_KERNEL' assignment.
 
 
SOURCE_SPK_KERNEL
 
   The value of this keyword must be the name of an existing SPK file that
   you want to merge into an output SPK file. Multiple SPK files or
   different parts of a single SPK file can be merged into an output SPK
   file by repeating this assignment. It can be repeated up to 1000 times
   for each output SPK file. Before you name the files you want to merge,
   you must have previously specified the name of an output SPK kernel by
   using the `SPK_KERNEL' assignment.
 
   The sample command file below instructs SPKMERGE to create one SPK file
   by merging three existing SPK files in their entirety.
 
      LEAPSECONDS_KERNEL  = /kernels/gen/lsk/naif0010.tls
 
      SPK_KERNEL          = complete.bsp
        SOURCE_SPK_KERNEL = planets.bsp
        SOURCE_SPK_KERNEL = gll_1.bsp
        SOURCE_SPK_KERNEL = gll_2.bsp
 
   SPKMERGE will not create an SPK file that has overlapping data. The
   files you list first have precedence. (Caution: this is the opposite of
   the precedence rules used elsewhere in SPICE!) In the example above,
   source data from planets.bsp will have precedence over data from
   gll_1.bsp, and both will have precedence over gll_2.bsp.
 
 
BODIES
 
   This keyword is optional. If present, it restricts which bodies are
   merged. This keyword can appear in one of two places: after a
   `SOURCE_SPK_KERNEL' assignment, or before the first `SOURCE_SPK_KERNEL'
   assignment. In the former case, the keyword lists the bodies that should
   be merged from a specific source SPK file; in the latter case, the
   keyword lists the bodies that should be merged from all source SPK files
   that do not have specific bodies mentioned. This keyword may appear only
   once for each output or source SPK file. A body listed in this
   assignment does not have to be contained within the source SPK file(s)
   the assignment applies to. Remember that SPKMERGE will not create a file
   that has overlapping data, so even if an SPK kernel contains a body you
   list, it may not necessarily be merged.
 
   The bodies must be given as NAIF integer body IDs; the IDs may be
   delimited by spaces or commas.
 
   In the example below, only data for bodies 10, 399 and 301 will be
   merged from `planets.bsp'. The other two files will be merged in their
   entirety---assuming no overlapping data.
 
      LEAPSECONDS_KERNEL  = /kernels/gen/lsk/naif0010.tls
 
      SPK_KERNEL          = complete.bsp
        SOURCE_SPK_KERNEL = planets.bsp
          BODIES          = 10, 399, 301
        SOURCE_SPK_KERNEL = gll_1.bsp
        SOURCE_SPK_KERNEL = gll_2.bsp
 
   If you want to merge only data for bodies 10, 399, 301 and -77, from
   each of the three source files the command file could be structured as
   shown below:
 
      LEAPSECONDS_KERNEL  = /kernels/gen/lsk/naif0010.tls
 
      SPK_KERNEL          = complete.bsp
        BODIES            = 10, 399, 301, -77
        SOURCE_SPK_KERNEL = planets.bsp
        SOURCE_SPK_KERNEL = gll_1.bsp
        SOURCE_SPK_KERNEL = gll_2.bsp
 
 
BEGIN_TIME, END_TIME
 
   These two keywords operate just like the `BODIES' keyword, except they
   restrict times instead of bodies. The `END_TIME' keyword must
   immediately follow the `BEGIN_TIME' keyword. Together, these keywords
   represent a time window. Multiple windows (up to 1000) can be specified
   by repeating these two assignments.
 
   SPKMERGE accepts many different time input formats from a variety of
   time systems. The default input system is UTC, but one may specify
   ephemeris time (TDB) instead. For complete details on the accepted time
   strings see the STR2ET section of ``Time Required Reading'' (time.req).
   Below are a few examples.
 
   The following illustrates utilization of the default time system, UTC.
 
      LEAPSECONDS_KERNEL  = /kernels/gen/lsk/naif0010.tls
 
      SPK_KERNEL          = complete.bsp
        SOURCE_SPK_KERNEL = planets.bsp
          BEGIN_TIME      = 1 JAN 1994 00:00:00.000
          END_TIME        = 1 JUL 1994 00:00:00.000
        SOURCE_SPK_KERNEL = gll_1.bsp
          BEGIN_TIME      = 1 JAN 1994 00:00:00.000
          END_TIME        = 1 JUL 1994 00:00:00.000
        SOURCE_SPK_KERNEL = gll_2.bsp
          BEGIN_TIME      = 1 JAN 1994 00:00:00.000
          END_TIME        = 1 JUL 1994 00:00:00.000
 
   To select ephemeris time (ET, also called Barycentric Dynamical Time or
   TDB) as the desired input time system, append TDB to the end of the time
   string. The following example demonstrates the merging of the contents
   of two SPK files for the period between the ephemeris times `15 Feb
   1998' and `21 Jul 1998'.
 
      LEAPSECONDS_KERNEL  = /kernels/gen/lsk/naif0010.tls
 
      SPK_KERNEL          = complete.bsp
        SOURCE_SPK_KERNEL = planets.bsp
          BEGIN_TIME      = 15 FEB 1998 00:00:00.000 TDB
          END_TIME        = 21 JUL 1998 00:00:00.000 TDB
        SOURCE_SPK_KERNEL = mgs_ab2.bsp
          BEGIN_TIME      = 15 FEB 1998 00:00:00.000 TDB
          END_TIME        = 21 JUL 1998 00:00:00.000 TDB
 
   In the following example SPKMERGE is instructed to merge only the UTC
   times `1 Jan 1994' through `2 Jan 1994'. Since no `BODIES' keyword is
   given, all bodies will be merged. In this example a command log file is
   also produced (see explanation below).
 
      LEAPSECONDS_KERNEL  = /kernels/gen/lsk/naif0010.tls
 
      SPK_KERNEL          = complete.bsp
        LOG_FILE          = gll_early_cruise.log
        BEGIN_TIME        = 1 JAN 1994 00:00:00.000
        END_TIME          = 1 JUL 1994 00:00:00.000
        SOURCE_SPK_KERNEL = planets.bsp
        SOURCE_SPK_KERNEL = gll_1.bsp
        SOURCE_SPK_KERNEL = gll_2.bsp
 
 
LOG_FILE
 
   If this keyword is present it instructs SPKMERGE to create a log file.
   This keyword can only follow an `SPK_KERNEL' assignment and can appear
   only once for each output SPK file. A log file created by SPKMERGE will
   contain a list of all the SPK files that were used to create an SPK
   file, including all the times and all the bodies. The log file will be
   in the form of a command file, so it can be used as such if the need
   arises. An exact copy of the log file is always placed in the comment
   area of an SPK file created by SPKMERGE. The value field for this
   assignment can be any file name that is valid on the computer being
   used.
 
 
INCLUDE_COMMENTS
 
   If this keyword is present it can only have a value of YES or NO (upper
   or lower case), and it can only follow a `SOURCE_SPK_KERNEL' assignment
   and appear only once for each source SPK file. If the value of this
   keyword is YES, the comment area of the source SPK file named prior to
   this assignment is merged into the new SPK file, otherwise it is not.
   The default action is to not merge the comment area of a source SPK
   file.
 
