30-Dec-2021

Welcome to SPICE

Welcome to SPICE, an ancillary information system that provides scientists and engineers the capability to include space geometry and event data into mission design, science observation planning, and science data analysis software.

SPICE is used throughout NASA and within many other U.S. and international agencies for organizing, distributing, and accessing ancillary data associated with space science missions. The NAIF website contains the few important rules regarding using SPICE, including the Toolkit license and other important considerations. Please take a moment to read these.

Using SPICE Toolkit Software

Your first step is to download a SPICE Toolkit package from the NAIF website if a current version is not already installed on your machine or available through some form of connected server. In addition to the Toolkit download package and installation script you will find several important documents.

The README file provides installation instructions.

The Description document (dscriptn.txt) provides an overview of the contents and organization of the Toolkit.

The What's New document (whats.new) describes new and changed capabilities of this Toolkit as regards previous versions, and lists the supported environments (environment = language/platform/OS/compiler) for the Toolkit.

What Else is Needed

Use of the SPICE system requires (at a minimum) one of the following: a FORTRAN 77 compiler/linker, an ANSI C compiler/linker, an IDL installation, or a MATLAB installation, that is consistent with the components NAIF used in building the Toolkit you have downloaded. You'll also need a text editor—preferably one that is familiar to you and perhaps that is good for writing code. Familiarity with a debugger can also be helpful as you develop your application program. You will need to know how to build and execute a program on your computer.

Getting Started

Tutorials

Programming Examples

• Most high level Toolkit APIs include at least one complete, compilable/executable example in their reference documentation, a.k.a. headers. These examples illustrate how a particular routine might be used in solving a typical problem. The html versions of Toolkit documentation contain hyperlinks to these headers, or you may open the source code module in an editor or with a text display utility.

• The code for several very simple SPICE-based programs is provided in a set of so-called "cookbook" programs found in each copy of the Toolkit. The topics covered are time conversions (tictoc), reading a trajectory file (states), computing the angular separation of two objects as seen from a third (simple), and computing a spacecraft's sub-observer point on a target body (subpt). The annotated source code, a User's Guide, and sample data files for running these programs are all provided.

• The code for a program that computes a spacecraft instrument's boresight intercept on a body's surface, plus the phase, incidence and emission angles at that point (and a bit more) is provided in the set of tutorials named "program_(language)." Here you can follow the code development step-by-step.

• A set of "open book" programming lessons is available from the NAIF server. These are used in the annual SPICE Training classes taught by NAIF staff, but you can do them on your own. Each lesson comes with a problem statement including a graphic that depicts the problem, a set of notes and tips about how to create the desired program, a list of the SPICE data files (kernels) to be used, and the actual code solution created by a NAIF staff member. The kernels needed to run the programs are also provided, and the answers obtained from the completed NAIF-written version of the program is shown at the end. Each lesson is broken into manageable chunks, with the intermediate answers provided. The primary lessons are:
  • Toolkit Contents  (practice navigating through the Toolkit components)
  • Starting Programming  (demonstrating you can compile and link a program)
  • Remote Sensing  (a realistic space geometry task for a remote sensing instrument)
  • Other Stuff  (a collection of small, independent tasks)

  Additional lessons are:

  • Insitu Sensing  (a realistic space geometry task for an in-situ instrument)
  • Event Finding  (a more difficult lesson involving visibility calculations in the face of occultations)

Finding the Appropriate Routine

The real programming power of SPICE derives from the extensive set of built in computations you need not re-invent. However, as the Toolkits contain hundreds of routines, reading all routine headers or API descriptions to determine the appropriate routine for a given task is not practical. In addition to numerous API references in the tutorials mentioned earlier, NAIF provides two products in each Toolkit to help you find an API that may meet your needs.

1. A document named "Most Used APIs" provides a brief summary of the purpose and use of the most used (high-level) APIs. The document is organized by functional categories, such as:
   • time system conversions
   • positions of spacecraft and natural bodies
   • orientation of spacecraft and instruments
   • reference frame transformations
   • illumination angles

   and so on.

2. A permuted index may help you identify the proper routine based on functionality statements. Since the index is permuted, any of a series of short phrases you may think of to describe a computation you need might be found in the permuted index document, pointing to a relevant routine. For example you will find

      Cross product of two vectors
      Product of two vectors, cross
      Vectors, cross product of two
   

   all listed in the permuted index. Each of these points to the SPICELIB subroutine VCRSS, or the CSPICE function vcrss_c, that computes a cross product. Using the hyperlinking within this document you can click on the API (subroutine or function) name to bring up the source code header for that module. In this header you will find the detailed specifications and examples needed to decide if the module does indeed provide the computation you sought.

   The permuted index is found in the doc/html/info folder and is named spicelib_idx.html in FORTRAN toolkits, cspice_idx.html in CSPICE toolkits, icy_idx.html in Icy toolkits, and mice_idx.html in Mice toolkits.

SPICE Kernels

SPICE stores data in files that are often referred to as "kernels.'' A kernel may store data in either text (ASCII) or binary format. In order to access data within a kernel an application program must "load" the kernel using a SPICE API ("furnsh").

