NOAA Fixes Solar Calculator

When comparing the results of the KosherJava NOAA algorithm to the output of NOAA’s new Solar Calculator almost two years ago, a discrepancy was encountered between the two. There was no discrepancy compared to the output of the old NOAA calculator. The NOAA code is an implementation of the accurate Jean Meeus algorithm for solar time calculations, and the KosherJava code is a Java port of this algorithm. While attempting to debug the issue, I turned to Pinny Markowitz who ported the KosherJava library to both Ruby and Python. He was able to trace the issue to what seemed to be a small accuracy adjustment missing in the noon calculation on the new NOAA implementation. Based on Pinny’s analysis, the old implementation seemed correct, but without confirmation from the NOAA developers this was not a certainty. We reported the issue to NOAA for clarification, and after an almost two-year delay, the NOAA development team confirmed and corrected the bug. After NOAA’s fix there is no longer any discrepancy. The fix can be seen in line 342 of the NOAA JavaScript file, where a half day adjustment is made in the noon time calculation. This bug was never present in the KosherJava library, or other language ports of the KosherJava code, since our code was based on the original NOAA code.

FAQ: Outputting Zmanim for A Different Time Zone With the Zmanim API

Question:

Why does the output of zmanim for a different time zone appear incorrect?

Answer:

One of the common issues encountered by developers using the API is that zmanim generated for a different time zone than the user’s time zone may return output that appears incorrect. For example a user in Lakewood, NJ trying to calculate sunrise for Yerushalayim may attempt to use the following code:

String locationName = "Jerusalem";
double latitude = 31.778; // Har habayis
double longitude = 35.2354;// Har Habayis
double elevation = 0;
TimeZone timeZone = TimeZone.getTimeZone("Asia/Jerusalem");
GeoLocation location = new GeoLocation(locationName, latitude, longitude, elevation, timeZone);
ZmanimCalendar zc = new ZmanimCalendar(location);
zc.getCalendar().set(2011, Calendar.FEBRUARY, 8);
System.out.println("Sunrise: " + zc.getSunrise());
System.out.println("Sunset: " + zc.getSunset());

While you would expect a sunrise of 6:27:41 AM and sunset of 5:19:19 PM, running this code on a computer anywhere in the Eastern Standard time zone would generate the following time that appears to be 7 hours early:

Sunrise: Mon Feb 07 23:27:41 EST 2011
Sunset: Tue Feb 08 10:19:19 EST 2011

The issue is simple, and the sunrise and sunset returned above are actually accurate. Zmanim are returned by the Zmanim API as a Java Date object that represents a moment in time (stored internally by Java as Unix Time – the number of milliseconds since the January 1, 1970 GMT). Sunrise in Yerushalayim on February 8th actually happens at 11:27:41 PM on February 7th EST. Java is simply outputting the Date as a String formatted to the users default time zone (EST in this example). The user probably intends to output the time in IST – Israel Standard Time (“Asia/Jerusalem” in the Olson database). To do this you have to output the zmanim using a formatter set to use the “Asia/Jerusalem” time zone.

DateFormat zmanimFormat = new SimpleDateFormat("EEE MMM dd HH:mm:ss z yyyy");
zmanimFormat.setTimeZone(location.getTimeZone());

System.out.println("sunrise: " + zmanimFormat.format(zc.getSunrise()));
System.out.println("sunset:" + zmanimFormat.format(zc.getSunset()));

will output the expected

sunrise: Tue Feb 08 06:27:41 IST 2011
sunset:Tue Feb 08 17:19:19 IST 2011

Below is the full code example.

