Failure is not an option. -- "Apollo 13"
Initial release.
While NAIF strives to make correct use of SPICE an effortless
experience, more remains to be done. NAIF's decade of experience with
SPICE customers has shown that certain problems seem to recur fairly
regularly. This document aims to assist you in preventing these
problems, or if necessary, troubleshooting them.
Most of this document is concerned with matching symptoms to possible causes and solutions. However, before starting to write a SPICE-based application, we strongly encourage you to consider the steps necessary to avoid problems.
It's generally much easier and quicker to make sure you're doing
things right in the first place than it is to explain why your program
isn't behaving as expected. For best results, carefully ascertain that
you have the proper input data and problem definition before
proceeding.
One of the most frequently occurring user-support questions fielded by NAIF is basically ``I compared my results from SPICE with [an alternate source], and they disagree. Why?'' The answer usually is that the two computations are for some unintended reason solving different problems.
Here's a checklist of things to get right before embarking on solving a problem with SPICE, or comparing SPICE results with those obtained from alternate sources.
The functional areas are listed alphabetically.
While for general applications, SPICE is usually capable of much
higher accuracy than required, for some specialized applications such
as radio science, certain SPICE-based computations may not be
sufficiently accurate.
Within the SPICE system TDB times are represented as double precision
numbers, and these are not generally accurate to better than 1.E-7
second.
This problem to date has proved illusory.
State vectors obtained from SPK files have been tested and shown to agree with those obtained from the parent NAVIO files to levels orders of magnitude below the knowledge error in the data. The differences in state vectors returned by the two systems tend to reflect round-off level differences in the handling of time.
This is not truly a common problem; it has arisen only in the context
of radio science applications.
The UTC-TDB conversion in SPICE is accurate to about 4.E-5 seconds.
Versions of the SPICE Toolkit released prior to May, 1995 used an
unnecessarily inaccurate light time computation: they returned the
distance between the geometric positions of observer and target at the
request time, divided by the speed of light. Later versions of SPICE
use the position of the target evaluated at the light-time corrected
epoch.
Be aware that SPICE aberration corrections do not account for relativistic effects.
Make sure you're using the correct ID code for the body.
Check that your kernel file has data for the body in question for the epoch of interest. If you're using a text PCK, this problem occurs because data is simply absent for the body in question.
Binary PCK files have coverage for limited time spans. Make sure the request time falls within the coverage interval for the body if a binary PCK is used. The available coverage may be ascertained by summarizing the PCK file with SPACIT.
If the rotation of the body is retarded by one-way light time, remember that PCK data for the body must be available at the light-time corrected epoch.
Rotational models for extended bodies vary. For any given body, the
model and model parameter values may evolve over time, so verify that
the version you're using is correct.
Some bodies have rotational models based on different physical attributes, for example rotation of the magnetic field or rotation of the atmosphere. Verify that the model you expect is provided by the PCK file you're using.
The epoch at which the target body's orientation should be evaluated depends on whether the actual or apparent orientation of the body is to be computed. Check whether the request epoch should be adjusted for light time.
All of the considerations listed above apply.
Additionally, note that velocity transformations involve the time derivative of the inertial-to-bodyfixed transformation. If P and V are inertially-referenced position and velocity vectors, M is the inertial-to-bodyfixed transformation matrix, and P_b and V_b are the body-fixed position and velocity, then we have (by the Chain Rule for derivatives):
P_b = M*P V_b = M*V + (dM/dt)*PSome applications external to SPICE erroneously ignore the second term in the second equation.
Use CKBRIEF or SPACIT to summarize the kernel. Depending on your
computer system, you may need to log the output to a file to view it
conveniently.
C-kernel data are contained in a series of one or more chunks called ``segments.'' SPACIT will output a series of summaries, one for each segment. SPACIT will tell you what instrument the pointing data is for, which base frame the pointing is referenced to, whether angular velocity data are also present in the segment, and the data type (internal representation) of the segment. The time bounds of each segment are also shown.
CKBRIEF is a more flexible and robust summary program than SPACIT; you normally will find CKBRIEF more convenient to use. However, the current version of CKBRIEF does not output the data types of segments.
Check that the ID code you're supplying to the CK reader matches that
in the C-kernel. If you're interested in pointing for a spacecraft
instrument, you may need to get pointing for another entity, usually
the spacecraft bus or a scan platform, then apply pointing offsets
from a Frame kernel or Instrument kernel to obtain instrument
pointing.
If the ID code is correct, it may be that the tolerance value supplied to the C-kernel reader routine, either CKGP or CKGPAV, should be increased. By increasing the tolerance value you supply to the CK reader called in your application, you may be able to pick up pointing at a nearby time sufficiently close to your time of interest.
There may be no nearby pointing due to coverage gaps in the C-kernel, either between segments or in the interior of some segment. C-kernel segments, unlike SPK segments, do not necessarily have continuous coverage. In fact, type 1 C-kernels contain discrete pointing and do not yield interpolated pointing. C-kernel data types 2-4 have coverage over a series of time intervals, but there may be gaps between the intervals.
Finally, you may be using the wrong reader. The reader CKGPAV will indicate that no pointing was found at your request time if no pointing that carries associated angular velocity data was found. If you're using a C-kernel that doesn't contain angular velocity, you should use CKGP instead. CKGP doesn't expect angular velocity to be present.
The choice of lookup tolerance can be a complex issue involving
trade-offs between accuracy and completing as much data processing as
possible. Choosing a non-zero tolerance means accepting pointing for a
time other than your time of interest. What magnitude of inaccuracy is
introduced by this choice? It depends on how much the structure of
interest can or did move during the tolerance interval. Knowledge of
the spacecraft or structure dynamics may be required to select the
maximum acceptable tolerance. This may vary depending on mission
phase, ACS (attitude control system) state, the specific structure for
which pointing is desired, or other time-dependent factors.
There are a few cases that do admit simple guidelines:
If you're using a type 1 C-kernel (discrete pointing), the tolerance should normally be at least half the nominal spacing between the pointing instances. Otherwise, no pointing will be found at request times near the midpoints between times where pointing is available.
If you're using a C-kernel of type 2, 3, or 4, and you know that the data does not suffer from gaps, you may use a tolerance of zero. This choice guarantees that you'll get pointing interpolated to your request time. A tolerance of zero is frequently acceptable when using predict pointing, which normally should not have any coverage anomalies.
See ``Quaternions'' below.
See ``Body-Fixed Frames'' above.
If the Cartesian body-fixed coordinates of a point are as expected, latitude and longitude may differ because of
Use the SPICE permuted index in the /doc subdirectory of your SPICE
Toolkit installation. The permuted index associates short functional
descriptions with names of SPICELIB functions. You can browse this
document or search/grep it for keywords.
Only a small fraction of the routines in SPICELIB tend to be called directly from users' applications. To familiarize yourself with this subset of routines, look at the document ``Most Used Subroutines'' in the /doc directory of your SPICE Toolkit installation.
To quickly get up to speed in using the elementary features of SPICE, examine the cookbook programs in the
/src/cookbooksubdirectory of your SPICE installation.
For help in understanding how SPICE routines are combined to solve more involved problems, examine the code examples in the Required Reading files in the /doc subdirectory of your Toolkit.
For queries that do not involve ordering the output, this sometimes
happens because inadequate constraints were supplied. Queries on large
databases should employ a WHERE clause to restrict to a manageable
size the set of matching rows. A typical example of a query generating
a huge number of matching rows would be an attempted equi-join with
the equi-join constraint accidentally omitted.
For queries involving ordering on a single column, generating more than 50000 matching rows will guarantee a long wait, because at that point scratch files will be used to store temporary results.
Queries involving multiple order-by columns are typically slow because scratch files are used when comparisons are required on columns other than the primary order-by column.
Use the ``fast loader'' routines, which are roughly two orders of
magnitude faster than the record-oriented writers. See the header of
EKIFLD (EK, initiate fast load) for an example.
Because of the complexity of the EK system, errors in application
calls to EK routines are sometimes diagnosed at locations very remote
from the original error. Mismatched arguments in subroutine calls are
the typical root cause of these error messages.
The default error handling response is to abort the application. This
response can be changed so that SPICE routines return on entry. See
the Error Required Reading or the routine ERRACT.
The target file for SPICE error messages can be reset. See the Error
Required Reading or the routine ERRDEV.
If your application directly calls CHKIN and CHKOUT, unpaired calls to
these routines may result in this error message. Due to recursion
restrictions in Fortran, this message does not pass through the normal
SPICE error handling mechanism.
The set of SPICE error messages can be re-configured. Any type of
message (long, short, traceback, default) can be suppressed. See the
Error Required Reading document or the routine ERRPRT.
Generally, Euler angles are unique only when their ranges are
appropriately restricted. Otherwise, there are usually multiple
combinations of angles that map to the same rotation matrix.
Review the headers of M2EUL or XF2EUL carefully to determine what output ranges are used.
Attempts to open a file for read access will fail if that file does
not exist.
Attempts to open a new file will normally fail if that file exists.
Any open attempt will fail if the application attempting the operation does not have permission to access the file.
SPICE utilities and some SPICELIB routines use scratch files. Scratch files are sometimes kept in locations other than the user's current or home directory. If permission to write to the scratch directory is not granted, a write error will occur.
SPICE kernel loader routines attempt to diagnose and report errors when used to open inappropriate kernel types.
Read errors can occur when a file is corrupted. They also can occur
when a file is deleted while a SPICE application is attempting a read.
Logical unit conflicts can cause nonsense data to be returned when reading SPICE kernels. The symptoms can be obscure. See below.
Logical unit conflicts are peculiar to Fortran applications. However,
they may occur in C applications that link to both CSPICE and other C
code generated by running f2c on Fortran source code.
The SPICE kernel loaders allocate logical units at run time. SPICE does not allocate logical units that are currently in use.
If a user application loads kernels or otherwise performs actions that cause SPICE to allocate logical units, and then uses those same logical units for its own I/O operations, a logical unit conflict exists. SPICE will then attempt to read from whatever file the application has connected to the logical units SPICE had allocated. This will typically result in SPICE reading something other than valid kernel data.
There are a couple of simple solutions. First, if an application is known to use a particular set of units, you can tell SPICE not to touch those units by calling RESLUN.
If you are writing a new application, it may be convenient to use GETLUN to allocate logical units at run time. This avoids hard-coded logical units, which may cause portability and integration problems.
The SPICE DAS system, which underlies the EK system, requires a
scratch file for sorting when a newly written file is closed.
Attempting to open this file could cause a system limit on open files
or logical units to be encountered, resulting in a file open error.
If the application does not have permission to open the scratch file, an error will be signaled. See also ``File I/O.''
If the scratch file is opened successfully, it is possible that disk space will be exhausted while writing to the file. This will result in a write error.
Usually this problem is caused by accidentally performing an ftp
transfer in binary mode. Binary ftp transfers of text files can be
expected to work only if the transfer is between systems having
identical text file formats.
It is also possible that the file was corrupted in transfer due to running out of disk space on the target system during the transfer.
If the file being transferred is a NAIF ``transfer format'' version of a binary kernel, corruption of the file often can be diagnosed by TOBIN during an attempt to convert the file back to binary format on the target system.
If the file was transferred between two systems with compatible binary
file formats, for example, between HP and Sun workstations, the
problem may be due to accidentally having transferred the file in
ASCII rather than binary ftp mode.
Also, it is possible that disk space was exhausted on the target system during the transfer.
If the file was transferred between two systems with incompatible binary file formats, for example an HP workstation and a PC, the problem is that binary kernels on one system are not designed to work on the other. The kernel must be converted to transfer format on the source system, the transfer format file must be transferred in ASCII mode, and the received transfer file must be converted back to binary format on the target system. Use TOXFR and TOBIN, respectively, to perform conversions from binary to transfer format and from transfer format to binary format. The utility SPACIT is also capable of performing these conversions. See the User's Guides for any of these utilities for further information.
First, the Fortran compiler must be capable of being invoked from the
command line in the directory where the installation is done.
On some systems, the compiler may not be installed, or libraries required by the compiler may not be available.
If your application cannot link against SPICELIB, or it links but does not run, there may be a compiler or system library version incompatibility. This problem can occur if you have installed the SPICELIB library simply by unpacking a delivery tar file, and there is a discrepancy between the version of your compiler and that used to create the object modules in the delivery tar file. This problem may be solved by doing a complete build of the SPICE Toolkit on your system. See the installation instructions for details.
In general, if you have difficulty building the SPICE Toolkit, it may be a useful test to see whether you can build a simple ``hello world'' program in the same environment. If that test fails, it's time to consult with your system administrator.
Allocate as much memory to the MPW application as possible during
compilation. Use virtual memory if available. The NAIF development Mac
normally is allowed 64 megs of which 20 is used by MPW when building
the library. The Toolkit application program Inspekt requires most of
the 20 megs when compiling.
Increase the amount of memory available to the program. Mac programs
which use the SPICELIB library programs need a considerable amount of
memory to run, especially Inspekt. 2 megs should be considered a
minimum.
The general-dimension matrix and vector routines, unlike their
3-dimensional counterparts, usually do not permit overwriting input
arguments with output values. Check the subroutine headers for
details.
PCK kernels supplied by NAIF normally contain data intended for use by
a general class of users. PCK kernels are text files and can be
edited, so you can easily customize an existing one, deleting
unnecessary data, adding new data, or changing existing values.
If you modify a kernel supplied by NAIF, it's a good idea to comment the file so as to make clear what changes were made. All NAIF text kernels allow comments to be inserted. See Kernel Required Reading for further information on the NAIF text kernel format.
The SPICELIB PCK system supports binary PCK files that are capable of
supporting high-accuracy rotation models. Currently NAIF has the
capability of producing high-accuracy PCK files for the earth; these
take into account precession, nutation, TAI-UT1, polar motion, and
nutation corrections.
NAIF is also developing the capability of producing high-accuracy PCK files for the moon.
Loading kernel files in a loop causes slow execution. Normally, kernel
files should be loaded once per program run, usually during
initialization.
Two possible ``global'' improvements are using compiler optimization and disabling SPICELIB call tracing.
The Fortran library SPICELIB is normally built without using compiler optimization. On some systems, in particular Sun Sparc machines running Sun Fortran, using optimization has resulted in some code generation errors. NAIF is working to resolve this problem. CSPICE on the other hand is always built using compiler optimization. If you have the opportunity to use either library, using CSPICE may result in a considerable speed-up.
SPICELIB applications can be speed up somewhat by disabling the routine call tracing done internally by SPICELIB. This is done by calling TRCOFF once during program initialization:
CALL TRCOFFNormally it is desirable to retain SPICELIB's call tracing while an application is still being debugged. See Error Required Reading or the header of TRCOFF (located in the umbrella routine trcpkg) for further information.
It's also possible to achieve speed gains via local code modifications. Before trying this, it's a good idea to profile your application to locate bottlenecks.
Often it's possible to re-organize your SPICE calls so as to minimize the number of expensive operations. There is usually a speed/complexity trade-off to consider when making such changes. For example, if you're computing a large number of geometric quantities that all require the same spacecraft-to-target state vector, and each quantity is computed by a separate routine, you may want to compute the state vector once and pass it into the geometry routines.
Sometimes speed gains can be achieved by calling lower-level SPICELIB routines. For example, if you're computing the apparent states of many targets as seen from a single observer at a given epoch, rather than using the high-level reader SPKEZR, you can look up the observer state relative to the solar system barycenter via SPKSSB, then separately look up each apparent target state relative to the solar system barycenter via SPKAPP. This eliminates redundant computations of the observer's state.
There are two styles of quaternions in common use. The NAIF style is
in common use by mathematicians and physicists; the alternate style is
in common use throughout JPL and elsewhere in the aerospace
engineering community.
NAIF style quaternions are related to rotations as follows: if a rotation transformation rotates a vector V in the right-handed sense about an axis
A = (a1, a2, a3)by an angle of theta radians, then the NAIF quaternion representing this rotation is
( cos(theta/2), sin(theta/2)a1, sin(theta/2)a2, sin(theta/2)a3 )A NAIF quaternion
( q0, q1, q2, q3 )can be transformed to the alternate style
( q0', q1', q2', q3' )by the equations
q0' = -q1 q1' = -q2 q2' = -q3 q3' = q0These equations also indicate how to transform the alternate quaternion style to the NAIF style.
The formulas for conversion between quaternions and matrices depend on
the quaternion style in use. See the section above.
See discussion of reference frames in ``Getting it Right.''
See ``Body-Fixed Frames.''
NAIF cannot change the names of routines in its published interfaces.
However, NAIF can supply on request a special version of a library
having special suffixed or prefixed names that are unlikely to collide
with names used elsewhere.
No mechanisms to ensure threadsafe behavior exist in standard ANSI C
or Fortran 77. NAIF has no plans to use non-standard features in
SPICELIB.
See ``Error Handling.''
Use the SPICE utility program BRIEF to summarize the SPK file.
Good question. SPICE does not currently contain routines that provide
a convenient answer.
It is possible to examine loaded kernels at run time to determine their coverage. This is done via the DAF search routines. See the DAF Required Reading, or the headers of DAFBFS, DAFBBS, DAFFNA, DAFFPA, DAFGS, and DAFUS.
The most common reason for this is that the user neglected to load a
necessary SPK file.
Computation of aberration-corrected states requires that sufficient data be available to compute the observer and target states relative to the solar system barycenter. The target state must be computable over the interval from the request time back to the request time minus one-way light-time. So don't request an aberration-corrected state at or near the coverage start time of an SPK file.
SPK coverage boundaries shown by SPACIT are approximate.
Also, if aberration corrections are used, state requests will result in look-ups of the target state for epochs prior to the request time. See ``SPICE(SPKINSUFFDATA) error is signaled'' above.
If multiple SPK files contain ``competing'' data, that is redundant
ephemeris data for a given body, center and time, then the SPK system
selects the data based on the order in which the competing files were
loaded, with files loaded last taking precedence.
Varying the order in which the files were loaded can affect the state vectors returned by the SPK system.
Of course, any change in the set of kernels used may affect results computed by the SPICE system.
See ``Body-Fixed Frames.''
The file may be corrupted. See ``File Transfer.''
Conversion of a single state to osculating elements does not yield
mean elements.
For some orbits, some elements are not easily recovered from state vectors. For example, argument of periapsis cannot be determined for a circular orbit.
Check that the central mass is valid.
See ``Accuracy.''
Note that system barycenter locations change as mass estimates change.
The solar system barycenter is very sensitive to mass estimates for the outer planetary systems. Therefore, state vectors of bodies relative to the solar system barycenter cannot be expected to compare well across planetary SPK files based on different integrations (having different underlying planetary ephemerides).
SPICE attempts to catch errors before they result in system-level
exceptions. Some types of errors are beyond SPICE's ability to
intercept.
Often due to missing data or uninitialized variables.
May be due to inconsistent input arguments supplied to SPICE routines.
However, SPICE generally has no graceful way of determining that it's
writing beyond the bounds of an array passed in by an application.
Often caused by mismatched argument lists. Applications must supply
arguments that match in data type and dimension with those expected by
SPICE routines.
Sometimes this error results from a constant actual argument being supplied where an output argument is expected.
When this error occurs on a Unix system immediately upon program execution, the cause may be that the user stack is too small. See the Unix ``limit'' man page.
Usually caused by invalid input data.
SPICE does not attempt to detect or prevent underflow.
Possible causes:
Note that TDB and UTC advance at different rates. UTC times that are
10 seconds apart are not 10 TDB seconds apart.
The problem may be solved by converting times to TDT in order to perform stepping. UTC may be converted to TDT by first calling STR2ET to produce TDB, then calling UNITIM to convert TDB to TDT. Also, be sure to account for round-off in the loop termination test.
SPICE supports an enormous variety of input and output formats. See
the Time Required Reading and the headers of the routines STR2ET and
TIMOUT.
Possible causes:
Possible causes:
Some SCLK string formats look like floating point constants. It's easy
to mistake the least significant SCLK field for a decimal fraction;
that interpretation is usually not correct. See SCLK Required Reading
for a discussion of SCLK strings.