PDS_VERSION_ID = PDS3 RECORD_TYPE = STREAM OBJECT = TEXT PUBLICATION_DATE = 2005-02-22 NOTE = "AAREADME file containing a complete overview of the PDS Rings Node's Kepler Library, version 1.0.2." END_OBJECT = TEXT END ********************************************************************** PDS Rings Node Software Library Part 1: THE KEPLER LIBRARY Version 1.0.2, February 2005 Mark R. Showalter ********************************************************************** 1. INTRODUCTION The Kepler Library comprises a set of C functions for calculating various aspects of a satellite orbit, such as positions, orbital rates, resonance locations, etc. It is designed to provide a high degree of numeric accuracy and efficiency. The library also includes a set of functions that are more easily called from FORTRAN programs. Each routine is found in a separate file, given by the routine's name and with a ".c" extension (all in lower case on UNIX systems). A header in each routine describes what it does and how it is called, and extensive comments within the code document the algorithms used. 1.1 Change History Version 1.0 (8/95) Original release. Version 1.0.1 (2/04) Adds support for Macintosh OS X. It also provides a detached PDS label file "KEPLER.LBL" and a software catalog file "SOFTWARE.CAT", making the library suitable for archiving on any PDS volume. Version 1.0.2 (2/05) Adds support for LINUX using the g77 compiler. 2. SUMMARY OF ROUTINES 2.1 Orbital rate calculations The following routines are used to calculate the relationship between orbital rate and semimajor axis in the gravitational field of an arbitrary, oblate planet. They are fully accurate for gravitational moments up to J20, and will work for even higher order terms if a symbol in file "kepler.h" is re-defined. However, they neglect any terms of order (e^2 J2) or (sin(i)^2 J2). Kep_SetPlanet Used to specify a planet's gravitational field. Kep_Omega Returns omega, the mean motion, as a function of mean orbital radius. Kep_Kappa Returns kappa, the radial (or eccentric) oscillation frequency, as a function of mean orbital radius. Kep_Nu Returns nu, the vertical (or inclined) oscillation frequency, as a function of mean orbital radius. Kep_5Freq Returns all five physically meaningful frequencies associated with an orbit of given radius: omega, kappa, nu, and the apsidal and nodal precession rates. This is significantly faster than multiple calls to the individual functions listed above. Kep_Combo Returns a "combination" frequency as a function of mean orbital radius. A combination frequency is defined to be the sum of omega, kappa and nu, each multiplied by an integer coefficient. It employs a trick to retain high accuracy when the coefficients sum to zero. Kep_SolveA Solves for the mean radius at which a specified combination frequency equals a given value. This powerful routine may be used to determine a satellite orbit based on its mean motion, or to solve for the locations of arbitrary resonances. (*) For convenience, the following two functions are provided via C macro definitions. Kep_Apse returns the apsidal precession rate, equivalent to omega minus kappa. Kep_Node returns the nodal regression rate, equivalent to omega minus nu. 2.2 Orbital trajectory calculations The following set of routines are used to track the position and orbital elements of a satellite in time. Positions will be accurate for arbitrary e < 1 and sin(i) < 1, except to the extent that orbital precession rates become less accurate for eccentric or inclined orbits when the central body is oblate (see restrictions on orbital rates above). Additional perturbations from the Sun or other nearby satellites are not included. Kep_SetOrbit Used to specify the orbital elements of a satellite. Kep_Precess Returns the orbital elements of a satellite after precession to a new epoch. Kep_MeanAnom Returns a satellite's mean anomaly, given its eccentricity and true anomaly. Kep_TrueAnom Returns a satellite's true anomaly, given its eccentricity and mean anomaly. (*) Kep_Locate Returns the planet-centered position and/or velocity of a satellite at a given time. (*) 2.3 Accuracy specification In general, each routine will return values at the full double-precision accuracy of the platform on which you are running. However, for the routines marked with an asterisk (*) above, the user has the option of reducing the accuracy of the result, and thereby (perhaps) speeding up the computations. Kep_SetError Used to specify the approximate fractional accuracy of some of the above routines. 2.4 FORTRAN-compatible routines By appending the letter "F" to the beginning of any of the above routines, you will obtain the name of a FORTRAN-compatible equivalent. Note that the arguments to these routines may differ slightly from the C versions. 2.5 Internal routines Several routines in the library have names beginning with "XKep_". These are used internally by the other Kepler Library routines, but are not intended for use outside the library. Documentation is provided, but use them at your own risk. 3. EXAMPLES Several additional programs are provided, which illustrate the use of Kepler Library routines. 3.1 table3.f This FORTRAN program illustrates the use of fKep_SolveA() to solve for the location of resonances in Saturn's rings. It reproduces Table 3 of Lissauer and Cuzzi, Resonances in Saturn's Rings, Astron. J. 87, 1051-1058. This table lists the Lindblad resonance locations of 1980S28 in units of Saturn radii. 3.2 solver.f This FORTRAN program prompts the user for the "combination" coefficients and then solves for either radius as a function of frequency, or vice versa. It is set up for the Saturn system, but could be used with any other planet by changing the gravity parameters given in the source. 3.3 orbit.f This simple FORTRAN program determines the coordinates of a satellite at uniformly-spaced moments in time, based on its orbital elements. Output may be directed either to the terminal or to a file. Once again, it is set up for the Saturn system, but could be modified easily. 3.4 Test programs Several test programs written in C are also provided. They have names beginning with "TKep_", and the remainder of the name indicates which routine it is used to test (although, in general, these programs actually test several library routines). These programs are used to confirm that various sets of routines yield compatible results. They may also provide the user with some guidance as to how to use these routines. 4. USAGE To use Kepler Library routines from within a C program, one should include the file "kepler.h". This file provides a declaration prototype for each function, and also defines the few routines treated as macros. In addition, this file declares two special typedefs, KEP_PLANET and KEP_ORBIT. The user need not concern him/herself with the format of these types; they are simply used to hold information describing a planetary gravity field, and may be treated as "black boxes" by the user. To call the routines from FORTRAN, no special include file is needed. 5. BUILDING INSTRUCTIONS 5.1 UNIX This library has been tested on UNIX systems by DEC, Sun, and Silicon Graphics. To build the library and test binaries on a Sun, type chmod +x makesun.com ./makesun.com To build the library and binaries on a system by DEC or Silicon Graphics, type chmod +x makedec.com ./makedec.com To build the library and binaries under LINUX using the g77 compiler, type chmod +x makeg77.com ./makeg77.com In each case, the script file "make*.com" will compile each file and build an archive file called "kepler.a". (Note that any pre-existent file called "kepler.a" should be removed first). The test program binaries are called "orbit", "solver" and "table3". The commands "cc" and "f77" are used by these scripts (except makeg77, where "g77" is called in place of "f77"). Be sure that your command search path includes these before executing the script. To use the library, include "kepler.a" among the files that appear on a cc or f77 command line. Note that for C programs, you must also include the "-lm" option to load in the C math libraries. 5.2 VMS (Vax or Alpha) To build the library and executables on a Vax or Alpha using the VMS operating system, type @MAKEVMS This will compile each file and build an object library called KEPLER.OLB. The test program binaries are called ORBIT.EXE, SOLVER.EXE and TABLE3.EXE. To use the library, include KEPLER/LIBRARY among the files in a LINK command.