import com.kosherjava.zmanim.*;
import com.kosherjava.zmanim.util.*;
import java.util.TimeZone;
public class FormatZmanim{
	public static void main(String [] args) {
		String locationName = "Jerusalem";
		double latitude = 31.778; //latitude of Har habayis
		double longitude = 35.2354; //longitude of Har Habayis
		double elevation = 0; //optional elevation
		//use a Valid Olson Database timezone listed in java.util.TimeZone.getAvailableIDs()
		TimeZone timeZone = TimeZone.getTimeZone("Asia/Jerusalem");
		//create the location object
		GeoLocation location = new GeoLocation(locationName, latitude, longitude, elevation, timeZone);
		ZmanimCalendar zc = new ZmanimCalendar(location); //create the ZmanimCalendar
		zc.getCalendar().set(2011, Calendar.FEBRUARY, 8); //set the date
		DateFormat zmanimFormat = new SimpleDateFormat("EEE MMM dd HH:mm:ss z yyyy"); //Create the formatter
		zmanimFormat.setTimeZone(location.getTimeZone()); //set the formatter's time zone
		System.out.println("sunrise: " + zmanimFormat.format(zc.getSunrise()));
		System.out.println("sunset:" + zmanimFormat.format(zc.getSunset()));
	}
}

FAQ: Why Some Zmanim Never Occur (Developers Beware)

Question:

Why do some zmanim never occur in some locations? Developers Beware!

Answer:

While most people realize that the sun may not rise or set in the Arctic and Antarctic Circles (see the Rabbi Dovid Heber’s article When Does One Pray When There Is No Day in the Star-K’s Kashrus Kurrents), many are not aware that some twilight dips will not occur during part of the year as far south of the Arctic Circle as London. For example around the summer solstice in London (on the zmanim map) the sun will never dip far enough below the horizon to reach alos 16°. This happens in London from June 4th through July 8th. The image seen on the top right (original at timeanddate.com) shows various civil twilights centered on London on Midnight June 21st. Look carefully to see the various bands of twilight. Gateshead will not have alos 16° from May 16th through July 28th, while Anchorage, Alaska (yes there is a Frum Shul in Anchorage with an interesting davening direction issue that is discussed in the Davening Direction from Alaska post ) will not have alos 16.1° from April 25th to August 20th. Zmanim based on sunrise such as alos 72 that is a 72 minute offset of sunrise can be calculated as long as sunrise can be calculated, something that will happen as long as you are not in the Arctic or Antarctic Circles.
For this reason, the Zmanim API will return a null when a zman will not happen. A Long.MIN_VALUE will be returned when a long is expected such as in the case of a shaah zmanis. While an inconvenience to developers who have to code for this, the alternative of a default date would mean that developers unaware of this would return incorrect zmanim, something far worse than a program error from a NullPointerException.
In recent weeks two publicly available programs using the Zmanim API ran into issues due to nulls returned for early alos times. Being something not anticipated by the developers, the nulls generated errors in the programs that quickly led to fixes. For this reason, Yitzchok updated the Zmanim .NET project to return the nullable DateTime? instead of the regular DateTime that it had previously been returning. While the Zmanim API documentation always made the possibility of a null being returned possible, I modified the documentation to make this clear on the return value documentation for every zman. Code with the modified documentation was part of the recently released Zmanim API 1.2.1.

Zmanim Bug Report from the Land of the Midnight Sun


I was recently contacted by Jan Terje Johansen, a developer at Datek Wireless AS in Norway, with an interesting bug report. Datek uses the Zmanim API (the AstronomicalCalendar base class) to allow their clients (the power company and stadiums) to remotely (via a web interface) control streetlights and stadium lights throughout Norway using a wireless lighting control system that they developed. The zmanim code is used to allow setting the lighting times based on an offset of sunrise/sunset. For the technically curious, they are controlled primarily through GPRS, with SMS as fallback. A version under development uses ZigBee. The bug encountered was that for Tromsoe (Tromsø), Norway, as well as other areas within the Arctic Circle that experience the midnight sun, from May 13th to May 17th (the date of last rise of the season in Tromsoe), the zmanim API produced correct sunrise/set times, but the date component (The API returns all times as Java Dates, something that might change with v2.0 of the API that will target JDK 7 to take advantage of JSR-310 Date and Time API) was a day off. For non-automated systems, the date component is not important, but in their case it would cause the lights to go on/off on the wrong day. Jan provided a suggested patch that worked well. The actual fix I used was slightly different because I took advantage of the time spent on fixing the bug to refactor and simplify the code. This change as well as a few other changes are part of the Zmanim 1.1 beta release that will likely be released as a final release in a few days. Jan mentioned that:

