Astrolabe: Astronomical subroutines and applications

Best Viewed With Any Browser.

Introduction

Astrolabe is a collection of subroutines and applications for calculating the positions of the sun, moon, planets and other celestial objects. The emphasis is on high accuracy over a several thousand year time span. Note that the techniques used are overkill for most calendar applications. See the FAQ, Astronomical Calculations for the Amateur for pointers to other methods which are both faster and smaller in terms of code bulk.

The subroutine library attempts to (someday) implement all the techniques described in Astronomical Algorithms, second edition 1998, by Jean Meeus, Willmann-Bell, Inc. For an alternative open-source implementation of Meeus in ANSI C, look here.

Currently there are no graphical applications apart from some demo CGI interfaces. I may add graphics in the future, but I don't intend to create a planetarium program. For a very nice open-source example of such running on Unix/Linux systems, see XEphem. Graphical software for many platforms are linked at Planetarium Software.

The Astrolabe source is licensed under the GPL, meaning it can be copied and distributed freely.

Sources

As a general rule, I have implemented all the sources in more than one language. Currently, the source languages are:

• Python
• C++

These applications are compute-intensive and are perhaps not the best use of an interpreted language like Python, but with modern hardware the Python versions perform well enough for many uses. The C++ versions are about 20-25 times faster.

The sources are available for download from the SourceForge Summary Page.

Getting started

Unpack the files into some convenient location. Everything is under a top-level directory astrolabe. If you have a previous astrolabe_params.txt, you should first copy it out of this directory tree so that your local modifications are not lost.

• Linux/Unix

  In the following examples I presume astrolabe is directly under your home directory "~".

  Edit ~/astrolabe/astrolabe_params.txt and enter your own longitude and latitude. There are some file path strings which you should modify to match your local directory structure.

  Set PYTHONPATH to include the Astrolabe library:

  export PYTHONPATH=$PYTHONPATH:~/astrolabe/lib/python

  Set a symbol to reference the Astrolabe parameter file:

  export ASTROLABE_PARAMS=~/astrolabe/astrolabe_params.txt

  Run some of the sample applications under astrolabe/apps/python.

  For C++: the makefile is in astrolabe/apps/cpp. Go to that directory and do:

  make all

• Microsoft

  Warning: My MS knowledge is years out of date. This installation method worked on NT around 2001 but I don't have more recent experience. .

  This is how I run the Python applications under NT. The example presumes astrolabe is a top-level folder on the C: drive.

  Use Start->Control Panels->System->Environment to create a new User Variable.

  Variable	Value
  ASTROLABE_PARAMS	c:\astrolabe\astrolabe_params.txt

  I believe you have to log out and in again.

  Use regedit (be careful!) to create a new key under HKEY_LOCAL_MACHINE -> SOFTWARE -> Python -> PythonCore -> 1.5 (or other version) -> PythonPath. Create a new key "astrolabe" with name = "(Default)" and value = "c:\astrolabe\lib\python".

  Run PythonWin. Edit c:\astrolabe\astrolabe_params.txt and enter your own longitude and latitude. There are some file path strings which you should modify to match your local directory structure.

  Still in PythonWin, Use File->Run to execute applications in the c:\astrolabe\apps\python folder.

  For C++: (to do: provide a makefile or workspace file [?]. Until then, create each app as a DOS console application and add the subroutine sources).

Models and accuracy

Mercury through Neptune

Model. The planetary model is VSOP87 (Variations Seculaires des Orbites Planetaires) by Bretagnon and Francou. The original model documentation, data files, and sample Fortran routines are available here. NOTE: It is not neccessary to download any data or sources from the original site. I have provided everything required. The original data files require about 4.1 MB; I have combined and reduced these to about 1.4 MB. The full accuracy of the model is retained.

Version. The VSOP model is available in several variants. I am using version "D" which produces heliocentric spherical coordinates for the equinox of date. This is the same as used in Meeus.

Accuracy. The model produces positions of better than 1 arc-second for Mercury through Mars for the years -2000 to +4000, for Jupiter and Saturn for the years 0 to +4000, and for Uranus and Neptune for the years -4000 to +8000. Within those ranges, the actual accuracies are:

	distance to Sun (km)	longitude & latitude (arc-seconds)
