Index Page
Common Problems

Table of Contents


   Common Problems
      Abstract
      Introduction
      Getting it Right

   Problems by Functional Area
      Accuracy
         Problem: Arithmetic on time values yields incorrect results
         Problem: States from the SPK and NAVIO systems are not identical
         Problem: UTC-TDB conversion in SPICE does not appear accurate
         Problem: Light time corrections in SPICE seem to be inaccurate
      Body-Fixed Frames
         Problem: Inertial/Bodyfixed position conversion gives SPICE error
         Problem: Inertial/Bodyfixed position conversion is incorrect
         Problem: Inertial/Body-fixed state conversion is incorrect
      CK/C-Kernel/C-Matrix/Pointing
         Problem: How does one determine the attributes of a C-kernel?
         Problem: no pointing found at desired epoch
         Problem: unclear what lookup tolerance to use
         Problem: SPICE quaternions appear invalid
      Coordinates
         Problem: SPICE does not produce expected lat/lon values
      Documentation
         Problem: ``I can't find the function I need''
      E-kernel
         Problem: Query takes forever to complete
         Problem: Writing EK file takes forever
         Problem: EK routines signal very mysterious errors
      Error Handling
         Problem: SPICE errors abort my application program
         Problem: SPICE error messages are written to standard output
         Problem: SPICE(NAMESDONOTMATCH) error is displayed
         Problem: ``Oh, by the way...'' message is annoying
         Problem: SPICE errors are not written to stderr
      Euler Angles
         Problem: m2eul_c or xf2eul_c don't produce the expected angles
      File I/O
         Problem: File open error is signaled from SPICE-based utility
         Problem: SPICE kernel reads fail within user's application
         Problem: Logical unit conflict
         Problem: Error occurs when trying to close EK or DAS file
      File Transfer
         Problem: A text kernel causes a SPICE(INCOMPATIBLEEOL) error
         Problem: binary kernel imported from a second system does not work
      Installing the SPICE Toolkit
         Problem: SPICE routines don't compile, link, or run
      Linear Algebra
         Problem: Bogus results returned by general-dimension functions
      PCK/Pc-Kernel/Planetary constants
         Problem: PCK file does not contain desired contents
         Problem: Earth orientation given by a text PCK is too inaccurate
      Performance
         Problem: SPICE-based application is too slow
      Quaternions
         Problem: NAIF quaternions appear incorrect
         NAIF matrix--quaternion conversion appears incorrect
      Reference frames
         Problem: EME50 vectors from SPICE appear incorrect
         Problem: Vectors in body-fixed frame appear incorrect
      Software Application Integration
         Problem: SPICE function names conflict with application's names
         Problem: SPICE code is not thread safe.
         Problem: Application requires SPICE error output to be trapped
      SPK/Ephemeris/States
         Problem: How can I interactively determine the coverage of an SPK?
         Problem: Can't determine what states are computable from SPK files
         Problem: SPICE(SPKINSUFFDATA) error is signaled
         Problem: no data found for times near SPK endpoints
         Problem: states vary over different program runs
         Problem: Velocity in rotating frame is incorrect
         Problem: SPK file contains clearly invalid data
         Problem: Osculating elements are wrong
         Problem: Aberration-corrected states are not as expected
         Problem: System barycenter-relative states are inconsistent
      System errors
         Problem: divide by zero
         Problem: subscript out of range
         Problem: segmentation fault/memory access violation
         Problem: arithmetic overflow
         Problem: arithmetic underflow
      Time
         Problem: SPICE conversion between ET and UTC is incorrect
         Problem: Stepping from start UTC to end UTC in loop fails
         Problem: SPICE time strings do not have the desired format
         Problem: conversion between ET and SCLK fails
         Problem: conversion of SCLK string to encoded SCLK fails
         Problem: SCLK string is misinterpreted
      Icy
         Problem: IDL segmentation fault

   Appendix A: Revisions
      2017 MAR 14 by E. D. Wright
      2007 FEB 11 by E. D. Wright
      2006 NOV 22 by B. V. Semenov.




Top

Common Problems





   Failure is not an option.
 
    -- "Apollo 13"
Last revised on 2017 MAR 14 by E. D. Wright



Top

Abstract




Descriptions of the more commonly encountered SPICE problems, broken down into functional areas with suggestions on how to avoid problems.



Top

Introduction




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



Top

