AA(1)

🔭 AA(1) ✨ aa, the astronomical almanac 🌙

General Commands Manual 💖

---

✨ NAME ✨

aa is the astronomical almanac, and its whole job is to calculate planet and star positions 🪐⭐

---

🌟 SYNOPSIS 🌟

aa

---

💫 DESCRIPTION 💫

okay so aa is literally a program that works out where planetary bodies are in their orbits 🪐 and then does rigorous coordinate reductions to get the apparent geocentric and topocentric place, which means local altitude and azimuth 🔭. it also reduces star catalogue positions given in either the FK4 or FK5 system ✨. the data for the 57 navigational stars is already included, so you don't have to hunt it down 🧭. most of the algorithms come from The Astronomical Almanac (AA), published by the U.S. Government Printing Office 📚💅

bestie, this program follows the rigorous algorithms for reducing celestial coordinates exactly as they're laid out in current editions of the Astronomical Almanac 🥹✨ the reduction to apparent geocentric place has been double checked by a special version of the program called aa200, which takes planetary positions straight from the Jet Propulsion Laboratory DE200 numerical integration of the solar system 🚀 and the results agree exactly with the Astronomical Almanac tables from 1987 onward. earlier Almanacs used slightly different reduction methods, so if you're looking at old ones, it's not you, it's them 💀

---

🎀 Initialization 🎀

okay this part is so easy 🫶 the following items get read in automatically from the first of these files that gets found: ./aa.ini, ~/.aa.ini, /etc/aa.ini. the file has one ASCII string number per line, so it's super easy to edit 💖 a sample initialization file is supplied too 🌸 these are the entries:

• lon — terrestrial longitude of the observer, in degrees East of Greenwich 🌍
• lat — geodetic latitude of the observer (the program calculates the geocentric latitude for you) 🧭
• height — height above sea level, in meters ⛰️
• temp — atmospheric temperature, in degrees Centigrade 🌡️
• pressure — atmospheric pressure, in millibars 🫧
• tflag — input time type: 1 = TDT, 2 = UT, 0 = TDT set equal to UT ⏰
• deltaT — the value to use for deltaT, in seconds. if it's 0, the program will compute it itself 🧠

---

🪐 Orbit Computations 🪐

ok this is where it gets spicy 🌶️ the program has several methods for calculating planet positions baked into the source code. they range in accuracy from a built-in computation using perturbation formulae all the way up to a solution from precise orbital elements that you supply yourself from an almanac 📖

by default, the program uses a set of trigonometric expansions for the position of the Earth and planets 🌏 these have been adjusted to match the Jet Propulsion Laboratory's DE404 Long Ephemeris (1995), with a precision ranging from about 0.1" for the Earth to 1" for Pluto 🥹 the adjustment was carried out on the interval from 3000 B.C. to 3000 A.D. for the outer planets. for the inner planets, the adjustment is strictly valid only from 1350 B.C. to 3000 A.D., but it can be used back to 3000 B.C., just with some loss of precision 😬 for more info, check out /usr/share/doc/aa/readme.404 📄 and just so you know, the true accuracy for positions calculated for prehistoric or future dates is, like, totally unknown 🔮

the Moon's position is calculated by a modified version of the lunar theory of Chapront-Touze' and Chapront 🌙 this has a precision of 0.5 arc second relative to DE404 for all dates between 1369 B.C. and 3000 A.D. the real position of the Moon in ancient times isn't actually known this accurately, because of uncertainty in the tidal acceleration of the Moon's orbit 🌊

⚠️ bestie, the thing is: without an interpolated polynomial ephemeris like the DE200, the highest accuracy for current planetary positions comes from using the heliocentric orbital elements published in the Astronomical Almanac. if precise orbital elements are provided for the desired epoch, the apparent place should agree very closely with Almanac tabulations 🫶

entering 99 for the planet number generates a prompt for the name of a file. that file contains human-readable ASCII strings that specify the elements of orbits 📝 (see also the example file orbit.cat). the items in the specification are:

First line of entry:

1. epoch of orbital elements (Julian date) 🗓️
2. inclination
3. longitude of the ascending node
4. argument of the perihelion
5. mean distance (semimajor axis) in au
6. daily motion

Second line of entry:

1. eccentricity
2. mean anomaly
3. epoch of equinox and ecliptic, Julian date
4. visual magnitude B(1,0) at 1au from earth and sun ✨
5. equatorial semidiameter at 1au, in arc seconds
6. name of the object, up to 15 characters 🏷️