Mercury	0.3	0.001
Venus	2.7	0.005
Earth	3.7	0.005
Mars	22.8	0.021
Jupiter	272	0.072
Saturn	1000	0.144
Uranus	230	0.017
Neptune	1891	0.087

A note on the Meeus version. Meeus prints a truncated version of the model in his book. The first edition had an optional software supplement which included the truncated data. This supplement is no longer available, but the complete data presented here can be used instead of the version on the diskette. I use a different format.

Moon

The lunar model is Meeus's simplified version of ELP2000-82 by Chapront. The complete model can be found here. Accuracy of the simplified version is about 10 arc-seconds in longitude and 4 arc-seconds in latitude. (Over what period?)

Applications

• check_equinox: Check the accuracy of the equinox approximation routines over 4000 years.
• check_vsop87d: Test the VSOP87d calculations against the check document.
• create_binary_vsop_db: Create a binary version of the VSOP87d database.
• create_text_vsop_db: Create a text version of the VSOP87d database.
• cronus: A clock application that displays a variety of celestial events in the order they occur.
• equinox-cgi: A demo CGI interface to the Easter routine.
• solstice: Displays the instants of equinoxes and solstices for a range of years. Times are accurate to one second.
• solstice-cgi: A demo CGI interface to the Solstice and Equinox routines.
• time_vsop_db_loads: Compare the loading time of text and binary VSOp87d databases.
• validate_meeus: Validate Astrolabe routines against examples given in Astronomical Algorithms by Jean Meeus, second edition 1998, Willmann-Bell Inc.

Subroutines

I don't have separate docs for the subroutine library yet, but all the modules and functions have doc strings which should make usage pretty clear. The applications are all rather simple and studying them may be instructive.

Platforms

I've tested on these platforms:

• Python
  • Linux 2.4.20 (SuSE 8.2, i686), Python 2.4.1
• C++
  • Linux 2.4.20 (SuSE 8.2, i686), gcc versions 3.3 and 4.0.1

Notes on programming languages

Years ago, I originally wrote the astrolabe routines in C. Now, I always implement in Python first, then make a C++ version as a more-or-less direct translation. The C++ source has a lot of compromises required for compatability with different compilers, which are, however, getting closer to the standard with time.

The Python sources are obviously more compact than the C++ versions and have less declarative overhead. To me, the most unfortunate aspects of C++ are:

• STL containers cannot have initialization lists, meaning that inline data must first be held in C-arrays, then copied to the containers at run-time. I use some macros to make this a bit more natural-looking.
• Template arguments cannot be local types. That means STL containers must use types declared at an outer scope, which is ugly.
• Functions may not return multiple values. Where Python can have:

  ra, dec = func()

  C++ requires:

  void func(double &ra, double &dec);
  double ra, dec;
  func(ra, dec);

  ...or a struct for a return value, which would require more declarations. In an alternative C-like language, this would be just as strongly-typed as the function shown above:

  double, double func();
  double ra, double dec = func();

To do

Add automated configure scripts for C++ compilation and installation.

Improve the lunar model, perhaps with the complete Chapront ELP2000-82.

Add more material from Meeus:

• Add a model for Pluto.
• Add year-by-year polynomial model for planets Jupiter through Neptune.
• Add perihelion/aphelion routines for the planets, and perigee/apogee routines for the Moon.
• Look at adjustable truncation of the VSOP model to trade accuracy for time.

Fix a bug in the Rise-Set-Transit code which causes events around 0hr UT to be dropped.

Fix a bug in cronus.py that causes equinox/solstice events to be reported out of order on that day. (The displayed values are correct, though).

Improve the param file parsing so people can enter their longitude and latitude more naturally.

Extend the Python code with C modules performing the expensive computations.

(or...) Make a CORBA version of the subroutine library in C++.

Change history

version	date
0.5	2005-Jul-4	Brought the code up to date to use new Python features and repair C++ damage caused by evolving gcc compliance. Added a few recent deltaT values.
0.4	2001-Jul-9	Added GPL license text; no code changes.
0.3	2001-May-21	Added equinox-cgi and solstice-cgi CGI interfaces. Plus minor format cleanup in the C++ applications.
0.2	2000-Oct-1	Added C++ version, small bug fixes.
0.1	2000-Sep-3	First version on SourceForge

Bill McClain's Home Page

Sattre Press

Hosted by: