Bug in NAIF library

Linda Wills (linda@cc.gatech.edu)
21 Oct 1994 10:54:14 -0400

NAIF found a bug in the CKGPAV routine. The bug fix is minor
(replacing a call to MXV w/ MTXV), so I will go ahead and make the
change.

I'm really surprised this error wasn't detected earlier! Another
interesting bug was detected and fixed 2 years ago in my favorite
routine NPEDLN (according to its modification history): PNEAR was not
being rescaled on the way out of the routine. This type of bug might
be something we could detect if we were able to recognize
transform-compute-untransform patterns (such as scale/rescale
wrappers).

Linda

___________________________________________________________________________

~From: HAN@NAIF.JPL.NASA.GOV
To: LFJHH00%TAIMVS1.BITNET@CUNYVM.CUNY.EDU, LHW@LOWELL.EDU,
LIMAYE@limaye.meteor.wisc.edu, LINDA@cc.gatech.edu,
LJG@SPACE.PHYSICS.UIOWA.EDU, LOUCKS@HOSHI.COLORADO.EDU,
LOWRY@ptolemy-ethernet.arc.nasa.gov, MA@ASTRO.UMD.EDU,
MARC@FENDER.JPL.NASA.GOV
~Subject: SPICELIB Bug: CKGPAV
~Date: Fri, 14 Oct 1994 18:11:23 -0700 (PDT)

***************************************************************************

BUG Alert!

If you wish to have your name deleted from this list, please send e-mail
to naif@naif.jpl.nasa.gov (smtp) or NAIF::NAIF (SPAN). We are still in
the process of updating the list from June, so if you've already requested
to be removed from this mailing list but haven't been, we apologize.

***************************************************************************

Dear SPICE User,

Last Thursday (October 6, 1994), while in the process of
preparing for SPICE system upgrades, a serious mathematical
error was discovered in the SPICELIB routine CKGPAV. This
routine is used to determine the attitude and angular
velocities of instruments and spacecraft structures.

CKGPAV retrieves from a SPICE C-kernel a C-matrix and
angular velocity for some user specified spacecraft
structure at a user specified epoch in a user specified
reference frame.

Nature of the error:
===========================================

This error affects CKGPAV module versions 2.0.1 and lower.

The error concerns the angular velocity returned by CKGPAV.

If the specified reference frame is not the reference frame
of the C-kernel, the angular velocity vector returned is
incorrect. (However, the C-matrix returned is correctly
transformed relative to the specified reference frame.)

If you request attitude and angular velocity relative to
the frame in which the data is stored, the angular
velocities returned are correct.

Size of the error:
===========================================

The magnitude of the angular velocity is correct. However,
the value returned has been erroneously rotated by the
inverse of the transformation matrix needed to transform
from the C-kernel reference frame to the user specified
reference frame.

If the frame requested is one of the Earth Equator and
Equinox frames, (for example FK4, J2000, B1950) and the data
in the C-kernel is stored relative to such a frame. The
magnitude of the error will be on the order of a few
arcseconds.

However, if the requested frame is an ecliptic or galactic
frame and C-kernel has stored attitude information relative
to one of the Earth Equator and Equinox frames, the direction
of the angular velocity vector returned may be in error by
tens of degrees.

Corrective Measures
===========================================

NAIF has fixed this error and will be reconfiguring the SPICE
Toolkit next week. You may receive a new configuration of the
Toolkit. NAIF will send a notification message
informing users when the new Toolkit is available on all of the
supported platforms, probably at the end of October.

If possible, we recommend that you wait to obtain the corrected
version of this routine. However, if that causes too many
problems for your particular circumstances, you may take
the following steps to protect yourself from this error.

1) If possible, request pointing and angular velocity relative
to the frame in which the data is stored. You can determine
this frame by summarizing your C-kernel with the SPICE
utility SPACIT.

2) Admittedly, approach 1 is not a very satisfactory solution.
Another approach it to repair the source code for CKGPAV.
Although we generally recommend against altering SPICE
source code, in this case you can probably easily correct
the error. Here are the steps to follow.

A) Make a backup copy of the source code for CKGPAV.
The source is located in the SPICELIB source code file
called 'ckgpav.f' or 'ckgpav.for', depending on your platform.
================================================================

B) Open CKGPAV with a text editor and make sure the version
number is 2.0.1 or lower. If the version number is
higher, you have already received the corrected version of
the routine. Don't do anything to it. The version number
is contained in the Version section of the header. That beginning
of that section is indicated by the line

C$ Version

The section of the header should look something like this:

C$ Version
C
C- SPICELIB Version 2.0.1, 10-MAR-1992 (WLT)
C
C Comment section for permuted index source lines was added
C following the header.
C
C- SPICELIB Version 2.0.0, 30-AUG-1991 (JML)
C


In version 2.0.1 this is on line 374 of the source file.
================================================================

C) Locate the following line of source code

CALL MXV ( ROT, AV, AV )

This is the erroneous line of code.
In version 2.0.1 this line occurs at approximately line 591 of
the source file. The exact location depends on whether you have
received precompiled versions of the code or code with VAX
extensions. To help you locate this section of the code, we've
included the the following code fragment that contains the
erroneous line.
================================================================
C
C If IRFROT detects that the reference frame is invalid
C then return from this routine with FOUND equal to false.
C
IF ( FAILED () ) THEN
CALL CHKOUT ( 'CKGPAV' )
RETURN
END IF

CALL MXM ( CMAT, ROT, CMAT )
CALL MXV ( ROT, AV, AV ) <---erroneous line


D) Replace the erroneous line above with the following:

CALL MTXV ( ROT, AV, AV )

After doing so the code should now look like this:
================================================================

C
C If IRFROT detects that the reference frame is invalid
C then return from this routine with FOUND equal to false.
C
IF ( FAILED () ) THEN
CALL CHKOUT ( 'CKGPAV' )
RETURN
END IF

CALL MXM ( CMAT, ROT, CMAT )
CALL MTXV ( ROT, AV, AV )

E) Update the version section of the header of the routine
as below so that you will be able to tell which version
of the routine you have in your library.
================================================================

C$ Version
C
C- BUGFIX Private version: <date of the fix> <your name>
C
C Corrected angular velocity transformation
C bug as reported by NAIF.
C
C- SPICELIB Version 2.0.1, 10-MAR-1992 (WLT)
C
C Comment section for permuted index source lines was added
C following the header.

F) Save and close the file. Compile it and replace its object in your
version of the SPICELIB object library.
================================================================

NAIF regrets this error and we apologize for any problems
or inconvenience that you may have or will experience as a
result of this error on our part. If you have any questions
regarding this error, please do not hesitate to contact us.

For NAIF,
Bill Taber and Hester Neilan

btaber@spice.jpl.nasa.gov
(818) 354-4279

hneilan@spice.jpl.nasa.gov
(818) 354-2504

-- 
					
					-Linda Wills (linda@cc.gatech.edu)