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.
0004 -------------------------------------------------------------------------------
0005
0006
0007 0. Introduction: Why are the calculations so complicated?
0008
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.
0020
0021
0022 1. The Theory, Briefly
0023
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:
0029
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
0031
0032 where T is the number of Julian Centuries since J2000.  The s(N) parameters
0033 are each themselves a sum:
0034
0035   s(N) = SUM_i[ A(N)_i * Cos( B(N)_i + C(N)_i*T ) ]
0036
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".
0044
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.
0049
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.
0053
0054
0055 2. The Implementation.
0056
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.
0062
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 ).
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.)
0080
0081 Tree view of this hierarchy:
0082
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.
0095
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.
0112
```