Tag: Software Dev

Taanis Bechoros Added to the KosherJava Zmanim API

Matzos
Years ago I posted the Calculating Erev Pesach Zmanim that discussed the addition of sof zman achilas chametz and sof zman biur chametz times to the API. Based on a request on the KosherJava project’s GitHub repository, a new isTaanisBechoros() method was added to the API. The Taanis Bechoros fast day usually occurs on Erev Pesach, but in years like this year (5781/תשפ״א – 2021) when Erev Pesach occurs on Shabbos, the fast is moved back to Thursday the 12th of Nissan. Erev Pesach occurs on Shabbos an average of once every 10 years. The frequency of such occurrences ranges from 3 to 20 years. It will next occur in the year 5785/תשפ״ה – 2025, followed 20 years later in the year 5805/תת״ה – 2045. The code is included in the new v2.2.0 release of the KosherJava zmanim library. The following code sample shows the basic usage of the new method.

JewishCalendar jd = new JewishCalendar();
HebrewDateFormatter hdf = new HebrewDateFormatter();
jd.setJewishDate(5781, JewishDate.NISSAN, 12);
System.out.println(jd.isTaanisBechoros());

Output:

true

Decimal Versus Sexagesimal Based Zmanim Location Errors

Decimal Analog Clock
Converting from one number system to another can be tricky. What time would 6:19 am/pm on this decimal based analog clock be on a regular duodecimal (12 based) clock? See the end of the article for the answer.

There are two different ways to reference latitude and longitude. One uses a sexagesimal (60 based) system of degrees indicated by a ° symbol, minutes indicated by a ' and seconds indicated by ". Think 60 minutes in an hour, 60 seconds in a minute and apply it to latitude numbers. The other system uses the more familiar decimal based format. For example The main BMG beis hamedrash is located at latitude 40.096, longitude -74.222 in degree/decimal. In degrees, minutes and seconds this would be latitude 40° 5′ 46″ N, longitude 74° 13′ 19″ W.

I was recently shown a zmanim calendar that seemed to be slightly inaccurate. Researching the issue showed that the intention was to generate the calendar for the location XX° 46′ N XX° 15′ W (latitude and longitude degrees are masked), but was mistakenly calculated for XX.46° -XX.15°. This confusion of the sexagesimal based system with the decimal based system is not uncommon. The discrepancy in sunrise and sunset in the calendar versus what it should have been was about 80 seconds in the summer. If someone were to confuse XX° 9′ with XX.9° (for both latitude and longitude) you have a much more significant relative error of 0.75°. The impact of this type of mistake is mostly caused by longitude, but latitude changes impact zmanim calculations as well. This 0.75° mistake can result in a zmanim discrepancy of up to five and a half minutes at the latitude of Lakewood, NJ. As confirmed by Dr. Noson Yanofsky, this scenario has the most extreme error, while 10′ confused with 0.10° has the least significant error of 0.066°.

An interesting variant of such a mistake is calculating a zman for a depression angle (how far the sun is below the horizon) that is based on degrees and minutes using degree/decimal. An example is mistakenly calculating tzais of 7° 5′ , or 7.083° as 7.5°. See Hazmanim Bahalacha vol II p. 520 footnote 21 for a case where this mistake happened. It should be noted that many are of the opinion that a depression angle of 7.5° is the proper time of tzais. This was used in the first ever known printed calendar calculated based on depression angles. It was published in תקכ״ו / 1766 by Raphael Levi Hannover. See Hazmanim Bahalacha p. 524 for a picture of the luach and a list of other calendars that calculate tzais as 7.5°.

To answer the question in the image caption above, the time in a regular 12 hour / duodecimal based clock would be 7:40. With 10 hours instead of 12, each decimal hour on this clock is 72 minutes of regular time. Therefore 6 hours = 432 minutes. Add ~19/50 decimal minutes that are equivalent to ~28/72 regular clock minutes and you end up with 460 minutes after noon/midnight, or about 7:40 🙂.

The Yereim’s Bein Hashmashos

Rabbi Eliezer of Metz (known by his acronym The רא״ם Re’em), a disciple of Rabbeinu Tam, in his Sefer Yereim ספר יראים chapter 274, states that bein hashmashos starts the time it takes to walk three quarters of a mil before sunset, and ends at sunset.

