Glossary Confused by computer jargon? Look it up!

Shameless plug Now available!

Articles - Ten-minute guide to setting up a WAP site - Talk like your boss: new developments in managerese - More...

Development -  File handling in the Linux kernel -  Java development for the Sony-Ericsson P800 - SunONE Application Server 7 FAQ - More...

Linux -  Using Linux with the Treo 600 - Linux on the Tecra M1 - Some notes on openzaurus - More...

Download - Java stuff - Linux stuff - More... (Please read the download policy)

Home automation - The X10 system - Linux TW723 driver - More...

The K-Zone - K-Zone computing - K-Zone law - K-Zone education and science - K-Zone motorcycles - K-Zone DIY - K-Zone railways - K-Zone martial arts - About the author - K-Zone home page

Download	Computing	Wallet	JavaChimes	JCalc
PhotoIndex	JavaPopt	FileGate	MailGate
MP3 Web interface	jmix

`suntimes' is a Java package that contains Java classes for calculating sunrise and sunset times, and related information, anywhere in the World and on any date. It includes a simple command-line program for carrying out these calculations on the command line, and a Web application based on Java Server Pages (JSPs). The calculation engine contains full Javadoc documentation. For a live demonstration, Click here.

SunTimes class and command-line client

SunTimes class

Usage

import com.web_tomorrow.util.suntimes.*;
Time t = getSunriseTimeUTC
  (year, month, day, longitude, lattitude, SunTimes.ZENITH);
System.out.println ("Sunrise is at " + t + " UTC");

Note that to calculate the sunrise or sunset time we need the exact date and the latitude and longitude.

Parameters

• day: 1-31
• month: 1-12
• year: four-digit year. Note that this value is only used for determining whether it is a leap year.

• latitude: degrees north of the equator; south of the equator latitudes are negative
• longitude: degrees east of the Greenwich Meridian; western longitudes are negative

Algorithm

True sunrise and true sunset conventionally refer to the times when the upper edge of the disk of the Sun appears on the horizon at the location of interest. Atmospheric conditions are assumed to be average, and the location is level.

`Zenith' is the angle that the centre of the Sun makes to a line perpendicular to the Earth's surface. If the Sun were a point and the Earth were without an atmosphere, true sunset and sunrise would correspond to a 90-degree zenith. Because the Sun is not a point, and because the atmosphere refracts light, this 90-degree zenith does not, in fact, correspond to true sunset or sunrise; instead the centre of the Sun's disk must lie just below the horizon for the upper edge to be obscured. This means that a zenith of just above 90 degrees must be used. The Sun subtends an angle of 16 minutes of arc, and atmospheric refraction accounts for 34 minutes or so, giving a total of 50 arcminutes. So the best overall figure for zenith is 90+(50/60) degrees for true sunrise/sunset, which is the value assigned to the constant SunTimes.ZENITH

Even when the Sun is slightly below the horizon, a small amout of light is reflected from dust particles in the atmosphere, and it is not quite dark; this is twilight. The duration of twilight is more difficult to define than the times of sunrise and sunset, because light fades gradually as the sun sets. Conventionally we take a zenith of 96 degrees to signify twilight; this figure is usually called the civil zenith. This period of twilight is the time in which it is possible to carry out some forms of outdoor activities, even with no other source of light. Two other twilight zeniths are recognized: nautical zenith at 102 degrees and astronomical zenith at 108 degrees. Nautical twilight is the point at which the horizon stops being visible at sea. Astronical twilight is the point at which the Sun really stops being a source of any illumination.

Clearly the rise and set times will depend on the date. In theory there are also year-to-year variations in sunset/rise times, but they are incredibly tiny. This SunTimes methods require a year to be specified only to account for whether it is a leap year or not. For example, March 1st is one day later on a leap year, compared to non-leap years. In practice this is unlikely to be affect the result by more than a few seconds.

Supporting classes

The Time class provides a simple model of time-of-day, which avoids the system-dependent features of the standard Java Calendar class. All the public methods in SunTimes return an object of class Time. In simple cases the application can just call toString() on it to get a displayable (24-hour clock) time.

Command-line client

Running the command-line client

java -classpath $CLASSPATH:suntimes.jar:javapopt.jar com.web_tomorrow.utils.suntimes.SunTimesClient 
  [options] latitude longitude [day] [month] [year]

Any of the day, month and year can be omitted, and current values will be assumed. At least one option must be specified, to indicate how to convert the calculated UTC time to a local time, if at all. The switch --utc indicates that a UTC time is acceptable and does not need to be converted. Alternatively an offset in hours from GMT can be supplied with the --offset switch, or a timezone with the --zone switch.

The results displayed are 24-hour clock times.

Note that the program does not check that the arguments make sense, beyond being numbers. So it won't complain if you specify Feb 31st, year -20.

Here are some examples.

• To find sunset and sunrise in London today (latitde 51 degrees N, longitude 0 degrees, approx) when daylight savings is not in effect (and therefore local time is UTC):

  suntimes -utc 51 0
  

• To find sunset and sunrise in Wayne, New Jersey, on June 25, 1990 (latitde 40.9 degrees N, longitude 74.3 degrees W) when local time is 4 hours earlier than UTC:

  suntimes -offset -4 40.9 -74.3 25 6 1990 
  

  Notice that offset is negative, because it is earlier than UTC, and longitude is negative because it is west of Meridian. The results should be -- sunrise 05:26, sunset 20:33. This is important because it is the test case presented in the NAO algorithm description.
• To get a list of recognized time zones:

  suntimes -showzones
  

• To find the (civil) twilight times in Thule, Greenland (76 deg N, 68 deg W) on April 9th, 2001:

  suntimes -zone "America/Thule" 76 -68 9 4 2001 -twilight
  

  Note that its northerly location gives Thule about 21 hours of daylight on this date.

• If not specified it displays sunrise and sunset. Use the switch `--twilight' to get the (civil) twilight times instead. Alternatively use `--zenith' to specify an exact zenith.
• Time zone codes are ISO format, e.g., `Europe/London', not the old three-letter codes. The switch `--showzones' displays a list of supported timezones. If the location required is not in the list, you can still convert to localtime explicitly using `--offset'. Remember that negative offsets correspond to places west of the Greenwich Meridian.
• If using a timezone rather than an explicit offset, the program will attempt to correct for daylight savings time at the specified location. In reality, you may be able to do this better the the Java system; if in doubt, use an explicit time offset.
• The program will tell you if you try to determine a non-existent sunrise or sunset time. For example, some northerly locations have no sunset for a large part of the year.

SunTimes Web application

SunTimes Portal Server channel

Download:

• suntimes class library in JAR format (including docs)
• suntimes Web application for Tomcat, etc.
• suntimes desktop channel for iPlanet Portal Server version 3
• suntimes desktop channel for iPlanet Portal Server version 6