Getting it Right




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

    1. Read the directions: read the relevant SPICE documentation, both function headers and Required Reading files. SPICE software interfaces aspire to be intuitively clear, but may fall short.

    2. Understand the definitions: many geometric quantities have a variety of definitions. For example, there are a variety of ways of computing a sub-observer point, involving both different applications of light time corrections and different definitions of ``sub-point'' (closest point to the observer vs. surface intercept of observer-target center vector).

    3. Understand the expected accuracy and precision: for example, the Astronomical Almanac frequently presents results having claimed accuracy of 0.01 degree. These cannot be expected to agree with SPICE results at the arcsecond level. On the other hand, if your application requires extraordinarily high accuracy, you may need to check whether SPICE meets your requirements.

    4. Use the right files: this is probably the single most frequent cause of disagreements. You MUST use the same ephemeris, rotational elements, shape models, pointing, instrument models, frame definitions, leapseconds, spacecraft clock coefficients, and so forth if you're attempting to match results from alternative computations.

    5. Use the right time: another major cause of disagreements. Is the input time supposed to be UTC, ``ET'' or TDB (barycentric dynamical time), TDT (terrestrial dynamical time), TAI, etc.? Frequently calendar dates and Julian dates are written down without specification of whether they're UTC or TDB, even though the distinction is critical for high-accuracy work.

    In order for SPICE-based time conversions to be correct, current leapseconds and/or SCLK (spacecraft clock) kernels are essential.

    6. Use the right reference frame: state vectors will not compare well if they're specified relative to different reference frames. ``EME50'' frames are problematic because there are a variety of similar but non-identical frames all designated by this name. Examples are: B1950, FK4, DE-125. Implementations of body-fixed frames may differ as well. Also, some extended bodies have a variety of frames associated with them: Jupiter system I vs. system III for example.

    7. Use the right coordinate system: sometimes disagreements result from mismatched coordinate systems, for example planetocentric vs. planetodetic coordinates.

    8. Use the right aberration corrections: there can be a large difference between geometric (uncorrected) states and states corrected for light-time or light time and stellar aberration. When computing quantities involving surface locations on extended bodies, whether or not the rotation is retarded by light time is an issue.

    9. Use the current software: out-of-date Toolkits may contain bugs corrected in the current release.

    10. When diagnosing a problem, make sure a problem exists. Correct answers are sometimes counterintuitive. Not infrequently, a disagreement between a SPICE result and a ``cross-check'' result occurs because the latter is not mathematically equivalent to the former.

In the discussion below, it's implicit that any of the problem areas listed above should be examined whenever you diagnose a failure.



Top

Problems by Functional Area





The functional areas are listed alphabetically.



Top

Accuracy




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.



Top

Problem: Arithmetic on time values yields incorrect results



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.



Top

Problem: States from the SPK and NAVIO systems are not identical



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.



Top

Problem: UTC-TDB conversion in SPICE does not appear accurate



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.



Top

Problem: Light time corrections in SPICE seem to be inaccurate



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 the SPICE aberration corrections do not account for relativistic effects.



Top

Body-Fixed Frames






Top

Problem: Inertial/Bodyfixed position conversion gives SPICE error



Make sure you're using the correct ID code for the body.

Check your kernel file lists data for the body in question at 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 PCK data for the body must be available at the light-time corrected epoch.



Top

Problem: Inertial/Bodyfixed position conversion is incorrect



Rotational models for extended bodies vary. For any given body, the model and model parameter values may evolve over time, so verify 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. Confirm 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.



Top

Problem: Inertial/Body-fixed state conversion is incorrect



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)*P
Some applications external to SPICE erroneously ignore the second term in the second equation.



Top

CK/C-Kernel/C-Matrix/Pointing






Top

Problem: How does one determine the attributes of a C-kernel?



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.



Top

Problem: no pointing found at desired epoch



Check 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 the tolerance value supplied to the C-kernel reader function, either ckgp_c or ckgpav_c, 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 CK wrong reader. The reader ckgpav_c returns pointing data only if pointing data AND angular velocity data exists at the request time. You should use ckgp_c if your C-kernel lacks angular velocity data as ckgp_c doesn't require the presence such data.



Top

Problem: unclear what lookup tolerance to use



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 the data does not suffer from gaps, you may use a tolerance of zero. This choice guarantees 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.



Top

Problem: SPICE quaternions appear invalid



See ``Quaternions'' below.



Top

Coordinates






Top

Problem: SPICE does not produce expected lat/lon values



See ``Body-Fixed Frames'' above.

If the Cartesian body-fixed coordinates of a point are as expected, latitude and longitude may differ because of

    -- The difference between planetocentric and planetodetic latitude.

    -- The difference between planetocentric and planetographic latitude or longitude.

    -- Differences in the range of allowed longitude values.

    -- Differences in angular units. SPICE uses radians in all coordinate transformation functions.

    -- For planetodetic or planetographic coordinates, latitude is a function of the equatorial and polar radii of the defining body. Check these values are as expected.



Top

Documentation






Top

Problem: ``I can't find the function I need''



Use the SPICE permuted index in the /doc subdirectory of your SPICE Toolkit installation. The permuted index associates short functional descriptions with names of CSPICE functions. You can browse this document or search/grep it for keywords.