פירוש משתשקע החמה דר׳ יהודה ור׳ נחמיה משמתחלת לשקוע שנוטה מעט ומכירים העולם שרוצה להכנס בעובי הרקיע … ולשון משתשקע משמע הקדמה … וכן נראה לי עיקר דמשתשקע החמה הוא קודם שקיעת החמה דעולא ולא כדברי רבינו יעקב … ואין להקפיד על צאת הככבים … אע״ף שאין הכוכבים נראים … שלילה גמור הוא כפירושי.

The Yereim’s opinion is brought down by other Rishonim including the Mordechai and Rav Alexander Suslin HaKohen in his Sefer Agudah. The Yereim is mentioned by the Bach as a reason for the minhag of starting Shabbos early. The Yereim’s times are not brought down by the poskim lehalacha.

The Time to Walk a Mil

The time to walk a mil is based on the Gemara in Pesachim 93b – 94a. The time ranges in the poskim and includes 18, 22.5 and 24 minutes. Three quarters of these mil times would be 13.5, 16.875 and 18 minutes. It should be noted that the Yereim is of the opinion that a mil is 24 minutes. The above mentioned Mordechai who quoted the Yereim is also of the same opinion. We will hopefully discuss in detail the various opinions on the time to walk a mil in a future article.

The Addition of the Yereim’s Times to the KosherJava Zmanim Library

As of the 2.1.0 release of the KosherJava zmanim library, the Yereim’s bein hashmashos times have been added to the KosherJava zmanim library/API. There are six variants of these zmanim that were added. These include the three exact minute offsets mentioned above, as well as the conversion of these three times to degrees (elevation angle, or solar zenith angle). The only prior degree based time for the Yereim that I am aware of is in Rabbi Yedidya Manet’s Zmanei Halacha Lema’aseh (זמני ההלכה למעשה מהרב ידידיה מנת). The Zmanei Halacha Lema’aseh charts calculate bein hashmashos in degrees based on the 18 minute (3/4 of a 24 minute mil, see p. 27 in the 4th ed. published in 2005), but does not clarify the degrees used. At Rabbi Yaakov Shakow’s recommendation, I used the refraction value of 31/60 or 0.516° that exists in Israel, as opposed to the global average of 0.566°. This more stringent refraction is mentioned in the Zmanei Halacha Lema’aseh (p. 11) and used in the לוח עתים לבינה Luach Itim Lebinah. I also slightly rounded the times. These small tweaks resulted in a trivial maximum 19 second chumra vs the non-rounded global average refraction. The resulting degrees of elevation angle for the Yereim’s bein hashmashos are 2.1°, 2.8° and 3.05°. Solar zenith angles are traditionally calculated using the sun’s position without adjusting for refraction and without accounting for the solar radius (i.e. it is the position of the center of the sun in a vacuum). This does not impact the calculated time, it is simply the convention used. In the upcoming 8th edition of הרב דוד יהודה בורשטין Rabbi Yehuda Burstein’s זמנים כהלכתם / Zmanim Kehilchasam he mentions that

הזמן הנ״ל של 18 דקות לפני השקיעה המישורית הוא הזמן רק במרכז א״י ביום הבינוני כנ״ל, ובכל מקום בכל יום מחשבין זאת לפי שיטת המעלות, דהיינו דבודקים כמה מעלות מעל האופק נמצאת השמש במרכז א״י ביום הבינוני 18 דקות לפני השקיעה המישורית, ואותו מספר מעלות של השמש מעל האופק בכל מקום בכל יום הוא הזמן של ״היראם״. ועוד יש להוסיף זמן ל״תוספת שבת״, ובזה יוצא ידי כל שיטות הראשונים ואשרי חלקו.

A future article will address the proper date to use for converting minute-based times to degrees below (or above) the horizon and show how to use the KosherJava Zmanim code to calculate this.
I would like to thank Rabbi Yaakov Shakow for his help and suggestions.

Sample Code

Below are code examples for all six variants of the Yereim’s Bein Hashmashos (spelled BainHashmashos in the code).