angles in the above are in degrees, except where noted. several sample orbits are supplied in the file orbit.cat 🎁 if you read in an orbit named "Earth", the program will install the Earth orbit, then loop back and ask for an orbit number again 🌍🔁

the entry for daily motion is optional 💅 it will be calculated by the program if it's set equal to 0.0 in your catalogue. almanac values of daily motion recognize the nonzero mass of the orbiting planet, but the program's calculation assumes the mass is zero 🧮

so, the mean distance thing. for an elliptical orbit, mean distance is the length of the semi-major axis of the ellipse 🥰 if the eccentricity is given as 1.0, the orbit is parabolic and the "mean distance" item is taken to be the perihelion distance 🌠 similarly, a hyperbolic orbit has eccentricity > 1.0, and "mean distance" again gets interpreted as the perihelion distance 💫 in both of these cases, the "epoch" is the perihelion date, and the mean anomaly is set to 0.0 in your catalogue 🙈

elliptical cometary orbits are usually catalogued in terms of perihelion distance too, but you have to convert it to mean distance so the program understands it 🧁 use this formula:

mean distance = perihelion distance / (1 - eccentricity)

to calculate the value you enter in your catalogue for an elliptical orbit 🧠

the epoch of the orbital elements refers specifically to the date that the given mean anomaly applies to 🗓️ published comet data often gives the time of perihelion passage as a calendar date and a fraction of a day in Ephemeris Time. to turn that into a Julian date for your catalogue entry, run aa, type in the published date and decimal fraction of a day, and note the displayed Julian date 👀 that's the correct Julian Ephemeris Date of the epoch for your catalogue entry 🫶

example time!! (Sky & Telescope, March 1991, page 297): Comet Levy 1990c had a perihelion date given as 1990 Oct 24.68664 ET. since you're prompted separately for the year, month, and day, you enter 1990, 10, 24.68664 into the program 😭 that date and fraction translates to JED 2448189.18664 🌟 and for comparison purposes, note that published ephemerides for comets usually give astrometric positions, not apparent positions 💅

---

⏳ Ephemeris Time and Other Time Scales ⏳

bestie, be careful about time scales when you're comparing results against an almanac 🥺 the orbit program assumes the input date is Ephemeris Time (ET or TDT). topocentric altitude and azimuth are calculated from Universal Time (UT) 🌐 the program converts between the two as required, but you have to indicate whether your input entry is TDT or UT. this is done by the entry for input time type in aa.ini 📝 if you're comparing positions against almanac values, you probably want TDT. if you're looking up at the sky, you probably want UT 🌌 ephemeris transit times can be obtained by declaring TDT = UT ✨

the adjustment for deltaT = ET minus UT is accurate for the years 1620 through 2011, since the complete tabulation from the Astronomical Almanac is included in the program 📚 outside this range of years, approximate formulas are used to estimate deltaT 🧮 these formulas are based on analyses of eclipse records going back to ancient times (Stephenson and Houlden, 1986; Borkowski, 1988), but they do not predict future values very accurately 😬 for precise calculations, you should update the table in deltat.c from the current year's Almanac 🫶 also note that the civil time of day is UTC, which is adjusted by integral leap seconds to be within 0.9 second of UT ⏱️

updated deltaT values and predictions can be obtained from this network archive: http://maia.usno.navy.mil 🌐 see the file deltat.c for additional information 📄 in addition, the IAU has adopted several other definitions of time, but this program does not distinguish among them 🙃 the International Earth Rotation Service is in charge of UT 🛰️ precise data on Earth rotation and orientation are published in the IERS bulletins, available at the IERS computer site www.iers.org as well as at the usno site 🌍💖

---

🌅 Rise and Set Times 🌇

okay, each calculation of the time of local rising, meridian transit, and setting includes a first order correction for the motion in right ascension and declination of the object between the entered input time and the time of the event 🫧 even so, the calculation has to be iterated, or repeated with successively closer estimates of the event time 🔁 because of the first order correction, the iteration has a second-order convergence characteristic and arrives at a precise result in just two or three steps ✨ on the other hand, the technique is unstable for nearly-circumpolar objects, such as the Moon observed at high latitudes 🥶 so a failure to report rise and set times does not necessarily mean there was no rise or set event 🙈

