Due to licensing issues that were brought to my attention last year, the parsha code was removed from the Zmanim API on Aug 22, 2016. In the future I may release the parsha code as a standalone module under the GPL license, or create a new LGPL implementation. To understand this more clearly, the current Zmanim API is licensed under the LGPL, while the parsha code contained some GPL code that had to be removed in order to retain the LGPL license. I would welcome any code submission for parsha code that could be released under the LGPL.
Why does the KosherJava Zmanim API seem to sometimes return the incorrect parshas hashavua in Israel?
Answer:
I have had a number of inquiries this year about the incorrect Parshas Hashavua being returned by the API. In all cases this has been a complaint for Eretz Yisrael and not Chutz La’aretz. The explanation is pretty simple and covered in the API documentation for the JewishCalendar class, but may not be clear to all. When the first day of Pesach occurs on a Shabbos, as it did this year (5775), the last day of Pesach in Eretz Yisrael is on a Friday. The following day is a regular Shabbos in Eretz Yisrael with the usual krias hatorah, but in chutz la’aretz it is the 8th day of Pesach, resulting in krias Hatorah for Pesach. The following weeks will have different krias HaTorah in Eretz Yisrael vs chutz la’aretz, and this will continue for a number of weeks until a double parsha in chutz laaretz is added to equalize the parsha. This last occurred in 2012 (before the release of the calendar functionality in the Zmanim 1.3 release) and will occur again next year. If you are coding to display the Parshas Hashavuah for use in Israel, it is important to set the inIsrael(true) flag (it has a default of false).
JewishDate.setInIsrael(true);
A fuller example showing how to set the indicator and showing the comparison of Eretz Yisrael and Chutz Laaretz this year can be seen in this example.
JewishCalendar israelCalendar = new JewishCalendar(5775, JewishDate.NISSAN, 7);
israelCalendar.setInIsrael(true); //set the calendar to Israel
JewishCalendar chutsLaaretzCalendar = new JewishCalendar(5775, JewishDate.NISSAN, 7);
chutsLaaretzCalendar.setInIsrael(false); //not really needed since the API defaults to false
HebrewDateFormatter hdf = new HebrewDateFormatter();
System.out.println("Date\tChutz Laaretz / Eretz Yisrael"));
for(int i = 0; i < 57; i++){
israelCalendar.forward(); //roll the date forward a day
chutsLaaretzCalendar.forward(); //roll the date forward a day
if(chutsLaaretzCalendar.getDayOfWeek() == 7){ //ignore weekdays
System.out.println(hdf.formatParsha(chutsLaaretzCalendar) + "\t" + hdf.formatParsha(israelCalendar) + " \\ " + hdf.format(chutsLaaretzCalendar));
}
}
How do I calculate the בעל התניא Baal Hatanya’s Zman for Shkiah as 4 minutes after sunset using the KosherJava Zmanim API?
Answer:
I was recently asked how to use the Zmanim API to calculate the Baal Hatanya’s opinion is that shkiah (halachic sunset) is 4 minutes after civil sunset. The assumption that the Baal Hatanya’s shkiah is a fixed 4 minutes after sunset is not that simple and will require a separate post to clarify. This zman should not be used lehalacha without consulting a rov. This post shows how to us the API assuming that it is a fixed 4 minutes after sunset. The technique to calculate this with the API is identical to the way getTzais72() would be calculated. The source of that method is
public Date getTzais72() {
return getTimeOffset(getSeaLevelSunset(), 72 * MINUTE_MILLIS);
}
public Date getTimeOffset(Date time, long offset) {
if (time == null || offset == Long.MIN_VALUE) {
return null;
}
return new Date(time.getTime() + offset);
}
The getTimeOffset method simply adds the number of milliseconds of the offset to the raw time of the zman and returns it as a date. While using the API itself is not needed for such a simple calculation, here is how it would be used:
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);
Date baalHatanyaShkiah = zc.getTimeOffset(zc.getSeaLevelSunset(), 4 * 60000);
System.out.println("Baal Hatanya Shkiah: " + baalHatanyaShkiah);
Adding it to the API itself would be even simpler:
public Date getShkiahBaalHatanya() {
return getTimeOffset(getSeaLevelSunset(), 4 * MINUTE_MILLIS);
}
At some point in the future I may (doubtful) add this time to the API itself. The zman is not commonly used, and the Chabad calendars that I have seen all use regular sunset.
Update on July 5, 2015 – י״ח תמוז תשע״ה: This article was updated to clarify that the Baal Hatanya’s opinion may not be a fixed 4 minutes, but that the post was showing how to use the API to calculate it based on the questioner’s assumption that it was a 4 minute zman. Update on Dec 14, 2018 – ו׳ טבת תשע״ט: This article was superseded with the more recent and corrected article Baal Hatanya’s Zmanim Added to KosherJava Zmanim Library.
The Zmanim API version 1.3.0 was released on March 4th, 2013 כ״א אדר תשע״ג. Various changes in the new release VS the previous version 1.2.1 that was released in May 2010 can be seen below. This release includes beta support for Jewish Calendar calculations as well as a number of updated zmanim and refactored code. The Jewish Calendar support in the Zmanim API is based on Avrom Finkelstien’s HebrewDate project released in 2002. Unlike the Zmanim code, the Jewish calendar interfaces may change significantly in the future (see Jay Gindin’s various changes that may make it into this API) and should therefore be considered beta.
Changes in the Zmanim API 1.3.0 release
Refactoring of zmanim calculations to allow more flexibility in generating custom zmanim. New generic methods that take an arbitrary start and end of day for many zmanim such as sofZmanShema and getPlagHamincha etc. This makes calculating atypical zmanim that I had not anticipated when creating the API. I receive such requests from time to time, and the changes greatly simplify these types of calculations. Examples of recent requests are:
Zman krias Shema calculated from alos as 72 minutes before netz and tzais as 7.083 degrees
Plag hamincha from alos 7.083° to tzais 7.083°
Many rounds of general code refactoring to simplify and stabilize the code and make it easier to port. Thank you Jay Gindin for his many suggestions.
Deprecation of the getSofZmanShmaKolEliyahu() method. Thank you to Rabbi Yisroel Boruch Twerski for pointing out that the Yisrael Vehazmanim was incorrect in including this zman. This is something he discussed with Rabbi Harfenes.
Uniformly return zmanim based on sea level sunrise and sunset. Most zmanim had this fix a long time ago, but there were a few zmanim such as candle lighting time that were corrected.
The International Date Line is an internationally agreed upon, arbitrarily selected, line that demarcates one calendar day from the next. This line is about 180° from Greenwich and was selected since it is opposite Greenwich and mostly runs through uninhabited areas. The line (see the gray line in the map above) meanders around national borders and island groups. The halachic date line (קו התאריך) is a complex subject with various opinions. See Rabbi Dovid Heber’s excellent article A Traveler’s Guide to the International Date Line in the Star-K Kashrus Kurrents for additional information. This line changes from time to time, as countries decide to change from one side of the date line to the other. The most recent change was when Samoa shifted to the west of the line at the end of 2011. Discussing the Samoa change in a December 29th, 2011 Yeshiva World article How to Keep This Shabbos in Samoa?, Rabbi Dovid Heber stated that
According to almost all opinions, the Halachic Date Line is not determined by what the locals call “Saturday” and therefore, the fact that Samoa changes the date line does not change when we keep Shabbos.
As far as I know, until this point, there has not been a very exact map allowing one to determine with clarity the exact parts of the world affected by the Halachic Date Line. As an example, see Rabbi Yisroel Taplin’sseferTaarich Yisrael תאריך ישראל for a discussion about possibly not visiting the Philippines due to questions about the exact location of the date line. With the introduction of the Halachic Date Line Map such ambiguities can be laid to rest since users can zoom in to find the exact locations of various opinions on the map (see the map partially zoomed in to the Philippines for example).
Location of the Halachic Date Line
There are various opinions about the location of the halachic date line. The three main opinions of the location of the Halachic Date Line are:
Rabbi Yechiel Michel Tucazinsky (author of the Gesher Hachaim) who wrote the היומם בכדור הארץ Hayomam Bekadur Haaretz stating his opinion that the date line is 180° east (or west) of Har Habayis. Among those agreeing with this opinion is Rabbi Elyashiv. Since this line is exactly halfway around the world from Yerushalayim, a person on different sides of this line will face different directions when davening (using the rhumb line method). A person located west of the line will daven westward, and a person east of the line will daven eastwards. See the Bearing to Yerushalayim Map for a location along this line (the green line). Click on the blue pushpin in the map (below the green line) for additional information on the antipodal point of the Har Habayis.
The locations of the three lines are mostly over the Pacific Ocean, but in some places the lines intersect dry land. Examples of this are Russia, China, Korea, The Philippines, Indonesia, East Timor and Australia that are split by the Kuzary and Baal Hamaor’s line (see the map above). The Chazon Ish brings the opinion of the יצחק הישראלי Yitzchak Hayisraeli (a disciple of the רא״ש Rosh) in the יסוד עולם Yesod Olam 2:17 and 4:7–8, that when the line intersects dry land, the line is extended eastward (or on occasion westward according to the 180° opinion). This extension is referred to as גרירה / graira, where the land to the west “drags” the land it is attached to, to within the line. In the map, both the 90° (Chazon Ish) and 180° (Rabbi Tucazinsky) lines are measured from Har Habayis. Specifically, the measurements in the map are from the center of the Dome of the Rock. This is the location of the Kodesh Kodashim according to the רדב״ז Radvaz. According to the רד”ק Radak the center of the Dome of the Rock is the location of the mizbeach, and the Kodesh Kodashim is 101 amos (about 54 meters / 180 feet) west of this point. According to the Radak the International Date Line would be 101 amos west of the lines in the map.
How the Map Works
The Halachic Date Line Map works like any other Google Map. You can zoom into any area to see a close-up. Clicking on the lines and shaded in graira areas will provide some details about it. The map will show a very clear and exact position of the Halachic Date Line according to different halachic opinions.
Interesting points on the map
Tahania Atoll, a small atoll in French Polynesia that is intersected by Rabbi Tucazinsky’s line. To the south of this point is the island of Rapa Iti. There is an interesting Halachic phenomenon at this location with Kiddush Levana in December 2027. See Rabbi Heber’s Sefer Shaarei Zemanim שערי זמנים. Rabbi Heber graciously allowed me to post סימן ד׳ קונטרס זמן קידוש לבנה of the Shaarei Zemanim here. The discussion of Kiddush Levana on Rapa Iti appears on page 14 of the pdf which is page 32 in the sefer.
The Wrangell Mountain Homestead in Alaska, along the Edgerton Highway between Kenny Lake, and Chitina seems to be the only inhabited place that is that is intersected by Rabbi Tucazinsky’s line. The line cuts through what seems to be a barn. Thank you Rabbi Heber for this interesting observation.
Ikema Island is intersected by the Baal Hamaor’s line. According to the Chazon Ish graira covers the entire Ikema Island but would not (according to Rabbi Dovid Heber of the Star-K) extend over the bridge to Miyakojima Island.
The line of the Baal Hamaor runs through Changchun, China a city of 7 million. According to the Chazon Ish, graira would mean the line does not split the city.
Are islands on Lake Argyle, that are 100 miles inland but with a river leading to the ocean included in graira using the Chazon Ish’s line? According to Rabbi Heber the river would “not ruin graira“, and such islands would be included. Would you say the same thing for French and Phillip Islands near Melbourne, Australia? Rabbi Heber is of the opinion that one should be machmir on these islands.
Clarity about exactly what parts of the Philippines are on the other side of the date line. Some say it is better not to travel to the Philippines due to questions of the placement of the Baal Hamaor/Chazon Ish line, but the date line map clarifies any ambiguities about this part of the world.
Due to licensing issues that were brought to my attention last year, the parsha code was removed from the Zmanim API on Aug 22, 2016. In the future I may release the parsha code as a standalone module under the GPL license, or create a new LGPL implementation. To understand this more clearly, the current Zmanim API is licensed under the LGPL, while the parsha code contained some GPL code that had to be removed in order to retain the LGPL license. I would welcome any code submission for parsha code that could be released under the LGPL.
