Warning, /education/kstars/README.planetmath is written in an unsupported language. File is not indexed.

0001 README.planetmath:  Understanding Planetary Positions in KStars.
0002 copyright 2002 by Jason Harris and the KStars team.
0003 This document is licensed under the terms of the GNU Free Documentation License
0004 -------------------------------------------------------------------------------
0007 0. Introduction: Why are the calculations so complicated?
0009 We all learned in school that planets orbit the Sun on simple, beautiful 
0010 elliptical orbits.  It turns out this is only true to first order.  It 
0011 would be precisely true only if there was only one planet in the Solar System, 
0012 and if both the Planet and the Sun were perfect point masses.  In reality, 
0013 each planet's orbit is constantly perturbed by the gravity of the other planets
0014 and moons.  Since the distances to these other bodies change in a complex way,
0015 the orbital perturbations are also complex.  In fact, any time you have more 
0016 than two masses interacting through mutual gravitational attraction, it is 
0017 *not possible* to find a general analytic solution to their orbital motion.  
0018 The best you can do is come up with a numerical model that predicts the orbits 
0019 pretty well, but imperfectly.  
0022 1. The Theory, Briefly
0024 We use the VSOP ("Variations Seculaires des Orbites Planetaires") theory of 
0025 planet positions, as outlined in "Astronomical Algorithms", by Jean Meeus.  
0026 The theory is essentially a Fourier-like expansion of the coordinates for 
0027 a planet as a function of time.  That is, for each planet, the Ecliptic 
0028 Longitude, Ecliptic Latitude, and Distance can each be approximated as a sum:
0030   Long/Lat/Dist = s(0) + s(1)*T + s(2)*T^2 + s(3)*T^3 + s(4)*T^4 + s(5)*T^5
0032 where T is the number of Julian Centuries since J2000.  The s(N) parameters
0033 are each themselves a sum:
0035   s(N) = SUM_i[ A(N)_i * Cos( B(N)_i + C(N)_i*T ) ]
0037 Again, T is the Julian Centuries since J2000.  The A(N)_i, B(N)_i and C(N)_i
0038 values are constants, and are unique for each planet.  An s(N) sum can
0039 have hundreds of terms, but typically, higher N sums have fewer terms.
0040 The A/B/C values are stored for each planet in the files
0041 <planetname>.<L/B/R><N>.vsop.  For example, the terms for the s(3) sum
0042 that describes the T^3 term for the Longitude of Mars are stored in
0043 "mars.L3.vsop".
0045 Pluto is a bit different.  In this case, the positional sums describe the
0046 Cartesian X, Y, Z coordinates of Pluto (where the Sun is at X,Y,Z=0,0,0).
0047 The structure of the sums is a bit different as well.  See KSPluto.cpp
0048 (or Astronomical Algorithms) for details.
0050 The Moon is also unique, but the general structure, where the coordinates
0051 are described by a sum of several sinusoidal series expansions, remains
0052 the same.
0055 2. The Implementation.
0057 The KSplanet class contains a static OrbitDataManager member.  The
0058 OrbitDataManager provides for loading and storing the A/B/C constants
0059 for each planet.  In KstarsData::slotInitialize(), we simply call
0060 loadData() for each planet.  KSPlanet::loadData() calls
0061 OrbitDataManager::loadData(QString n), where n is the name of the planet.
0063 The A/B/C constants are stored hierarchically:
0064  + The A,B,C values for a single term in an s(N) sum are stored in an
0065    OrbitData object.
0066  + The list of OrbitData objects that compose a single s(N) sum is
0067    stored in a QVector (recall, this can have up to hundreds of elements).
0068  + The six s(N) sums (s(0) through s(5)) are collected as an array of
0069    these QVectors ( typedef QVector<OrbitData> OBArray[6] ).
0070  + The OBArrays for the Longitude, Latitude, and Distance are collected
0071    in a class called OrbitDataColl.  Thus, OrbitDataColl stores all the
0072    numbers needed to describe the position of any planet, given the
0073    Julian Day.
0074  + The OrbitDataColl objects for each planet are stored in a QDict object
0075    called OrbitDataManager.  Since OrbitDataManager is static, each planet can
0076    access this single storage location for their positional information.
0077    (A QDict is basically a QArray indexed by a string instead of an integer.
0078    In this case, the OrbitDataColl elements are indexed by the name of the
0079    planets.)
0081 Tree view of this hierarchy:
0083 OrbitDataManager[QDict]: Stores 9 OrbitDataColl objects, one per planet.
0084 |
0085 +--OrbitDataColl: Contains all three OBArrays (for 
0086    Longitude/Latitude/Distance) for a single planet.
0087    |
0088    +--OBArray[array of 6 QVectors]: the collection of s(N) sums for 
0089       the Latitude, Longitude, or Distance.
0090       |
0091       +--QVector: Each s(N) sum is a QVector of OrbitData objects
0092          |
0093          +--OrbitData: a single triplet of the constants A/B/C for 
0094             one term in an s(N) sum.
0096 To determine the instantaneous position of a planet, the planet calls its
0097 findPosition() function.  This first calls calcEcliptic(double T), which
0098 does the calculation outlined above: it computes the s(N) sums to determine
0099 the Heliocentric Ecliptic Longitude, Ecliptic Latitude, and Distance to the
0100 planet.  findPosition() then transforms from heliocentric to geocentric
0101 coordinates, using a KSPlanet object passed as an argument representing the
0102 Earth.  Then the ecliptic coordinates are transformed to equatorial
0103 coordinates (RA,Dec).  Finally, the coordinates are corrected for the
0104 effects of nutation, aberration, and figure-of-the-Earth.  Figure-of-the-Earth 
0105 just means correcting for the fact that the observer is not at the center of 
0106 the Earth, rather they are on some point on the Earth's surface, some 6000 km
0107 from the center.  This results in a small parallactic displacement of the 
0108 planet's coordinates compared to its geocentric position.  In most cases, 
0109 the planets are far enough away that this correction is negligible; however, 
0110 it is particularly important for the Moon, which is only 385 Mm (i.e., 
0111 385,000 km) away.