GeoLocation yerushalayim = new GeoLocation("Jerusalem, Israel", 31.778, 35.2354, 0, TimeZone.getTimeZone("Asia/Jerusalem"));
ComplexZmanimCalendar czc = new ComplexZmanimCalendar(yerushalayim);
Date bh18Min = czc.getBainHasmashosYereim18Minutes();
Date bh3Pt05Deg = czc.getBainHasmashosYereim3Point05Degrees();
Date bh16Pt875Min = czc.getBainHasmashosYereim16Point875Minutes();
Date bh2Pt8Deg = czc.getBainHasmashosYereim2Point8Degrees();
Date bh13Pt5Min = czc.getBainHasmashosYereim13Point5Minutes();
Date bh2Pt1Deg = czc.getBainHasmashosYereim2Point1Degrees();

SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd h:mm:ss a z"); //set the output format
sdf.setTimeZone(czc.getGeoLocation().getTimeZone()); //set the formatter's time zone
System.out.println("Bein Hashmashos 18 min:     " + sdf.format(bh18Min));
System.out.println("Bein Hashmashos 3.05°:      " + sdf.format(bh3Pt05Deg));
System.out.println("Bein Hashmashos 16.875 min: " + sdf.format(bh16Pt875Min));
System.out.println("Bein Hashmashos 2.8°:       " + sdf.format(bh2Pt8Deg));
System.out.println("Bein Hashmashos 13.5 min:   " + sdf.format(bh13Pt5Min));
System.out.println("Bein Hashmashos 2.1°:       " + sdf.format(bh2Pt1Deg));

The output of the above code (assuming that the calendar was set to March 16, 2020).

Bein Hashmashos 18 min:     2020-03-16 5:29:58 PM IST
Bein Hashmashos 3.05°:      2020-03-16 5:29:40 PM IST
Bein Hashmashos 16.875 min: 2020-03-16 5:31:05 PM IST
Bein Hashmashos 2.8°:       2020-03-16 5:30:51 PM IST
Bein Hashmashos 13.5 min:   2020-03-16 5:34:28 PM IST
Bein Hashmashos 2.1°:       2020-03-16 5:34:09 PM IST

KosherJava Zmanim Library Package Name and Build Process Update


The KosherJava zmanim library originally went live in 2004. There was an existing C/C++ zmanim project by Ken Bloom hosted on SourceForge (that was at the time the equivalent of what GitHub is today). The Java package structure name net.sourceforge.zmanim was based on the one used by Ken’s project (despite not being hosted there), and remained that way for 16 years.
On August 3, 2020, Eli Julian modernized the library’s build process from the previously used Ant, to Maven & Gradle. This change simplified the workflow for many developers using the zmanim API. As part of the change, the package name was updated to com.kosherjava.zmanim. The KosherJava zmanim Maven / Gradle artifacts are available at the KosherJava zmanim Maven Central page. A direct Jar download is available at Maven Central (see the KosherJava Downloads page for instructions). The old code was branched into zmanim-1.5 and will allow people who do not want to upgrade to continue to use the old structure (and Ant build process) while continuing to receive emergency bug fixes. This will allow the codebase to use more modern Java language features, without impacting users who want to remain on the legacy code. The new code has a minimum Java 8 requirement (a version released in March 2014). Releases based on the new build process will use SemVer (Semantic Versioning) to make things simpler for developers.
The upgraded build process also allowed automated GitHub’s CodeQL vulnerability scanning for the KosherJava Zmanim project.
You can add the KosherJava zmanim library as a Maven or Gradle dependency. For Maven add the following to your pom.xml.

<dependency>
  <groupId>com.kosherjava</groupId>
  <artifactId>zmanim</artifactId>
  <version>2.0.3</version>
</dependency>

For Gradle, add the following to your build.gradle file.

implementation group: 'com.kosherjava', name: 'zmanim', version: '2.0.3'

Parsha Code Restored to the KosherJava Zmanim Calendar API

Sunrise CalendarIn the Parsha Code Removed from KosherJava Zmanim Calendar API article posted two years ago, I documented the removal of the parsha code from the KosherJava Zmanim API due to licensing issues. I would like to announce that thanks to Yechiel Paricher, the zmanim library now supports a clean LGPL implementation. Yechiel’s Jan 17, 2019 pull request that was a port of his C libzmanim code, was finally merged on August 22nd, and over the past day, the old formatting code for parshiyos was restored after being changed to work with the new code. The new code not only restores the old functionality, but adds support for the special parshiyos of Shekalim, Zachor, Parah and Hachodesh. It also added support for Shabbos Mevorchim and Machar Chodesh.