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.
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
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=somethingSetting a city this way allows
solunar to be run without
arguments, to get today's timings.
$ 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 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 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 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.
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.
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 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.
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.
solunar program:
solunar refers to as the "syslocal" timezone);solunar refers
to this as the "local" timezone, and is distinct from the syslocal
timezone).-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 converion 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.
-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.solunar has no Unix/Linux man page as yet --
vounteers to write one are most welcome.% make % sudo make installNote 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 plaforms, perhaps with changes to the Makefile.
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.
--syslocal switch; various bug fixes.
Version 0.1.3a, January 2016solunar 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 alway be
more recent than any pre-built binaries, and include the latest bug
fixes, some of which are important.