“IMHO your API is easily the best and most accurate Open Source sunset/sunrise API out there”. He continued: “Officially (according to the Norwegian Meteorology Institute), the midnight sunset/sunrise is from May 20 to July 22 in Tromsoe, ie. the complete sun is above the horizon 24 hours. Parts of sun is visible 24 hours a day in Tromsoe from May 18th to July 25th. This is the same as in your calculations.” … “I have tested your calculations against other official midnight sunrise/sunset (part of sun) dates in Northern-Norway (North Cape, Hammerfest, Longyearbyen (78,049762N -15,458252E)) and they are spot on.”

In response to my question regarding his testing of the NOAACalculator versus the USNOCalculator he had an interesting and very practical answer

“We prefer to use USNO calculator as it is more in tune with the sunrise/sunset times printed in most newspapers. You see, our experience is that most users don’t look at the sun to determine sunrise/sunset but read the times in the newspaper. If our times don’t correspond to the printed ones, something is wrong with our system in their mind.”

Fix to NOAA Sunrise/Sunset Algorithm

The Zmanim API was developed from the ground up as an API which allows for easy plugging in of different algorithms. The Zmanim API ships with 3 “Calculator” implementations. Two calculators implement the US Naval Observatory’s algorithm, the SunTimesCalculator and the ZmanimCalculator (no longer available). Both produce identical zmanim using slightly different code and are included for comparison. There is also the JSuntimeCalculator (no loner available – see below information on the NOAACalculator), an implementation of the NOAA algorithm by Jonathan Stott. I was recently contacted by Eliezer Bulka who wanted to know why sunrise/sunset times generated by the NOAA algorithm were about 2 minutes off of the sunrise/sunset times generated by the NOAA JavaScript implementation that is the source of the JSuntimeCalculator. To compare apples and apples required modification of the NOAA JavaScript to allow entry of decimal latitude/longitude, and changing the output to display seconds. No change was made to the algorithm itself. I then ported the JavaScript directly to Java. This involved nothing more than slight syntax changes between the languages. Once this was done I noticed that the sun rise/set output from the Java port exactly matched the output of the NOAA JavaScript. Analysis of Jonathan’s code showed (or at least my interpretation of it did) that there were two areas that caused the difference. Once is that he used a slightly different method of computing the Julian date, a key part of the algorithm. His change includes the time of day as part of the calculation. The net result of this change is that solar time generated using his algorithm varies based on the time of day the calculation is run, something that is incorrect. This means that there can be a discrepancy of up to one calendar day. If the user calculated sunrise at 11:59 PM, sunrise would be calculated for the following day even if the user attempted to calculate it for today. In addition, the other calculations do not match the output of the matching NOAA code. I have deprecated the JSuntimeCalculator and in its place added the NOAACalculator that was the result of the direct port of the NOAA code, shoehorned into the Zmanim API Calculator interface. I ran some tests to compare the maximum and minimum discrepancy between the 2 implementations, and calculations for Lakewood, NJ, latitude 40.0828, longitude -74.2094 show a discrepancy of between a minute and 34 seconds to a minute and 37 seconds for sunrise and sunset across an entire year of sunrise and sunset calculations. I also compared the USNO algorithm to the new NOAA implementation and ended up with a maximum deviation of less than 30 seconds, something that had been about 1.5 minutes apart previously. While I do believe that the Julian date calculation is a bug, I do not know that this is a case as far as the rest of the calculation, but it is clear that it does not match the NOAA implementation that is was based on, and I recommend that you download the latest version that has the new NOAACalculator that fixes this issue. In addition to this fix, an additional patch will be released later this week that will address issues with calculations in the arctic circle. Stay posted for the next post.