Only a small fraction of the functions in CSPICE tend to be called directly from users' applications. To familiarize yourself with this subset of functions, 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/cookbook
subdirectory 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.



Top

E-kernel






Top

Problem: Query takes forever to complete



For queries not involving the ordering of 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 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.



Top

Problem: Writing EK file takes forever



Use the ``fast loader'' routines, which are roughly two orders of magnitude faster than the record-oriented writers. See the header of ekifld_c (EK, initiate fast load) for an example.



Top

Problem: EK routines signal very mysterious errors



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 function calls are the typical root cause of these error messages.



Top

Error Handling






Top

Problem: SPICE errors abort my application program



The default error handling response is to abort the application. This response can be changed so SPICE routines return on entry. See the Error Required Reading, error.req, or the function erract_c.



Top

Problem: SPICE error messages are written to standard output



The target file for SPICE error messages can be reset. See the Error Required Reading, error.req, or the function errdev_c.



Top

Problem: SPICE(NAMESDONOTMATCH) error is displayed



If your application directly calls chkin_c and chkout_c, 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.



Top

Problem: ``Oh, by the way...'' message is annoying



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, error.req, or the function errprt_c.



Top

Problem: SPICE errors are not written to stderr



The current CSPICE error handling response is inherited from the FORTRAN library SPICELIB. In Standard ANSI FORTRAN 77 there is no distinct error stream.



Top

Euler Angles






Top

Problem: m2eul_c or xf2eul_c don't produce the expected angles



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_c or xf2eul_c carefully to determine what output ranges are used.



Top

File I/O






Top

Problem: File open error is signaled from SPICE-based utility



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 CSPICE functions 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.



Top

Problem: SPICE kernel reads fail within user's application



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.



Top

Problem: Logical unit conflict



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



Top

Problem: Error occurs when trying to close EK or DAS file



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 the disk space will be exhausted while writing to the file. This will result in a write error.



Top

File Transfer






Top

Problem: A text kernel causes a SPICE(INCOMPATIBLEEOL) error



These problems usually occur after accidentally performing a binary ftp transfer of the text file in question. SPICE use of such files can be expected to work only if the transfer is between systems having identical text file formats.

It is also possible the file was corrupted in transfer due to running out of disk space on the target system during the transfer.

SPICE Toolkits since version N57 include an error check to text file readers to ensure the files had the correct line terminators for the platform. NAIF added this check as loading non-native text kernels proved a continual problem for SPICE users - trying to load a non-native kernel usually caused no change to the kernel pool state resulting in unexpected results and confused users.

Most (if not all) modern Microsoft compilers perform an internal conversion from DOS terminators to Unix terminators, explaining why one seldom saw this problem on Windows.

As of Toolkit version N59, CSPICE/Icy text kernel loaders perform the conversion between text line terminators on Windows and Unix platforms; SPICELIB (the FORTRAN toolkit library) lacks this conversion capability and so signals INCOMPATIBLEEOL.

If the file being transferred is a NAIF ``transfer format'' version of a binary kernel, TOBIN can often diagnose file corruption when attempting the conversion to binary format.



Top

Problem: binary kernel imported from a second system does not work



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 the 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 -- tobin.ug, toxfr.ug, spacit.ug -- for further information.



Top

Installing the SPICE Toolkit






Top

Problem: SPICE routines don't compile, link, or run



First, the C 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 CSPICE, 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 CSPICE 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.



Top

Linear Algebra






Top

Problem: Bogus results returned by general-dimension functions



The general-dimension matrix and vector functions, unlike their 3-dimensional counterparts, usually do not permit overwriting input arguments with output values. Check the function headers for details.



Top

PCK/Pc-Kernel/Planetary constants






Top

Problem: PCK file does not contain desired contents



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, kernel.req, for further information on the NAIF text kernel format.



Top

Problem: Earth orientation given by a text PCK is too inaccurate



The CSPICE 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.



Top

Performance






Top

Problem: SPICE-based application is too slow



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

CSPICE applications can be somewhat sped up by disabling the function call tracing done internally by CSPICE. This is done by calling trcoff_c once during program initialization:

   trcoff_c();
Normally it is desirable to retain CSPICE's call tracing while an application is still being debugged. See Error Required Reading, error.req, or the header of trcoff_c 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 function, 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 CSPICE functions. 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_c, you can look up the observer state relative to the solar system barycenter via spkssb_c, then separately look up each apparent target state relative to the solar system barycenter via spkapp_c. This eliminates redundant computations of the observer's state.



Top

Quaternions






Top

Problem: NAIF quaternions appear incorrect



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'  =   q0
These equations also indicate how to transform the alternate quaternion style to the NAIF style.



Top

NAIF matrix--quaternion conversion appears incorrect



The formulas for conversion between quaternions and matrices depend on the quaternion style in use. See the section above.



