• Utility corner
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 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.
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
Date: Monday 21 May 2012
Moon phase: 0.02 new
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
underscores, as spaces confuse the shell; so -c los_angeles.
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 default timezone:
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,
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
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:
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
For a full list of command-line switches:
-t, --twelvehour: use 12-hour (AM/PM) format for times, rather than
-u, --utc: use UTC (essentially GMT) 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.
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
mmonset. 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 folliage 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
Date: Friday 6 September 2013
Sunrise: 6:20 am
Sunset: 7:35 pm
Moon phase: 0.04 new
Moonrise: 7:30 am
Moonset: 7:35 pm
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 inflence, only
its central time. The variation in duration and intensity can be
considerable. For more detail, use the -f or --full
switches in conjuction 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 maximums
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 coincdences
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.
# make install
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
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
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.
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
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.
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
- 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
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 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
solunar is copyright (c)2005-2014 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
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.
Version 0.1.0, May 2012
First release, based on the original Java implementation of
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.
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.
An Android app
is available which displays a subset
of the data producted by this program, and is based on the same
A command line version for Android is available from the
KBOX downloads page.