Introduction to SPICE





   NAIF
 
   May 2003 (EDW)


Welcome...




Welcome to SPICE, a NAIF (The Navigation and Ancillary Information Facility at JPL) developed software system that provides the capability to easily combine accurate space geometry and event data with your mission analysis, observation planning, or science data processing software.

Since its introduction, SPICE earned wide acceptance for organizing, distributing, and accessing both space geometry and mission event data. As you move on from your current investigations to other planetary science studies, SPICE can likely assist you with these new endeavors.

The SPICE system supports the following platforms/compilers:

The principal SPICE product---the SPICE Toolkit---consists of software coded in either ANSI FORTRAN 77 or ANSI C, a documentation suite, and example data. The software set comprises source code for various libraries and Toolkit based applications. Due to NAIF's use of ANSI standard code, SPICE easily ports to environments that support either language.

This overview guides you through the Toolkit's various components and identifies more extensive documentation.



Quality and Stability




We at NAIF are committed to providing a robust, flexible, and understandable product that suits the needs of the space sciences community. All SPICE Toolkit software undergoes careful review and testing; the documentation for the SPICE software is extensive and accurate.

To further enhance the SPICE user experience, NAIF encourages users to comment on the product. Such comments can range from bug reports to requests for new functionality.

In addition to listening to users' comments, NAIF uses the product in support of JPL flight projects. With such practical experience, we understand the perspective and future needs of the novice working to learn SPICE.

The SPICE system is a continual work in progress. However, NAIF is equally committed to providing SPICE users a consistent product. We understand the frustrations of learning a programming system only to have it change in unanticipated ways. Therefore, we never change the intended functionality of, or the interface to, released software and data products. If you build a program using today's SPICE system, it will work the same way when you re-build it with tomorrow's SPICE system. Our motto "Once SPICE, always SPICE."



CSPICE




NAIF developed a pure ANSI C version of the SPICE Toolkit named ``CSPICE'' to present C programmers a natural C-style interface to the FORTRAN SPICE Toolkit's functionality. (The term SPICE is more general and refers to either the FORTRAN or C systems.)

First released in May 1999, NAIF subjected CSPICE to an elaborate testing process, but lacks the benefit of extensive, sustained testing by practical use. In contrast, various NASA flight projects have used the FORTRAN Toolkit since 1990.

NAIF delivers the CSPICE Toolkit as a distinct product from the FORTRAN SPICE Toolkit; NAIF does not deliver intermixed versions of these products.

The cspice.req ``Required Reading'' document, included in the CSPICE Toolkit, provides a detailed description of the product.



The Interactive Data Language (IDL)




The advent of the CSPICE extension to the SPICE system presented NAIF the opportunity to create an interface named ``Icy'' between the IDL environment and CSPICE. Currently available in Beta-test status and to be formally released in 2004, Icy provides access to the CSPICE vector math, SPICE file read/write and data evaluation routines (among others).

The Icy distribution consists of a superset of the CSPICE distribution containing CSPICE plus the IDL/CSPICE interface code, Icy API html documentation, CSPICE API html documentation, and the Icy programming guide.



Introduction to SPICE Kernels




SPICE stores data in specialized files named ``kernels''. A kernel may store data in either ASCII text or binary formats.

Text kernels are interpreted as simply a string of ASCII characters with special markers to indicate data assignments. Caution, a text file contains operating system specific line terminators. Reading a file containing the wrong terminators for your operating system may produce useless results.

Binary kernels on the other hand have more specialized organization. They typically contain numeric and textual information. The numeric information is stored in the binary format used by your computer instead of a form easily read by people.

The binary kernels set consists of:

The binary kernels are often delivered in the SPICE ``transfer format'', an ASCII text file easlily transported between computers. You must convert such files to your computer's binary format using either the tobin or spacit utility program delivered with the Toolkit.

The set of text kernels consists of:

These can be used as received - no conversion is needed.

The C and FORTRAN Toolkits use the same kernel files on the same architecture platform.

Both types of kernels (text and binary) must be read to be useful. The SPICE system provides software for reading (and in some cases writing) these kernels. Still, you can use these kernels without ever concerning yourself with the details of their format.

To make the information in kernels available to your software you will need to load them. This lets the SPICE system know where to find these data. Loading text kernels is discussed in the document kernels.req. Loading SP-kernels, C-kernels, and PC-kernels is discussed in the documents spk.req, ck.req, and pck.req respectively. Moreover examples of loading kernels are provided in the cookbook programs provided with SPICE (see the section on Example Programs below). Kernels of all types need to be loaded only once in your program - no need to embed the load statement in a loop.



