Solunar - a simple command-line utility for calculating Sun and Moon rise and set, and related times

solunar is a simple, command-line utility for rapidly displaying sun- and moon-related data, such as sunset times and equinoxes. It builds under Cygwin on Windows, and on most Linux platforms. solunar produces output that can be readily parsed by scripts, although it is reasonably human-readable. The utility contains a database of city locations, so locations can be specified by name, rather than latitude and longitude, although specific latitude and longitude can also be specified if required.

Solunar can also calculate the dates of lunar-related events such as Easter.

Basic usage

Get sun and moon rise and set times, etc., in London, on the current day:

$ solunar -c london
Selected city Europe/London
Using location 51:30N,000:07W
Date/time Mon May 21 13:52:52 2012 local

Today
                          Date: Monday 21 May 2012

Sun
                       Sunrise: 04:59
                        Sunset: 20:52

Moon
                    Moon phase: 0.02 new
                       Moonset: 05:10
                       Moonset: 21:36

Partial city names can be given, so long as the name is unambiguous. To see a full list of city names, run solunar --cities.

Get sun and moon rise and set times, etc., in Paris, on January 1st, this year:

solunar -c paris -d "jan 1"

Get detailed information for location

solunar -c paris -d "jan 1"

Get brief information for location 51.0 degrees north, 1.5 degrees west:

solunar -l 51.0,-1.5 -d "jan 1"

Note that southerly latitudes are negative, as are westerly longitudes. For more information on the accepted lat/long formats, run solunar -l help. Note also that when latitude and longitude are given, the times displayed are in the default timezone, whether or not the specified point is in that timezone. If it isn't, you probably need to use the -u switch to get the times in UTC, then convert appropriately. In practice, the use of -c to set a city is more convenient, unless there really is no city within a hundred miles or so of the location.

To get a list of equinoxes, etc., for the current year:

solunar --days

This also displays the dates of festivals like Easter which are derived from the lunar calendar. However, this dating of Easter is the conventional Western one, and not all locations observe the same date, even when they observe Easter.

For a full list of command-line switches:

solunar --longhelp

Compiling

The usual:

% make
# make install

Note that solunar uses GNU-cc specific methods of handling time and date, and requires a Posix timezone database. Consequently it won't build under MinGW (and won't work even if it can be made to build). Interestingly it will build for Android using the Native Development Kit, and does seem to work correctly. Of course, that's only useful if you routinely use the command prompt on Android. solunar may build on other Posix-like plaforms, perhaps with changes to the Makefile.

Notes on the calculations

The calculations are all based on published algorithms, and I have checked them against reliable data sources so far as possible. There are potential sources of error that the program can't control, and some issues of interpretation.

The most troublesome potential source of error is the system's timezone database. By default, results are worked out in UTC and then converted to the local time of the specified city. This relies on the system's own time and date being correct, and having a proper understanding of daylight savings changes. In general, these issues seems to be handled reasonably well in modern Linux distributions, but there's not much solunar can do if the platform data is incorrect.

Issues of interpretation include those relating to uncertainty about exactly what position of the sun in the sky constitudes sunset. The sun is not a uniform disc, so there has to be a convention for the angle of zenith that we take as sunset. Most publications that give sunset times seem to take the Zenith angle as 90 degrees and 50 minutes, so solunar does the same. However, the --full switch will make it display sunset according to other popular zeniths. In particular, civil twilight has a zenith 6 degrees below conventional sunset, and denotes the time before which outdoor activities are reasonably practicable. Nautical and astonomical twilight have zeniths 12 and 18 degrees below conventional sunset. In practice, many parts of the world will experience no astronomical sunset for at least part of the year. Some, of course, experience no sunset at all for part of the year.

Limitations

Events like equinoxes are displayed to the nearest minute but, in fact, it's hard to get an accuracy of better than 30 minutes or so. These are annual events, after all.
The --days switch produces a list for the current year. To get a list for a different year, you will need to specify a full date in that year, even though only the year part will be used.
Times are displayed either as UTC, or local to the specified city. There is no way to get the times of events in one location relative to a different one. solunar is not intended to be a general timezone converter.
If a date is specified but no time, then the time is taken to be 2AM, local time. So, for example, the distance from the earth to the moon will be given at 2AM on the specificed day. In practice, this seems highly unlikely to be significant. The use of 2AM, rather than midnight, is so the user is less likely to be surprised when selecting a day at the boundary between daylight savings changes. Midnight local time might end up being in an unexpected day.

Legal

solunar is copyright (c)2005-2012 Kevin Boone, and is released under the GNU Public Licence, version 2.0. That means, essentially, that you are welcome to use this program however you see fit, at your own risk, so long as you do not redistribute it without acknowledging the original author.

The algorithms used in the program are published in various textbooks and, so far as I know, there are no particular legal restrictions on their use and distribution.