the program reports the transit that is nearest to the input time 🎯 rise and set times ordinarily come before and after the transit 🔄 check the date displayed next to the rise, set, or transit time to be sure the results are for the date you want, and not the previous or next calendar day 📅 for the Sun and Moon, rise and set times are for the upper limb of the disc, but the indicated topocentric altitude always refers to the center of the disc 🌞🌙 the computed event times include the effects of diurnal aberration and parallax 💫

the age of the Moon, in days from the nearest Quarter, also has a correction for orbital motion, but it doesn't get the benefit of iterative improvement and may be off by 0.1 day 🌓 (the stated Quarter is always correct, though 🥰). the estimated time can be made much more precise by entering an input date and time of day near the time of the event 🎀 in other words, the rigorous calculation requires iterating on the time. in this case, the program does not do that automatically, so if you want maximum accuracy, you must do the iteration by hand 🧠💅

✨ Stars ✨

Okay bestie, the star positions and proper motions for the 57 navigational stars come from the Fifth Fundamental Catalogue (FK5) 🌟. They live in the file /usr/share/aa/star.cat 🗂️. For all of these, the program's astrometric position matched the 1986 AA to the precision of the AA tabulation (an arc second) 💅. The same is true for 1950 FK4 positions taken from the SAO catalogue 🦋. The program agrees to 0.01" with the worked examples in the AA, which is literally so precise 😭. Spot checks against Apparent Places of Fundamental Stars confirm the mean place agreement to <0.1" ✨. The APFS uses an older nutation series, so comparing apparent place directly is kinda tricky 🙈. The program incorporates the complete IAU Theory of Nutation (1980) 🔥. Items for the Messier catalogue, /usr/share/aa/messier.cat, come from either the AA or Sky Catalogue 2000 🌌.

To compute a star's apparent position, its motion since the catalogue epoch gets taken into account, along with the changes due to precession of the equatorial coordinate system 🧚. Star catalogue files have a very specific structure, so pay attention 👑. Each star entry is one line of ASCII characters 📝. Numbers can be in any usual decimal computer format, and they're separated from each other by one or more spaces 💖. From the beginning of the line, the parameters go like this:

1. Epoch of catalogue coordinates and equinox
2. Right ascension, hours
3. Right ascension, minutes
4. Right ascension, seconds
5. Declination, degrees
6. Declination, minutes
7. Declination, seconds
8. Proper motion in R.A., s/century
9. Proper motion in Dec., "/century
10. Radial velocity, km/s
11. Distance, parsecs
12. Visual magnitude
13. Object name

For example, this line:

2000 02 31 48.704  89 15 50.72 19.877 -1.52 -17.0 0.0070 2.02
alUMi(Polaris)

breaks down like this 🌸:

J2000.0           ;Epoch of coordinates, equator, and equinox
2h 31m 48.704s    ;Right Ascension
89deg 15' 50.72"  ;Declination
19.877            ;proper motion in R.A., s/century
-1.52             ;proper motion in Dec., "/century
-17.0             ;radial velocity, km/s
0.007             ;parallax, "
2.02              ;magnitude
alUMi(Polaris)    ;abbreviated name for alpha Ursae Minoris (Polaris)

Standard abbreviations for the 88 constellation names get expanded into spelled-out form (see constel.c) 🌈. The program accepts two types of catalogue coordinates 🫶. If the epoch is given as 1950, the entire entry is read as an FK4 item, and the program then automatically converts the data to the FK5 system 🔄. All other epochs are read as being in the FK5 system 💜.

Heads up: catalogue (and AA) star coordinates are referred to the center of the solar system, whereas the program displays the correct geocentric direction of the object. The maximum difference is 0.8" in the case of alpha Centauri 🙈.

---

✨ OPTIONS ✨

aa does not accept any options 💀. Zero. None. It's giving minimalist 💅.

---

✨ FILES ✨

• ./aa.ini, ~/.aa.ini, /etc/aa.ini — Initialization data 🎀.
• /usr/share/doc/aa/readme.404 — Documentation of plan404 ephemerides 📖.
• /usr/share/aa/star.cat — Catalogue data on the 57 navigational stars ⭐.
• /usr/share/aa/messier.cat — Items for the Messier catalogue 🌌.

---

✨ SEE ALSO ✨

• conjunct(1) 🦋

---

✨ AUTHOR ✨

aa was written by Stephen L. Moshier <steve@moshier.net> 👑.

This manual page was written by James R. Van Zandt <jrv@debian.org>, for the Debian project (but may be used by others) 🫶.

---

Stay iconic, bestie! This was the AA(1) page from the Debian aa package, dated September 4, 2006 💖✨