sun: A Quartus Forth 2.0 Library Module for Calculating Sunrise and Sunset
Neal Bridges, August 2005.  support@quartus.net
--------------------------------------------------------------------------
Quartus Forth is an on-board compiler for PalmOS handhelds.
http://www.quartus.net/products/forth
--------------------------------------------------------------------------

The sun library module provides words for calculating sunrise/sunset times
for a specified latitude/longitude.  The times are available both in UTC and
in the local timezone selected in Preferences on each PalmOS (v4 and
greater) device.

The source algorithm for the time calculation is from:

  Almanac for Computers, 1990
  Published by the Nautical Almanac Office
  United States Naval Observatory
  Washington, DC 20392.

Online:
  http://williams.best.vwh.net/sunrise_sunset_algorithm.htm
  Local copy: sunrise_sunset_algorithm.htm

This algorithm is valid for the years 1980-2050, and is generally accurate
to within a minute.  Accuracy degrades when the location is further north or
south than 60 degrees of latitude; above 80 degrees of latitude, small
inaccuracies in the calculation of the sun's ecliptic will result in greater
errors in the time of sunrise and sunset.

The sun library module uses Quartus Forth internal single-precision floats.
MathLib is not required for this module.


Requirements:

- Quartus Forth 2.x (or higher)
- A PalmOS 4 (or higher) device (because of the use of timezone & DST
prefs).


Provides:

  set-location ( F: longitude latitude -- )
Sets the location used by the sunrise/sunset words below.  West longitudes
and south latitudes are negative; east longitudes and north latitudes are
positive.

  set-zenith ( F: zenith -- )
Sets the zenith used by the sunrise/sunset words below.  Applicable named
zenith words are provided, as follows:
  astronomical-zenith ( -- )
  civil-zenith ( -- )
  nautical-zenith ( -- )
  official-zenith ( -- )  The default when sun is loaded.
Each of these sets a value for zenith.

  rising ( -- rising-flag )
  setting ( -- setting-flag )
These flags control whether UTC-suntime calculates sunrise, or sunset.

  UTC-suntime ( day month year set? -- ) ( F: -- h.m )
Calculates the time of the rising or the setting of the sun for the current
location on the specified date, using the current zenith.  The value
returned is a floating-point hour.minute in UTC (GMT timezone).  set? must
be either rising or setting.
If the sun does not rise or set at the selected lat/long on the given day,
-11 (result out of range) is thrown during the time calculation.  Use CATCH
to trap that as required.

  sunrise ( day month year -- ) ( F: -- h.m )
  sunset ( day month year -- ) ( F: -- h.m )
These return sunrise and sunset, respectively, for the current location on
the specified date, using the current zenith, corrected for local time using
the Palm preferences settings for timezone and daylight-savings.  The value
returned is a floating-point hour.minute.

  time>mh ( F: h.m -- ) ( -- m h )
Converts a floating point hour.minute value into minute and hour integers on
the stack.

  day-of-year ( day month year -- day-of-year )
Computes the day number for the specified date.  January 1=1, January 2=2,
etc.  The year is only used to determine leap-year status.


Library module dependencies for sun:

  needs calendar
  needs ftrig2
  needs opg
  needs tester

Notes:

ftrig2 is a new library module since the initial Quartus Forth 2.0.0
release, requiring the most recent version of fatan (05.8.9 or later).
These can be found with ( as can all updated library files) at
http://www.quartus.net/files/PalmOS/Forth/Library/.

tester must be the most recent version (05.8.9 or later).

Wil Baden's excellent OPG library module allows infix notation, to keep the
calculation source similar in format to the original algorithm description.


Example of use:

 -79.4e 43.6e set-location
 ( west longitudes and south latitudes are negative )
 official-zenith
 21 August 2005 sunrise time>mh . .
 1 July 1990 sunset time>mh . .

--
support@quartus.net
http://www.quartus.net