Native/Non-native Kernels



As mentioned, several SPICE kernel types store numeric data in binary format. Unfortunately, hardware architecture (the CPU chip) determines the format of numeric binary data. The two most common formats are IEEE standard big endian and non-IEEE standard little endian.

To accommodate those users who require the use of kernels across multiple computing architectures, SPICE software can read non-native binary kernels on most platforms (not including VAX/VMS).



Installation




Your first step to join the SPICE user community is to install a Toolkit delivery onto your computer. An installation nominally requires nothing more than executing a script or command procedure (provided with your SPICE package) to unpack the SPICE directory system. A Toolkit delivery usually includes precompiled executables and libraries.

Should you want or need to rebuild the executables and libraries, a script exists for that task.

The time required for a rebuild varies with the speed of your computer and its FORTRAN or C compiler. On most systems, a rebuild process lasts less than thirty minutes.



Toolkit Contents




Once you install the SPICE system on your computer, consult the document dscriptn.txt for a description of the directory structure created by the installation process and the contents of the various directories.

A toolkit delivery is a collection of files segregated by category: documentation, source code, make or link procedures, and some sample data.

Documentation is stored in the doc subdirectory of the main toolkit directory. These files include user's guides for the various applications, index information, and discussion of related collections of routines that make up the SPICELIB or CSPICE libraries.

Documentation on the design and function of a particular subroutine is found in the source code for the routine. All subroutines contain an extensive comment block called a ``header'' that appears at the beginning of the source file.

The main component of all Toolkit deliveries, regardless of target language, is the code library, SPICELIB in the FORTRAN delivery and CSPICE in the C. The source files in these libraries compile to object libraries, spicelib.a (FORTRAN) and cspice.a (C) stored in the ``lib'' subdirectory. You link against these libraries when creating your own programs. Other object files are linked with SPICELIB or CSPICE to create the application tools included in the SPICE system.

Sample data files make up the remaining files. Some of these (LSK and PCK) can be used as you receive them. Others must be converted from transfer to binary format before you can use them with Toolkit software; these are the ephemeris (SPK), attitude (CK) and spacecraft events (EK) information files. The conversion programs used for converting these files are called spacit, tobin and toxfr. They are provided with the SPICE system and their executable modules are located under the exe subdirectory. They are discussed briefly in the TOOLS section below and are documented in the spacit.ug and convert.ug User's Guide documents that come with SPICE.

The following discussion of delivery contents refers to either the FORTRAN or C SPICE Toolkits. The installation trees for these Toolkits are always disjoint: the directories discussed will contain FORTRAN or C products but not both.



Using SPICE




Practical use of the SPICE system requires (at a minimum):

You will need to be familiar with using your computer's editor, compiler, and linker. Familiarity with a debugger can also be helpful as you develop your application program. Finally, you will need to know how to execute a program on your computer.

In future releases of the SPICE system, NAIF intends to provide documentation describing the development of SPICE-based applications in the various computing environments for which we actively support the SPICE system. But for now, if any of these topics (editing, compiling or linking) are not clear to you, try examining the routines used by the installation procedure to build the various SPICE applications. For example, examine the procedure mkprodct (or mkspacit on some computer platforms) located in the source code directory for SPACIT (see dscriptn.txt to locate this directory). If this example fails to answer any questions, NAIF recommends you consult a colleague or your system administrator to find out the details of program development on your computer.



Trilingual Programming




If you ``speak'' FORTRAN, C or IDL, then you're ready to program. However, you might need to code in another language (for example Java or Visual Basic) and still use SPICE routines. Caution, cross language linking is notoriously tricky. Matrices, strings, and other data types may be organized differently in your language of choice from the way they are organized in FORTRAN or C.

If you choose this path you will need to find out how your language of choice supports calls to FORTRAN or C object modules. Your best source of information will be a colleague who has already mastered this art. There may be a programmer's reference manual that describes cross-language syntax. In addition, you may be able to receive support from the company that supplies the language you choose for writing your software.



Creating or Modifying Kernels




Most SPICE users will not need to create or modify kernels. Moreover, of the users who need to create or modify kernels, most will only need to deal with one of the various text kernels. Because these are text files they can be created and modified with any text editor. Although the format of these files is fairly easy to deduce, we recommend you consult the document kernel.req before you attempt to edit a text kernel for the first time.

Some SPICE users will want to create binary kernels. This task requires a deeper understanding of the SPICE kernel format and kernel readers. If you need to create SPICE binary kernels we recommend you read all of the material in the one of spk.req, ck.req, pck.req or ek.req pertinent to your task. In addition, if you are producing these data products in an official project capacity we encourage you to contact NAIF to discuss any issues that might be relevant to your task of producing binary kernels.



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



Programming Examples




We often learn new ideas best by seeing examples of their use. For this reason SPICE comes with a collection of simple example programs called the SPICE Cookbook, located under the cookbook subdirectory. These sample programs show in a few pages how to load various kernel files, how to call the kernel readers and how to perform common geometric and time computations. Most users find these to be very valuable in getting started with the SPICE system. We recommend you look at the Cookbook early to help you get an idea of how easily you can begin programming using SPICE.



Tools




Toolkit distributions include several utility programs to assist you with using SPICE. These programs are:

SPACIT

Used to convert binary format kernels to a ``transfer'' format (and vice-versa) for porting between different environments. Also used for summarizing the contents of binary kernels. (See the SPACIT User's Guide.)
INSPEKT

Used for examining the contents of binary EK kernels. (See the INSPEKT User's Guide. This is available only as a printed document or PostScript file.)
TOBIN

Used to convert transfer format kernels to a binary format using a simple command line interface. (See the CONVERT User's Guide.)
TOXFR

Used to convert binary format kernels to a transfer format using a simple command line interface. (See the CONVERT User's Guide.)
COMMNT

Used to provide internal documentation in binary kernels. (See the COMMNT User's Guide.)
The executable modules of these programs are located in the exe subdirectory of the Toolkit's main directory.



Concepts and Terminology




The SPICE system is very much concerned with concepts of geometry and time. The planetary science community uses several different time and coordinate systems when describing geometry and time. Within the context of a single planetary mission, one does not often need to be concerned with the details of these systems. Project management simply dictates a common system to be used for all software and data products. However, the scope of the SPICE system spans many planetary missions and terrestrial based investigations. As a result, you will need to pay more careful attention to the details of the various measurement systems.

SPICE includes mechanisms for converting between different time systems such as UTC, JED, TDB and Spacecraft Clock. SPICE also provides conversions between various inertial reference frames such as J2000, B1950, EME50, and non-inertial frames such as body-fixed frames.

Additional detailed information available in:



Better Programming




The SPICE system is much more than kernels and kernel readers. Over half the Toolkit's routines perform functions designed to ease the process of building software. Those familiar with the standard C library will find a find a parallel between some SPICE FORTRAN routines and standard C functions. A subset of the text and file manipulation capabilities inherent to the Perl language are also integrated into the SPICELIB and CSPICE libraries.

Use of the Toolkit for more than simple data acquisition and analysis means you can often produce software more robust, and in less time than similar software developed without using Toolkit routines. There are some obvious reasons for this. You don't have to write the software that duplicates Toolkit functions. Toolkit software has already undergone careful testing. The action of Toolkit software is carefully specified. In addition, you benefit from a centralized error handling facility integrated with Toolkit software.

To find out more about the various features of the Toolkit, consult the following documents found in the doc subdirectory:

Also examine the following documents. These are included in both the FORTRAN and CSPICE Toolkits but have not been converted from FORTRAN to C style for CSPICE:



Finding the right routine




The real programming power of SPICE derives from the extensive set of built in capabilities you need not re-invent. However, since SPICE contains over 1100 routines, reading all the routine headers is not a practical way to locate the appropriate routine for a given task. If you can classify the function you need as belonging to one of the categories listed in the previous section, then you can consult one of the listed documents. However, there many routines in SPICE don't fit into one of the categories. (For example, the Toolkit contains over forty routines for performing vector-matrix arithmetic.) With this indexing problem in mind, we have provided additional documents to help you quickly locate the proper routine for the task.

The documents spicelib.idx and cspice.idx provide a permuted index to all of the routines in SPICELIB or CSPICE respectively. Like the index to a reference work, this helps you find the right routine for a specific task. Moreover, the index is permuted. Thus, the word you think of as an index to a routine has a much greater chance of 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 point to the SPICELIB subroutine VCRSS, or the CSPICE function vcrss_c, that computes a cross product.



What to do when you have a problem




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

All Toolkit distributions include a document named ``problems.txt'' in the doc directory. 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 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 manager. (s)he may be able to assist you. NAIF can provide little more than sympathy with regards to such situations.

If you use a SPICE based product developed by someone else, contact the developer for assistance.

If your program executes but your output disagrees with those of a colleague who ran the same program with identical inputs, ensure you both use 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 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 within our resources to help.



Please share your opinions




The NAIF Team encourages all SPICE users to comment on the SPICE system. If you like what you've so far 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.