| Common Problems |
Table of ContentsCommon 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 routine 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 Euler Angles Problem: M2EUL or XF2EUL 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 routines 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 routine 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. Common Problems
Failure is not an option.
-- "Apollo 13"
Last revised on 2017 MAR 14 by E. D. Wright
Abstract
Introduction
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. Getting it Right
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.
Problems by Functional Area
Accuracy
Problem: Arithmetic on time values yields incorrect results
Problem: States from the SPK and NAVIO systems are not identical
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. Problem: UTC-TDB conversion in SPICE does not appear accurate
The UTC-TDB conversion in SPICE is accurate to about 4.E-5 seconds. Problem: Light time corrections in SPICE seem to be inaccurate
Be aware the SPICE aberration corrections do not account for relativistic effects. Body-Fixed FramesProblem: Inertial/Bodyfixed position conversion gives SPICE error
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. Problem: Inertial/Bodyfixed position conversion is incorrect
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. Problem: Inertial/Body-fixed state conversion is incorrect
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. CK/C-Kernel/C-Matrix/PointingProblem: How does one determine the attributes of a C-kernel?
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. Problem: no pointing found at desired epoch
If the ID code is correct, it may be 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 CK wrong reader. The reader CKGPAV returns pointing data only if pointing data AND angular velocity data exists at the request time. You should use CKGP if your C-kernel lacks angular velocity data as CKGP doesn't require the presence such data. Problem: unclear what lookup tolerance to use
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. Problem: SPICE quaternions appear invalid
CoordinatesProblem: SPICE does not produce expected lat/lon values
If the Cartesian body-fixed coordinates of a point are as expected, latitude and longitude may differ because of
DocumentationProblem: ``I can't find the routine I need''
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. E-kernelProblem: Query takes forever to complete
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. Problem: Writing EK file takes forever
Problem: EK routines signal very mysterious errors
Error HandlingProblem: 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
Euler AnglesProblem: M2EUL or XF2EUL don't produce the expected angles
Review the headers of M2EUL or XF2EUL carefully to determine what output ranges are used. File I/OProblem: File open error is signaled from SPICE-based utility
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. Problem: SPICE kernel reads fail within user's application
Logical unit conflicts can cause nonsense data to be returned when reading SPICE kernels. The symptoms can be obscure. See below. Problem: Logical unit conflict
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. Problem: Error occurs when trying to close EK or DAS file
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. File TransferProblem: A text kernel causes a SPICE(INCOMPATIBLEEOL) error
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. Problem: binary kernel imported from a second system does not work
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. Installing the SPICE ToolkitProblem: SPICE routines don't compile, link, or run
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. Linear AlgebraProblem: Bogus results returned by general-dimension routines
PCK/Pc-Kernel/Planetary constantsProblem: PCK file does not contain desired contents
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. Problem: Earth orientation given by a text PCK is too inaccurate
NAIF is also developing the capability of producing high-accuracy PCK files for the moon. PerformanceProblem: SPICE-based application is too slow
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 somewhat sped up 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, error.req, 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. QuaternionsProblem: NAIF quaternions appear incorrect
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. NAIF matrix--quaternion conversion appears incorrect
Reference framesProblem: EME50 vectors from SPICE appear incorrect
Problem: Vectors in body-fixed frame appear incorrect
Software Application IntegrationProblem: SPICE routine names conflict with application's names
Problem: SPICE code is not thread safe.
Problem: Application requires SPICE error output to be trapped
SPK/Ephemeris/StatesProblem: How can I interactively determine the coverage of an SPK?
Problem: Can't determine what states are computable from SPK files
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, daf.req, or the headers of DAFBFS, DAFBBS, DAFFNA, DAFFPA, DAFGS, and DAFUS. Problem: SPICE(SPKINSUFFDATA) error is signaled
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. Problem: no data found for times near SPK endpoints
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. Problem: states vary over different program runs
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. Problem: Velocity in rotating frame is incorrect
Problem: SPK file contains clearly invalid data
Problem: Osculating elements are wrong
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. Problem: Aberration-corrected states are not as expected
Problem: System barycenter-relative states are inconsistent
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). System errors
Problem: divide by zero
Problem: subscript out of range
Problem: segmentation fault/memory access violation
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. Problem: arithmetic overflow
Problem: arithmetic underflow
TimeProblem: SPICE conversion between ET and UTC is incorrect
Problem: Stepping from start UTC to end UTC in loop fails
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. 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
IcyProblem: IDL segmentation fault
.full_reset_sessionmay 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 15Add a new entry for CSPICE_REMOVC.
PROCEDURE CSPICE_RECSPH 0 15 PROCEDURE CSPICE_REMOVC 0 15 PROCEDURE CSPICE_REMOVD 0 15Then save and close icy.dlm. NAIF corrected the problem for Icy 1.3, the N61 distribution. Appendix A: Revisions2017 MAR 14 by E. D. Wright
2007 FEB 11 by E. D. Wright2006 NOV 22 by B. V. Semenov.
|