Next / Previous / Contents / Shipman's homepage


This document describes, a Python module to perform spherical geometry calculations for astronomical applications.

This publication is available in Web form and also as a PDF document. Please forward any comments to

This work is licensed under a Creative Commons BY-NC Creative Commons Attribution-NonCommercial 3.0 Unported License.

Table of Contents

1. Introduction
2. Downloadable files
3. Coordinate systems used
3.1. Terrestrial coordinates
3.2. Altazimuth coordinates
3.3. Equatorial coordinates
4. Standalone scripts
4.1. Specifying dates and times on command lines
4.2. Specifying angles on command lines
4.3. Specifying latitude and longitude on command lines
4.4. Specifying hours on command lines
4.5. jd: Convert to Julian date
4.6. conjd: Convert from Julian date
4.7. mjd: Convert to modified Julian date
4.8. conmjd: Convert from modified Julian date
4.9. rdaa: Equatorial to horizon coordinates
4.10. aard: Horizon to equatorial coordinates
5. Constants
6. Functions
6.1. hoursToRadians(): Convert hours to radians
6.2. radiansToHours(): Convert radians to hours
6.3. hourAngleToRA(): Convert an hour angle to right ascension
6.4. raToHourAngle(): Convert a right ascension to an hour angle
6.5. dayNo(): Date to day number
6.6. parseDatetime(): Parse external date/time
6.7. parseDate(): Parse external date
6.8. parseTime(): Parse external time
6.9. parseAngle(): Parse external angle
6.10. parseLat(): Parse latitude
6.11. parseLon(): Parse longitude
6.12. parseHours(): Parse a quantity in hours
7. class MixedValue: Handling mixed unit systems
7.1. MixedValue.__init__(): Constructor
7.2. MixedValue.__float__()
7.3. MixedValue.format()
8. class LatLon: Terrestrial position
8.1. LatLon.__init__(): Constructor
8.2. LatLon.__str__(): Convert to a string
9. class JulianDate: Julian date and time
9.1. JulianDate.__init__(): Constructor
9.2. JulianDate.__float__(): Convert to float
9.3. JulianDate.datetime(): Convert to a datetime instance
9.4. JulianDate.offset(): Move a time by some number of days
9.5. JulianDate.__sub__(): Find the difference between two times
9.6. JulianDate.__cmp__(): Comparison
9.7. JulianDate.fromDatetime(): Convert a datetime
10. class MJD: Modified Julian date
10.1. MJD.__init__(): Constructor
10.2. MJD.__float__(): Convert to a float
10.3. MJD.datetime(): Convert to a datetime instance
10.4. MJD.offset(): Add a number of days
10.5. MJD.__sub__(): Find the difference between two modified Julian dates
10.6. MJD.__cmp__(): Comparator
10.7. MJD.fromDatetime(): Convert a datetime
11. class SiderealTime
11.1. SiderealTime.__init__(): Constructor
11.2. SiderealTime.__str__(): Convert to a string
11.3. SiderealTime.utc(): Find Universal Time
11.4. SiderealTime.gst(): Local Sidereal Time to Greenwich Sidereal Time
11.5. SiderealTime.lst(): Greenwich Sidereal Time to Local Sidereal Time
11.6. SiderealTime.fromDatetime(): Convert UTC to GST
12. class AltAz: Horizon coordinates
12.1. AltAz.__init__(): Constructor
12.2. AltAZ.raDec(): Convert horizon to equatorial coordinates
12.3. AltAz.__str__(): Convert to a string
13. class RADec: Equatorial coordinates
13.1. RADec.__init__(): Constructor
13.2. RADec.hourAngle(): Find the hour angle of an equatorial coordinate
13.3. RADec.altAz(): Convert to horizon coordinates
13.4. RADec.__str__(): Convert to a string

1. Introduction

The package is designed to do a few of the simpler astronomical calculations. The mathematical basis of these calculations comes from spherical trigonometry.

Here is the source for formulae used in this package:

Duffett-Smith, Peter. Practical astronomy with your calculator. Second edition. Cambridge, 1981, ISBN 0-521-28411-2.

The reader is assumed to know the Python programming language.


All astronomical computations are approximations. Refer to Duffett-Smith's book for a discussion of the limitations of these formulae. In particular, they assume that the Earth is a sphere, which it isn't quite.

The actual implementation of this module is shown in the companion document, Internal maintenance specification, in lightweight literate programming form.