Excepting the important platform-specific differences mentioned below, any particular kernel may be used with any of the Toolkits.

Text Kernels

The set of text kernels consists of:

• Spacecraft Clock kernels (SCLK)
• Leapseconds kernel (LSK)
• Text-style (most) Physical Constants kernels (PCK)
• Instrument parameter kernels (IK)
• Frame definition kernels (FK)
• Some E-kernels (EK, although EKs are now rarely used)
• Meta-kernels (MK, also called "furnsh kernels")

As for any text file, a SPICE text kernel contains operating system specific line terminators. Trying to use a non-native style text kernel is one of the most prevalent user errors. To mitigate this problem somewhat the CSPICE, Icy, and Mice Toolkits include code that allows reading of non-native text kernels. Unfortunately this accommodation is not possible in the FORTRAN Toolkits. FORTRAN Toolkits contain code that will issue a SPICE error message whenever a non-native text kernel load occurs.

Binary Kernels

The set of binary kernels consists of:

• SP-kernels (SPK)
• Binary-style (just a few) PC-kernels (PCK)
• C-kernels (CK)
• Some spacecraft Events kernels (EK/ESP)

Binary kernels typically contain numeric and textual information. Hardware architecture (the CPU chip) determines the format of numeric binary data; the two formats used by computers supported by NAIF are called "big endian" and "little endian." Because kernels are frequently transferred between computers which may use incompatible binary architecture, SPICE software has been designed to read non-native binary kernels. (But not to write to a non-native binary kernel.)

Loading Kernels

One "loads" kernels to give the SPICE system the information needed to find the data within the kernels. The tutorial named "intro to kernels" quickly describes the loading process. The Kernel Required Reading document (kernel.req) provides a complete description. Examples of loading kernels may be seen in the cookbook programs and the "open book" programming lessons previously mentioned. Except for unusual circumstances, kernels of all types need "loading" only once in your program—do not embed the load statement in a loop.

Creating or Modifying Kernels

The majority of SPICE users will not need to create or modify kernels. But if you do need to do so you must do so carefully to avoid structural problems and to help ensure others will easily use the kernel. Careful testing of a kernel you create, and of the kernel production process for binary kernels, is essential!

Creating or Modifying Text Kernels

Creating or Modifying Binary Kernels

Some SPICE users will want to create or modify binary kernels. This task requires a good understanding of the particular SPICE kernel type, and of the appropriate binary kernel writer API(s). You should be familiar with the tutorial discussing the kernel type of interest. NAIF recommends you also read the "Making an SPK" or the "Making a CK" tutorial, if relevant. You should also read appropriate portions of the "required reading" reference document pertinent to your task (spk.req, ck.req, pck.req or ek.req).

Annotating a New or Modified Kernel

Comments (metadata) are added to text kernels using any text editor, just as for making or modifying the data sections of the text kernel.

Comments (metadata) are normally added to, extracted from, or removed from a binary kernel using a Toolkit utility program named "commnt."

Selecting and Obtaining Kernels

Knowing which kernel, or set of kernels, to use in any particular task can be a challenge. Having kernel producers use a consistent and well thought out kernel naming methodology is a must. Having kernel producers provide high quality metadata with each kernel or kernel collection is equally important. Nevertheless, kernel selection is one of the most challenging aspect of using the SPICE system. (Probably the same challenge would exist no matter what kind of ancillary information system would be used.)

Often three classes of kernels are available:

• mission operations kernels
• mission archived kernels
• generic kernels

Mission operations kernels are those produced before or while a spacecraft is operating, to support science observation planning, initial science data processing and analysis, and mission engineering functions. There are often many of these kernels. Those types that provide data as a function of time—especially SPK and CK—may have many overlaps in time. Some may be "predict" versions made for observation planning while others may be "reconstruction" versions made for science data processing. Selecting kernels from this class can be quite a challenge, especially if you are not a regular consumer of mission operations kernels.

Certainly for NASA planetary missions, and probably for missions operated by other agencies, mission archived kernels are usually your best bet—if there are already archived kernels covering the period of the mission of interest to you. A mission's archived kernels are usually better organized and documented, and often sets of "small" kernels covering short periods of time have been merged into more easily used "large" kernels covering a longer time span.

For JPL-managed missions the mission archived kernels often have associated "furnsh" kernels (meta-kernels) that logically aggregate the entire collection of kernels appropriate for a given time span or a given mission phase. Make use of these!

Be aware that for all but the shortest missions the archiving of SPICE data is usually done in increments, with a new batch of data added to the collection on a regular basis—typically every three or six months. The usual (preferred) NAIF methodology for archiving SPICE data is to create a single, "accumulating" SPICE dataset. Every few months the next batch of kernels is added to the existing dataset, with updates made to the dataset's metadata indicating the new (longer) time span covered by the whole collection.

Generic kernels are those that are not tied specifically to one mission; they are usually applicable to many missions, or could be useful independent of any mission. Examples of generic kernels are:

• the planetary, satellite, comet and asteroid ephemeris files produced by JPL (SPKs)
• the leapseconds kernel (LSK)
• the "generic" version of the planetary constants kernel (text PCK)
• the high-precision lunar orientation kernel (binary PCK)
• earth station topocentric locations (SPK) and reference frames (FK)
• various kinds of mission-independent reference frame specifications (FK)

A majority of the generic kernels are produced by NAIF and made available from the generic kernels link on the Data webpage. But, as the use of SPICE spreads, other agencies may also offer generic kernels.

Since you probably won't produce your own kernels, you need to obtain them from someplace—normally a project database or project data management team. Once a mission is complete the kernels should be available from a national data archive center. The NAIF node of the Planetary Data System is one such example (https://naif.jpl.nasa.gov/naif/data.html).

Troubleshooting Options

With any new product people sometimes encounter problems. If you run into problems, here are some steps you can take to try to resolve them.

• A tutorial named "common problems" is available from the NAIF website; take a look at this.
• Several of the subsystem tutorials (for example SPK and CK) contain a discussion of common problems at the end of the tutorial; check these out.
• All Toolkit distributions include a document named problems.req in the /doc folder, and in the doc/html folder. This document lists the most common problems and aggravations the new SPICE user might experience, and the most probable solutions.
• If you think the problem is related to a SPICE routine, look at the reference documents related to the routine—these are listed in the required reading section of the routine's header. These documents may contain useful information for diagnosing and correcting the problem.
• If the problem seems related to your programming environment, (for example you can't link a program, can't find a file, don't have sufficient privileges to perform some action, etc.) contact your system administrator. She/He may be able to assist you.
• If you are using either the Icy (IDL) or Mice (MATLAB) version of SPICE be sure to read the environment configuration information for these two products provided in the "Preparing for Programming" tutorial.
• If you are using a SPICE based program developed by someone else, contact that program's author for assistance.
• If your program executes but your output disagrees with those of a colleague who supposedly ran the same program with identical inputs, ensure you both used the same kernel files.
• If you don't have the latest version of a kernel associated with a flight project (or want to find out if you do) contact the project's SPICE data administrator.
• If you can't seem to fit the problem into one of the above categories, or just aren't getting anywhere, send us (NAIF) e-mail or call us on the phone; we'll do what we can to help within our resources and programmatic limitations. See the getting help link on the NAIF webpage.

SPICE Software Quality and Stability

NAIF is committed to providing a robust, flexible, and understandable product that suits the needs of the space science community. SPICE Toolkit software undergoes considerable review and testing; the documentation for the SPICE software is extensive and (usually) accurate.

The SPICE system is undergoing continuous development to both improve existing capabilities and to add new ones. However, NAIF is committed to providing SPICE users a consistent product. We understand the frustrations of using a set of software only to see it change in a subsequent release. Therefore, we do not change the intended functionality of, or the interface to, previously released software unless needed to correct a bug, or occasionally to improve an implementation. If you build a program incorporating today's SPICE system, it should work the same way when you re-build it with tomorrow's SPICE system. Retaining backwards compatibility is a primary development objective within NAIF.

SPICE Data Accuracy

In some cases the source data are transformed ("manipulated") before or being placed or as they are placed inside a kernel file. In most cases the data extracted from a kernel are transformed by the Toolkit application program interfaces (APIs, sometimes referred to in SPICE documentation as subroutines) SPICE customers use to compute the observation geometry parameters of interest—position, range, LAT/LON, lighting angles, etc.

One can see there are several possible contributors to the accuracy of geometry parameters computed using SPICE. (The situation may be quite similar when using means other than SPICE to make the same kinds of computations.) One cannot make an assessment of accuracy that applies to all SPICE-based results. In many cases the accuracy of a high-level geometry parameter determined using SPICE is principally determined by the accuracy of the source data used to make a kernel—"garbage in, garbage out" applies. In some cases the accuracy is somewhat or even highly dependent on the kernel producer's knowledge of the dynamics or timing of the physical system involved and his/her skill in using kernel production software. (This is often the case for production of SPKs, CKs, and SCLKs.)

Because of the complexity of determining data accuracy, especially for time-dependent data, and also because of the complexity of processing any such data within SPICE, the SPICE system provides no numerical mechanisms for managing accuracy information. The only provision for dealing with accuracy information in SPICE is the ability of each kernel type to contain text "comments" (meta-data) provided by the kernel producer that state whatever that producer feels is relevant about the accuracy of data that may be extracted from the kernel. The user of the kernel can see (read) any such comments and decide what if anything to do with that information. That said, because it is often difficult for a kernel producer to confidently determine the accuracy of source data, it is rare that useful accuracy information is placed in a kernel.

Please Share Your Opinion

The NAIF Team encourages SPICE users to comment on the SPICE system. If you like what you've received, let us know. If some part of the system fails, or performs in an unexpected manner, tell us that too.

If you have ideas for improvements or enhancements, we'd like to hear about them. With the support and suggestions of users, the SPICE system will continue as a valuable resource for the space science community for decades to come.

Stay Connected

If you wish to keep well informed about SPICE related news, consider signing up with the spice_announce Mailman system.