public ArrayList EventTimes( EventType TypeofEvent, int Day, int Month, int Year, double SiteLatitude, double SiteLongitude, double SiteTimeZone )
Public Function EventTimes ( TypeofEvent As EventType, Day As Integer, Month As Integer, Year As Integer, SiteLatitude As Double, SiteLongitude As Double, SiteTimeZone As Double ) As ArrayList
public: virtual ArrayList^ EventTimes( EventType TypeofEvent, int Day, int Month, int Year, double SiteLatitude, double SiteLongitude, double SiteTimeZone ) sealed
|InvalidValueException||If the combination of day, month and year is invalid e.g. 31st September.|
The definitions of sunrise, sunset and the various twighlights that are used in this method are taken from the US Naval Observatory Definitions.
The dynamics of the sun, Earth and Moon can result at some latitudes in days where there may be no, 1 or 2 rise or set events during a 24 hour period; in consequence, results are returned in the flexible form of arraylist.
The returned zero based arraylist has the following values: Arraylist(0) - Boolean - True if the body is above the event limit at midnight (the beginning of the 24 hour day), false if it is below the event limitArraylist(1) - Integer - Number of rise events in this 24 hour periodArraylist(2) - Integer - Number of set events in this 24 hour periodArraylist(3) onwards - Double - Values of rise events in hours Arraylist(3 + NumberOfRiseEvents) onwards - Double - Values of set events in hours
If the number of rise events is zero the first double value will be the first set event. If the numbers of both rise and set events are zero, there will be no double values and the arraylist will just contain elements 0, 1 and 2, the above/below horizon flag and the integer count values.
The algorithm employed in this method is taken from Astronomy on the Personal Computer (Montenbruck and Pfleger) pp 46..56, Springer Fourth Edition 2000, Fourth Printing 2009. The day is divided into twelve two hour intervals and a quadratic equation is fitted to the altitudes at the beginning, middle and end of each interval. The resulting equation coefficients are then processed to determine the number of roots within the interval (each of which corresponds to a rise or set event) and their sense (rise or set). These results are are then aggregated over the day and the resultant list of values returned as the function result.
High precision ephemeredes for the Sun, Moon and Earth and other planets from the JPL DE421 series are employed as delivered by the ASCOM NOVAS 3.1 component rather than using the lower precision ephemeredes employed by Montenbruck and Pfleger.
Accuracy Whole year almanacs for Sunrise/Sunset, Moonrise/Moonset and the various twighlights every 5 degrees from the North pole to the South Pole at a variety of longitudes, timezones and dates have been compared to data from the US Naval Observatory Astronomical Data web site. The RMS error has been found to be better than 0.5 minute over the latitude range 80 degrees North to 80 degrees South and better than 5 minutes from 80 degrees to the relevant pole. Most returned values are within 1 minute of the USNO values although some very infrequent grazing event times at lattiudes from 67 to 90 degrees North and South can be up to 10 minutes different.
An Almanac program that creates a year's worth of information for a given event, lattitude, longitude and timezone is included in the developer code examples elsewhere in this help file. This creates an output file with an almost identical format to that used by the USNO web site and allows comprehensive checking of acccuracy for a given set of parameters.