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

RETIRED!

Please note that this utility is obsolete, and I won't be developing it any further, or fixing any more bugs. I've started an entirely new implementation, which is avilable here:

https://github.com/kevinboone/solunar2

Thanks to everybody who tested and contributed to this version over the years.

Version 0.1.3d

solunar is a simple, command-line utility for rapidly displaying sun- and moon-related data such as sunset times and equinoxes. It also attempts to predict the combined influence of the sun and moon on wildlife activity. This process -- sometimes called solunar scoring or solunar forecasting can be useful to people with an interest in fishing, wildlife photography, and birdwatching. solunar 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 calendar events like 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
                      Moonrise: 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. Note that city names containing spaces are represented in solunar with underscores, as spaces confuse the shell; so -c los_angeles (but, int fact, 'angeles' will work, since it is unambiguous)

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

solunar -c paris -d "jan 1"

Get more detailed information:

solunar -f -c paris -d "jan 1"

Get brief information for location 51.0 degrees north, 1.5 degrees west, with times appropriate for the "syslocal" timezone (see 'Note on timezones' below):

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.

When a city name is given using the -c switch, the times displayed are local to the timezone in which that city is located. When latitude and longitude are given alone, then times displayed are in the syslocal timezone -- usually the timezone set in the TZ environment variable, or UTC if no timezone is set. The syslocal timezone will be used whether or not the specified location happens to be in that timezone -- this may well be unhelpful if you need to know the times local to that location, when you are in another, different location. solunar has no general way to work out what timezone a specified lat/long location is in. To get local times for a lat/long location, give the -c switch along with -l, naming a city in the required timezone. For example, the city database has no entry for Washington, DC. The following command specifies the Washington DC lat/long coordinates, but displays the results for the syslocal timezone:

solunar -l 38.90,-77.03

The same command additionally using the name of a nearby city (at least, close enough to be in the same timezone) displays local times for Washington, DC:

solunar -l 38.90,-77.03 -c New_York

solunar -l 38.90,-77.03 --syslocal

You can also force the use of GMT/UTC times using the --utc switch.

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

RC file

If the file $HOME/.solunar.rc exists, it will be read for configuration. Values set in the file can be overridden by the command line. At present, the only configuration that is read is

city=something

Setting a city this way allows solunar to be run without arguments, to get today's timings.

Useful switches

-t, --twelvehour: use 12-hour (AM/PM) format for times, rather than 24-hour times.

-u, --utc: use UTC (essentially GMT) times for input and output.

-y, --syslocal: use system local times for input and output.

-c, --cities: list cities in database.

-s, --solunar: show solunar scoring information (see below).

--datetime help: show a summary of date/time input formats.

Solunar scoring

The influence of the sun and moon on animal activity -- particularly feeding activity -- is frequently noted, but not particularly well understood. It is widely accepted that many animals are most active at times near the full and new moons and, within a particular day, at dawn and dusk. It also seems to be the case that animal activity is greatest during moon transits (when the moon is directly overhead or directly 'underfoot') and, to a lesser extent, at moonrise and moonset. The Sun's being at its highest point may also be significant, because this is when the light and heat from the Sun is most likely to penetrate foliage and water, to warn the ground or river beds.

It is often surmised that good times for birdwatching, fishing, etc., will be when the significant events related to the sun and moon coincide -- for example, when the moon is directly overhead at dusk. There is little experimental data to support this surmise, but there is enough anecdotal evidence to make it interesting.

To display solunar scoring information, use the -s or --solunar switches. An example of the output is as follows:

$ solunar -s -c london -t
Selected city Europe/London
Using location 51:30N,000:07W
Date/time Fri Sep  6 15:01:53 2013 local

Today
                          Date: Friday  6 September 2013

Sun
                       Sunrise:  6:20 am
                        Sunset:  7:35 pm

Moon
                    Moon phase: 0.04 new
                      Moonrise:  7:30 am
                       Moonset:  7:35 pm

Solunar
              Moon phase score: 89%
           Moon distance score: 56%
     Solunar coincidence score: 59%
            Solunar peak times:  6:45 am  1:15 pm  7:45 pm
         Overall solunar score: 68%

The moon phase score is a figure indicating how favourable the moon phase is to wildlife activity. This has a maximum of 100% at full and new moons, and declines gradually to (a completely arbitrary) 25% at the moon quarters. The moon distance score estimates the effect of the closeness of the moon to the earth, with a figure of 100% at perigee and (again, arbitrarily) 25% at apogee. Solunar coincidence score is a measure of the overlap between sun-related and moon-related events on the specified day. It is difficult to predict the upper limit of this figure; by experiment the algorithm's parameters have been adjusted to give a figure of 100% on days where there is the greatest observed overlap between sun and moon influence. On some days, this figure will be zero; this will happen when, for example, sun rise/set/transit times are completely different from moon rise/set/transit times. The final figure, the overall score, is the unweighted average of the three previous scores.

The solunar peak times shows the times, if any, of the peak overlap between sun and moon influence scores. This figure does not indicate the duration or intensity of the overlapping influence, only its central time. The variation in duration and intensity can be considerable. For more detail, use the -f or --full switches in conjunction with --solunar. This will display a chart of the Sun, Moon, and combined influence at 30-minute intervals for the day. From this the length and intensity of the combined influence should be clear.

