Function that returns a list of rise and set events of a particular type that occur on a particular day at a given latitude, longitude and time zone

Namespace: ASCOM.Astrometry.AstroUtils
Assembly: ASCOM.Astrometry (in ASCOM.Astrometry.dll) Version: 6.0.0.0 (6.1.1.2619)

Syntax

C#
public ArrayList EventTimes(
	EventType TypeofEvent,
	int Day,
	int Month,
	int Year,
	double SiteLatitude,
	double SiteLongitude,
	double SiteTimeZone
)
Visual Basic
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
Visual C++
public:
virtual ArrayList^ EventTimes(
	EventType TypeofEvent, 
	int Day, 
	int Month, 
	int Year, 
	double SiteLatitude, 
	double SiteLongitude, 
	double SiteTimeZone
) sealed

Parameters

TypeofEvent
Type: ASCOM.Astrometry..::..EventType
Type of event e.g. Sunrise or Astronomical twighlight
Day
Type: System..::..Int32
Integer Day number
Month
Type: System..::..Int32
Integer Month number
Year
Type: System..::..Int32
Integer Year number
SiteLatitude
Type: System..::..Double
Site latitude
SiteLongitude
Type: System..::..Double
Site longitude (West of Greenwich is negative)
SiteTimeZone
Type: System..::..Double
Site time zone offset (West of Greenwich is negative)

Return Value

An arraylist of event information (see Remarks for arraylist structure).

Remarks

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.

Exceptions

ExceptionCondition
ASCOM..::..InvalidValueExceptionIf the combination of day, month and year is invalid e.g. 31st September.

See Also