Astronomy Engine

Supported Programming Languages

C	Examples	Code & Docs
C#	Examples	Code & Docs
JavaScript	Examples Browser Node.js	Code & Docs
Python	Examples	Code & Docs
Kotlin / JVM	Examples Kotlin Java	Code & Docs

Overview

Astronomy Engine is a suite of open source libraries for calculating positions of the Sun, Moon, and planets, and for predicting interesting events like oppositions, conjunctions, rise and set times, lunar phases, eclipses, transits, and more.

It supports several popular programming langauges with a consistent API. Function and type names are mostly consistent across all the supported languages.

Astronomy Engine is designed to be small, fast, and accurate to within ±1 arcminute. It is based on the authoritative and well-tested models VSOP87 and NOVAS C 3.1.

These libraries are rigorously unit-tested against NOVAS, JPL Horizons, and other reliable sources of ephemeris data. Calculations are also verified to be identical among all the supported programming languages.

Features

• Provides calculations for the Sun, Moon, Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, Neptune, and Pluto.

• Calculates all supported objects for any calendar date and time for millennia before or after the present.

• Provides heliocentric and geocentric Cartesian vectors of all the above bodies.

• Determines apparent horizon-based positions for an observer anywhere on the Earth, given that observer's latitude, longitude, and elevation in meters. Optionally corrects for atmospheric refraction.

• Calculates rise, set, and culmination times of Sun, Moon, and planets.

• Finds civil, nautical, and astronomical twilight times (dusk and dawn).

• Finds date and time of Moon phases: new, first quarter, full, third quarter (or anywhere in between as expressed in degrees of ecliptic longitude).

• Predicts lunar and solar eclipses.

• Predicts transits of Mercury and Venus.

• Predicts lunar apogee and perigee dates, times, and distances.

• Predicts date and time of equinoxes and solstices for a given calendar year.

• Determines apparent visual magnitudes of all the supported celestial bodies.

• Predicts dates of planetary conjunctions, oppositions, and apsides.

• Predicts dates of Venus' peak visual magnitude.

• Predicts dates of maximum elongation for Mercury and Venus.

• Calculates the positions of Jupiter's four largest moons: Io, Europa, Ganymede, and Callisto.

• Allows custom simulation of the movements of user-defined small bodies, such as asteroids and comets, through the Solar System.

• Converts angular and vector coordinates among the following orientations:

  • Equatorial J2000
  • Equatorial equator-of-date
  • Ecliptic J2000
  • Topocentric Horizontal
  • Galactic (IAU 1958)

• Determines which constellation contains a given point in the sky.

• Calculates libration of the Moon.

• Calculates axis orientation and rotation angles for the Sun, Moon, and planets.

Why I Created This Thing

I have been an amateur astronomer since childhood. I still remember the amazement I felt when I saw Saturn through a backyard telescope for the first time. As a software developer, I naturally became interested in combining my love of astronomy with my computer programming skills.

In 2008, I started to learn about formulas for calculating positions of the Moon and planets. I discovered many wonderful resources, including

• Paul Schlyter's lucid and educational page How to compute planetary positions.
• Practical Astronomy with your Calculator, third edition, by Peter Duffett-Smith, Cambridge University Press. ISBN 0 521 35629 6.
• Astronomy on the Personal Computer by Oliver Montenbruck and Thomas Pfleger. ISBN-13: 978-3540672210.

I implemented algorithms based on these resources. Over time, however, I noticed that they were not quite as accurate as I would like. Their calculated positions differed from those reported by online tools like JPL Horizons and Heavens Above by large fractions of a degree in many cases.

In 2019 I renewed my interest in astronomy calculations, with the goal of creating something more accurate that could be written in JavaScript to run inside a browser. I studied how professional astronomers and space agencies did their calculations. First I looked the United States Naval Observatory's NOVAS C 3.1 library. I quickly realized it could not be ported to the browser environment, because it required very large (hundreds of megabytes) precomputed ephemeris files.

This led in turn to studying the French Bureau des Longitudes model known as VSOP87. It requires more computation but the data is much smaller, consisting of trigonometric power series coefficients. However, it was still too large to fit in a practical web page.

Furthermore, these models were extremely complicated, and far more accurate than what I needed. NOVAS, for example, performs relativistic calculations to correct for the bending of light through the gravitational fields of planets, and time dilation due to different non-intertial frames of reference! My humble needs did not require this herculean level of complexity. So I decided to create Astronomy Engine with the following engineering goals:

• Support JavaScript, C, C#, and Python with the same algorithms, and verify them to produce identical results. (Kotlin support was added in 2022.)
• No external dependencies! The code must not require anything outside the standard library for each language.
• Minified JavaScript code less than 120K. (The current size is 116485 bytes.)
• Accuracy always within 1 arcminute of results from NOVAS.
• It would be well documented, relatively easy to use, and support a wide variety of common use cases.

The solution I settled on was to truncate the VSOP87 series to make it as small as possible without exceeding the 1 arcminute error threshold. I created a code generator that converts the truncated tables into C, C#, JavaScript, and Python source code. Then I built unit tests that compare the calculations against the NOVAS C 3.1 code operating on the DE405 ephemeris and other authoritative sources, including the JPL Horizons tool. Basing on VSOP87 and verifying against independent trusted sources provides extra confidence that everything is correct.

Pluto was a special case, because VSOP87 does not include a model for it. I ended up writing a custom gravitation simulator for the major outer planets to model Pluto's orbit. The results are verified against NOVAS and the model TOP2013.

As far as I know, Astronomy Engine is the only open source solution in existence that combines very compact code for four major programming languages with such rigorous validation and testing at a reasonable accuracy threshold. The 1-arcminute accuracy is not good enough for spacecraft navigation, but it is good enough for most amateur uses, and allows the code to be much simpler, faster, and smaller.

I am committed to maintaining this project for the long term, and I am happy to answer questions about how to solve various astronomy calculation problems using Astronomy Engine. Feel free to reach out on the discussions page or submit a new issue.

Acknowledgements