Note that the levels of sun and moon influence in the chart, and used to derive the solunar peak times display, are relative to the maxima for that day. That is, the solunar coincidence score could high, and several peak times shown, but the day could still be inauspicious because the moon is at apogee (for example). Solunar coincidences might be of interest in predicting the level of wildlife activity on a specified day, but that doesn't mean that there will be an overall high level of activity on that day.

There is little science to solunar scoring. The program's algorithm has been tuned to give results that are broadly comparable with several published almanacs that claim to offer such scoring.

Notes on the calculations

With the exception of solunar scoring, 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 constitutes sunset (and similar considerations for the moon.) 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 astronomical 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.

Although there will always be at most one sunset on a given day, and one sunrise, there can be zero, one, or two moonrises and sets. So to capture all these events we have to consider the position of the moon at a series of time intervals, and then determine the horizon-crossing points, interpolating if necessary (at least, I have not been able to find a better way to do this). This means that there is even more scope for disagreement in lunar event times than solar events. Published sources seem to vary by +/- ten minutes or so.

Solunar scoring -- estimating the influence of sun and moon on wildlife activity -- is highly speculative, with little scientific justification. The algorithms used by solunar for this purpose are not based on any particular science -- there isn't any -- but have been tuned to produce output that is broadly comparable with other published solunar tables.

A note on timezones

There are three timezones that are of potential interest to the solunar program:

• The timezone in which the host computer believes it is located (which solunar refers to as the "syslocal" timezone);
• The UTC (GMT) timezone, in which all calculations are carried out; and
• The timezone of some selected location (solunar refers to this as the "local" timezone, and is distinct from the syslocal timezone).

In general, if a particular city is selected (-c switch), then the timezone of that city is used both to parse input dates, and to adjust output times to that location. If the --utc switch is given, then input and output are UTC times. If --syslocal is given, then input and output will be system local, including allowance for daylight savings, even if a city is specified. So, for example, using -c and --syslocal together allow solunar to answer questions like "What time is it here, when it is sunset in Paris?<.

If no city is specified, but only a location (latitude/longitude), then input and output will be system local, unless --utc is specified.

Internally, "syslocal" is interpreted as meaning "apply no particular timezone conversion beyond what the algorithms insist on." The results are platform-dependent to some extent but, in practice, both Linux and Cygwin both take the working timezone from the TZ environment variable, if it is set, or the file /etc/localtime if it exists, or UTC if neither is present.

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. The times shown for events that have a time (equinoxes, for example) will be system-local unless you specify a city (-c) or specify UTC times (--utc).
• solunar will tell you what time it currently is in a different location if you specify a city, but it won't tell you (for example) what UK time corresponds to 9:30 AM in Los Angeles -- it 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. So, for example, the distance from the earth to the moon will be given at 2AM on the specified day. In practice, this seems highly unlikely to be significant. The use of 2AM, rather than midnight should reduce the likelihood of a nasty surprise when selecting a day at the boundary between daylight savings changes: midnight local time might end up being in an unexpected day.
• solunar has no Unix/Linux man page as yet -- volunteers to write one are most welcome.

Compiling

Source code is available from github. You can check out the latest version, or download and unpack a ZIP file. Then the usual:

% make
% sudo make install

Note that solunar uses GNU-cc specific methods of handling time and date. 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. It will also build on an Android device that has a GCC compiler. Of course, this is only useful if you routinely use the command prompt on Android. For OS/X, you might need to use the alternative Makefile.OSX. solunar may build on other Posix-like platforms, perhaps with changes to the Makefile.

Legal

solunar is copyright (c)2005-2019 Kevin Boone, and is released under the GNU Public Licence, version 3.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.

Revision history

Version 0.1.0, May 2012
First release, based on the original Java implementation of 2005-2011.

Version 0.1.1, June 2013
Fixed incorrect text label on moonset.
Fixed a problem with TZ environment handling, that led to a hugely incorrect timezone compensation on some platforms.</br/> Added 12-hour time display.
Added solunar scoring feature.
Fixed some minor memory leaks.
Corrected some errors in the documentation.

Version 0.1.2, June 2014

Fixed a problem with timezone handling that caused the wrong day to be used between midnight and 1AM during daylight savings time.

Version 0.1.2a, March 2015

Fixed bug in name parsing in parse_zoneinfo.pl (thanks to Cezary Kruk)

Version 0.1.3, January 2016

Added --syslocal switch; various bug fixes.

Version 0.1.3a, January 2016

Fixed a bug in working out when a day started and ended, that affected mostly pacific timezones. Tidied up the display of the "Today" date. Made system local the default timezone for situations where a location (lat/long) is given, but no city -- this seems to be what users prefer.

Version 0.1.3b, May 2017

Tidied up Makefile, so that it respected CFLAGS and LDFLAGS environment variables. This is to make it easier to cross-compile.

Version 0.1.3c, December 2018

Fixed summer/winter naming to depend on hemisphere of selected location.

Version 0.1.3d, November 2019

Preliminary RC file support. Tidied up some printf() usages that caused complaints from modern GCC versions.

Downloads

solunar is already in the repositories for various Linux distributions. Where that is not the case, it is easy to build from source. Please note that the latest source will nearly always be more recent than any pre-built binaries, and include the latest bug fixes, some of which are important.