Top

Reference frames






Top

Problem: EME50 vectors from SPICE appear incorrect



See discussion of reference frames in ``Getting it Right.''



Top

Problem: Vectors in body-fixed frame appear incorrect



See ``Body-Fixed Frames.''



Top

Software Application Integration






Top

Problem: SPICE function names conflict with application's names



NAIF cannot change the names of functions 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.



Top

Problem: SPICE code is not thread safe.



No mechanisms to ensure thread safe behavior exist in standard ANSI C or FORTRAN 77. NAIF has no plans to use non-standard features in CSPICE.



Top

Problem: Application requires SPICE error output to be trapped



See ``Error Handling.''



Top

SPK/Ephemeris/States






Top

Problem: How can I interactively determine the coverage of an SPK?



Use the SPICE utility program BRIEF to summarize the SPK file.



Top

Problem: Can't determine what states are computable from SPK files



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 functions. See the DAF Required Reading, daf.req, or the headers of dafbfs_c, dafbbs_c, daffna_c, daffpa_c, dafgs_c, and dafus_c.



Top

Problem: SPICE(SPKINSUFFDATA) error is signaled



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.



Top

Problem: no data found for times near SPK endpoints



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.



Top

Problem: states vary over different program runs



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.



Top

Problem: Velocity in rotating frame is incorrect



See ``Body-Fixed Frames.''



Top

Problem: SPK file contains clearly invalid data



The file may be corrupted. See ``File Transfer.''



Top

Problem: Osculating elements are wrong



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.



Top

Problem: Aberration-corrected states are not as expected



See ``Accuracy.''



Top

Problem: System barycenter-relative states are inconsistent



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



Top

System errors




SPICE attempts to catch errors before they result in system-level exceptions. Some types of errors are beyond SPICE's ability to intercept.



Top

Problem: divide by zero



Often due to missing data or uninitialized variables.



Top

Problem: subscript out of range



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.



Top

Problem: segmentation fault/memory access violation



Often caused by mismatched argument lists. Applications must supply arguments that match in data type and dimension with those expected by SPICE functions.

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.



Top

Problem: arithmetic overflow



Usually caused by invalid input data.



Top

Problem: arithmetic underflow



SPICE does not attempt to detect or prevent underflow.



Top

Time






Top

Problem: SPICE conversion between ET and UTC is incorrect



Possible causes:

    -- Leapseconds kernel is out of date.

    -- SPICE parsing of input time string is not as user expects (applicable only to string-to-ET conversion).

    -- SPICE rounding or truncation is not as user expects.

    -- user expects to input or output Terrestrial Dynamical Time (TDT); SPICE default is Barycentric Dynamical time (TDB).



Top

Problem: Stepping from start UTC to end UTC in loop fails



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_c to produce TDB, then calling unitim_c to convert TDB to TDT. Also, be sure to account for round-off in the loop termination test.



Top

Problem: SPICE time strings do not have the desired format



SPICE supports an enormous variety of input and output formats. See the Time Required Reading, time.req, and the headers of the functions str2et_c and timout_c.



Top

Problem: conversion between ET and SCLK fails



Possible causes:

    -- SCLK or leapseconds kernel is out of date.

    -- SPICE parsing of input time string is not as user expects.

    -- Input string lacks partition information and is ambiguous without it.

    -- SPICE rounding is not as user expects. When converting ET to discrete ticks, SPICE rounds. Some alternate algorithms truncate.

    -- ET time value is out of range covered by SCLK kernel.



Top

Problem: conversion of SCLK string to encoded SCLK fails



Possible causes:

    -- Conversion was not done using the CSPICE function scencd_c. Alternate conversion methods may not be reliable.



Top

Problem: SCLK string is misinterpreted



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, sclk.req, for a discussion of SCLK strings.



Top

Icy






Top

Problem: IDL segmentation fault



When using the N59 or N60 distributions of Icy 1.2, the IDL executive command

   .full_reset_session
may cause a segmentation fault on OS X, Linux and Windows platforms (dependent on the version of IDL). The solution requires editing of the icy.dlm text file. Open icy.dlm, locate the consecutive description entries:

   PROCEDURE   CSPICE_RECSPH     0 15
   PROCEDURE   CSPICE_REMOVD     0 15
Add a new entry for CSPICE_REMOVC.

   PROCEDURE   CSPICE_RECSPH     0 15
   PROCEDURE   CSPICE_REMOVC     0 15
   PROCEDURE   CSPICE_REMOVD     0 15
Then save and close icy.dlm.

NAIF corrected the problem for Icy 1.3, the N61 distribution.



Top

Appendix A: Revisions







Top

2017 MAR 14 by E. D. Wright




Edits to correct several minor typos.



Top

2007 FEB 11 by E. D. Wright






Top

2006 NOV 22 by B. V. Semenov.