Zmanim
The ZmanimCalendar is a specialized calendar that can calculate sunrise, sunset and Jewish zmanim (religious times) for prayers and other Jewish religious duties. This class contains the main functionality of the Zmanim library. For a much more extensive list of zmanim, use the ComplexZmanimCalendar that extends this class. See documentation for the ComplexZmanimCalendar and AstronomicalCalendar for simple examples on using the API. Elevation based zmanim (even sunrise and sunset) should not be used lekula without the guidance of a posek. According to Rabbi Dovid Yehudah Bursztyn in his Zmanim Kehilchasam, 7th edition chapter 2, section 7 (pages 181-182) and section 9 (pages 186-187), no zmanim besides sunrise and sunset should use elevation. However, Rabbi Yechiel Avrahom Zilber in the Birur Halacha Vol. 6 Ch. 58 Pages &34 and &42 is of the opinion that elevation should be accounted for in zmanim calculations. Related to this, Rabbi Yaakov Karp in Shimush Zekeinim, Ch. 1, page 17 states that obstructing horizons should be factored into zmanim calculations. The setting defaults to false (elevation will not be used for zmanim calculations besides sunrise and sunset), unless the setting is changed to true in isUseElevation. This will impact sunrise and sunset-based zmanim such as sunrise, sunset, sofZmanShmaGRA, alos-based zmanim such as sofZmanShmaMGA that are based on a fixed offset of sunrise or sunset and zmanim based on a percentage of the day such as ComplexZmanimCalendar.sofZmanShmaMGA90MinutesZmanis that are based on sunrise and sunset. Even when set to true it will not impact zmanim that are a degree-based offset of sunrise and sunset, such as or ComplexZmanimCalendar.getSofZmanShmaBaalHatanya since these zmanim are not linked to sunrise or sunset times (the calculations are based on the astronomical definition of sunrise and sunset calculated in a vacuum with the solar radius above the horizon), and are therefore not impacted by the use of elevation. For additional information on the halachic impact of elevation on zmanim see:
Zmanei Halacha Lema'aseh 4th edition by Rabbi Yedidya Manat. See section 1, pages 11-12 for a very concise write-up, with details in section 2, pages 37 - 63 and 133 - 151.
Zmanim Kehilchasam 7th edition, by Rabbi Dovid Yehuda Burstein, vol 1, chapter 2, pages 95 - 188.
Hazmanim Bahalacha by Rabbi Chaim Banish , perek 7, pages 53 - 63.
Note: It is important to read the technical notes on top of the AstronomicalCalendar documentation before using this code.
I would like to thank Rabbi Yaakov Shakow, the author of Luach Ikvei Hayom who spent a considerable amount of time reviewing, correcting and making suggestions on the documentation in this library.
Disclaimer:
I did my best to get accurate results, but please double-check before relying on these zmanim for halacha lema'aseh.Glossary Alos - Dawn. The time when the sun is 16.1° below the eastern geometric horizon before sunrise. Sunrise - Netz/Haneitz Sunset - Shkiah Dusk/Nightfall: This is the same as Tzais. Candle lighting - The time when Shabbos candles are lit. This is usually 18 minutes before sunset. Chatzos - Midday/Midnight. The time when the sun is at its highest point in the sky. This is usually 6 hours after Alos.
Author
Eliyahu Hershfeld 2004 - 2022
Inheritors
Constructors
Properties
Method to return alos (dawn) calculated using 72 minutes before sunrise or sea level sunrise (depending on the isUseElevation setting). This time is based on the time to walk the distance of 4 Mil at 18 minutes a Mil. The 72 minute time (but not the concept of fixed minutes) is based on the opinion that the time of the Neshef (twilight between dawn and sunrise) does not vary by the time of year or location but depends on the time it takes to walk the distance of 4 Mil.
Returns alos (dawn) based on the time when the sun is 16.1˚ below the eastern geometric horizon before sunrise. This is based on the calculation that the time between dawn and sunrise (and sunset to nightfall) is 72 minutes, the time that is takes to walk 4 mil at 18 minutes a mil (Rambam and others). The sun's position at 72 minutes before sunrise in Jerusalem on the [around the equinox /
The internal AstronomicalCalculator used for calculating solar based times. A method to set the AstronomicalCalculator used for astronomical calculations. The Zmanim package ships with a number of different implementations of the abstract AstronomicalCalculator based on different algorithms, including the default com.kosherjava.zmanim.util.NOAACalculator based on NOAA's implementation of Jean Meeus's algorithms as well as [] based on the US * Naval Observatory's algorithm,. This allows easy runtime switching and comparison of different algorithms.
A method that returns the beginning of astronomical twilight using a zenith of .ASTRONOMICAL_ZENITH.
A method that returns the beginning of civil twilight (dawn) using a zenith of .CIVIL_ZENITH.
A method that returns the beginning of nautical twilight using a zenith of NAUTICAL_ZENITH.
A method to return candle lighting time, calculated as .getCandleLightingOffset minutes before sea level sunset. This will return the time for any day of the week, since it can be used to calculate candle lighting time for Yom Tov (mid-week holidays) as well. Elevation adjustments are intentionally not performed by this method, but you can calculate it by passing the elevation adjusted sunset to .getTimeOffset.
The default Shabbos candle lighting offset is 18 minutes. This can be changed via the candleLightingOffset and retrieved by the candleLightingOffset.
This method returns chatzos (midday) following most opinions that chatzos is the midpoint between sea level sunrise and sea level sunset. A day starting at alos and ending at tzais using the same time or degree offset will also return the same time. The returned value is identical to sunTransit. In reality due to lengthening or shortening of day, this is not necessarily the exact midpoint of the day, but it is very close.
A method that returns the end of astronomical twilight using a zenith of .ASTRONOMICAL_ZENITH.
A method that returns the end of civil twilight using a zenith of .CIVIL_ZENITH.
A method that returns the end of nautical twilight using a zenith of .NAUTICAL_ZENITH.
the GeoLocation used for calculations.
Is elevation factored in for some zmanim (see isUseElevation for additional information).
The Java Calendar encapsulated by this class to track the current date used by the class
This method returns the latest mincha gedola,the earliest time one can pray mincha that is 6.5 * shaos zmaniyos (solar hours) after sunrise or sea level sunrise (depending on the isUseElevation setting), according to the GRA. Mincha gedola is the earliest time one can pray mincha. The Ramba"m is of the opinion that it is better to delay mincha until .getMinchaKetana while the Ra"sh, Tur, GRA and others are of the opinion that mincha can be prayed lechatchila starting at mincha gedola. The day is calculated from sea level sunrise to sea level or sunrise to sunset (depending on the isUseElevation setting).
This method returns mincha ketana,the preferred earliest time to pray mincha in the opinion of the Rambam and others, that is 9.5
This method returns plag hamincha, that is 10.75 * shaos zmaniyos (solar hours) after sunrise or sea level sunrise (depending on the isUseElevation setting), according to the GRA. Plag hamincha is the earliest time that Shabbos can be started. The day is calculated from sea level sunrise to sea level or sunrise to sunset (depending on the isUseElevation
A method that returns the sunrise without elevation. Non-sunrise and sunset calculations such as dawn and dusk, depend on the amount of visible light, something that is not affected by elevation. This method returns sunrise calculated at sea level. This forms the base for dawn calculations that are calculated as a dip below the horizon before sunrise.
A method that returns the sunset without elevation. Non-sunrise and sunset calculations such as dawn and dusk, depend on the amount of visible light, something that is not affected by elevation. This method returns sunset calculated at sea level. This forms the base for dusk calculations that are calculated as a dip below the horizon after sunset.
A method that returns a shaah zmanis (temporal hour) according to the opinion of the GRA. This calculation divides the day based on the opinion of the GRA that the day runs from sea level sunrise to sea level sunset or sunrise to sunset (depending on the isUseElevation setting). The day is split into 12 equal parts with each one being a shaah zmanis. This method is similar to temporalHour, but can account for elevation.
A method that returns a shaah zmanis (temporal hour) according to the opinion of the Magen Avraham (MGA) based on a 72 minutes alos and tzais. This calculation divides the day that runs from dawn to dusk (for sof zman krias shema and tfila). Dawn for this calculation is 72 minutes before sunrise or sea level sunrise (depending on the isUseElevation elevation setting) and dusk is 72 minutes after sunset or sea level sunset (depending on the isUseElevation elevation setting). This day is split into 12 equal parts with each part being a shaah zmanis. Alternate methods of calculating a shaah zmanis according to the Magen Avraham (MGA) are available in the subclass ComplexZmanimCalendar.
This method returns the latest zman krias shema (time to recite shema in the morning) that is 3 * shaos zmaniyos (solar hours) after sunrise or sea level sunrise (depending on the isUseElevation setting), according to the GRA. The day is calculated from sea level sunrise to sea level or sunrise to sunset (depending on the isUseElevation setting).
This method returns the latest zman krias shema (time to recite shema in the morning) that is 3 * shaos zmaniyos (solar hours) after alos72, according to the Magen Avraham (MGA). The day is calculated from 72 minutes before sea level sunrise to 72 minutes after seaLevelSunrise or from 72 minutes before sunrise to sunset (depending on the isUseElevation setting).
This method returns the latest zman tfila (time to recite shema in the morning) that is 4 * *shaos zmaniyos* solar hours after sunrise or sea level sunrise (depending on the isUseElevation setting), according to the GRA. The day is calculated from sea level sunrise to sea level or sunrise to sunset (depending on the isUseElevation setting).
This method returns the latest zman tfila (time to recite shema in the morning) that is 4 * shaos zmaniyos (solar hours) after alos72, according to the Magen Avraham (MGA). The day is calculated from 72 minutes before sea level sunrise to 72 minutes after or from 72 minutes before sunrise to sunset (depending on the isUseElevation setting).
The sunrise method returns an Instant representing the elevation adjusted sunrise time. The zenith used for the calculation uses geometric zenith of 90 plus AstronomicalCalculator.getElevationAdjustment. This is adjusted by the AstronomicalCalculator to add approximately 50/60 of a degree to account for 34 archminutes of refraction and 16 archminutes for the sun's radius for a total of 90.83333˚. See documentation for the specific implementation of the AstronomicalCalculator that you are using.
The getSunset method Returns a Date representing the elevation adjusted sunset time. The zenith used for the calculation uses geometric zenith of 90 plus AstronomicalCalculator.getElevationAdjustment. This is adjusted by the AstronomicalCalculator to add approximately 50/60 of a degree to account for 34 archminutes of refraction and 16 archminutes for the sun's radius for a total of 90.83333˚. See documentation for the specific implementation of the AstronomicalCalculator that you are using. Note: In certain cases the calculates sunset will occur before sunrise. This will typically happen when a timezone other than the local timezone is used (calculating Los Angeles sunset using a GMT timezone for example). In this case the sunset date will be incremented to the following date.
A method that returns sundial or solar noon. It occurs when the Sun is transiting the celestial meridian. The calculations used by this class depend on the AstronomicalCalculator used. If this calendar instance is astronomicalCalculator to use the com.kosherjava.zmanim.util.NOAACalculator (the default) it will calculate astronomical noon. If the calendar instance is to use the com.kosherjava.zmanim.util.SunTimesCalculator, that does not have code to calculate astronomical noon, the sun transit is calculated as halfway between sea level sunrise and sea level sunset, which can be slightly off the real transit time due to changes in declination (the lengthening or shortening day). See The Definition of Chatzos for details on the proper definition of solar noon / midday.
A method that returns an elevation adjusted temporal (solar) hour. The day from sunrise to sunset is split into 12 equal parts with each one being a temporal hour.
A method that returns tzais (nightfall) when the sun is 8.5˚ below the geometric horizon (90) after sunset, a time that Rabbi Meir Posen in his the Ohr Meir calculated that 3 small stars are visible, which is later than the required 3 medium stars. See the ZENITH_8_POINT_5 constant.
This method returns the tzais (nightfall) based on the opinion of Rabbeinu Tam that tzais hakochavim is calculated as 72 minutes, the time it takes to walk 4 Mil at 18 minutes a Mil. According to the Machtzis Hashekel in Orach Chaim 235:3, the Pri Megadim in Orach Chaim 261:2 (see the Biur Halacha) and others (see Hazmanim Bahalacha 17:3 and 17:5) the 72 minutes are standard clock minutes any time of the year in any location. Depending on the isUseElevation setting) a 72 minute offset from either sunset or sea level sunset is used.
Functions
A method that creates a deep copy of the object.
A generic method for calculating the latest mincha gedola (the earliest time to recite the mincha prayers) that is 6.5 * shaos zmaniyos (temporal hours) after the start of the day, calculated using the start and end of the day passed to this method. The time from the start of day to the end of day are divided into 12 shaos zmaniyos (temporal hours), and mincha gedola is calculated as 6.5 of those shaos zmaniyos after the beginning of the day. As an example, passing sunrise and sunset or sea level and sea level sunset (depending on the isUseElevation elevation setting) to this method will return mincha gedola according to the opinion of the GRA.
A generic method for calculating mincha ketana, (the preferred time to recite the mincha prayers in the opinion of the Rambam and others) that is 9.5 * shaos zmaniyos (temporal hours) after the start of the day, calculated using the start and end of the day passed to this method. The time from the start of day to the end of day are divided into 12 shaos zmaniyos (temporal hours), and mincha ketana is calculated as 9.5 of those shaos zmaniyos after the beginning of the day. As an example, passing sunrise and sunset or sea and sea level sunset (depending on the isUseElevation elevation setting) to this method will return mincha ketana according to the opinion of the GRA.
A generic method for calculating plag hamincha (the earliest time that Shabbos can be started) that is 10.75 hours after the start of the day, (or 1.25 hours before the end of the day) based on the start and end of the day passed to the method. The time from the start of day to the end of day are divided into 12 shaos zmaniyos (temporal hours), and plag hamincha is calculated as 10.75 of those shaos zmaniyos after the beginning of the day. As an example, passing sunrise and sunset or sea level and sea level sunset (depending on the isUseElevation elevation setting) to this method will return plag mincha according to the opinion of the GRA.
A generic method for calculating samuch lemincha ketana, / near mincha ketana time that is half an hour before .getMinchaKetana or 9 * shaos zmaniyos (temporal hours) after the start of the day, calculated using the start and end of the day passed to this method. The time from the start of day to the end of day are divided into 12 shaos zmaniyos (temporal hours), and samuch lemincha ketana is calculated as 9 of those shaos zmaniyos after the beginning of the day. For example, passing sunrise and sunset or sea and sea level sunset (depending on the isUseElevation elevation setting) to this method will return samuch lemincha ketana according to the opinion of the GRA.
A generic utility method for calculating any shaah zmanis (temporal hour) based zman with the day defined as the start and end of day (or night) and the number of shaahos zmaniyos passed to the method. This simplifies the code in other methods such as .getPlagHamincha and cuts down on code replication. As an example, passing sunrise and sunset or and sea level sunset (depending on the isUseElevation elevation setting) and 10.75 hours to this method will return plag mincha according to the opinion of the GRA.
A generic method for calculating the latest zman krias shema (time to recite shema in the morning) that is 3 * shaos zmaniyos (temporal hours) after the start of the day, calculated using the start and end of the day passed to this method. The time from the start of day to the end of day are divided into 12 shaos zmaniyos (temporal hours), and the latest zman krias shema is calculated as 3 of those shaos zmaniyos after the beginning of the day. As an example, passing sunrise and sunset or sea level sunrise and sea level sunset (depending on the isUseElevation elevation setting) to this method will return sof zman krias shema according to the opinion of the GRA.
A generic method for calculating the latest zman tfilah (time to recite the morning prayers) that is 4 * shaos zmaniyos (temporal hours) after the start of the day, calculated using the start and end of the day passed to this method. The time from the start of day to the end of day are divided into 12 shaos zmaniyos (temporal hours), and sof zman tfila is calculated as 4 of those shaos zmaniyos after the beginning of the day. As an example, passing sunrise and sunset or sea level sunrise and sea level sunset (depending on the isUseElevation elevation setting) to this method will return zman tfilah according to the opinion of the GRA.
A utility method that returns the time of an offset by degrees below or above the horizon of sunrise. Note that the degree offset is from the vertical, so for a calculation of 14 before sunrise, an offset of 14 + AstronomicalCalendar.GEOMETRIC_ZENITH = 104 would have to be passed as a parameter.
Returns the dip below the horizon before sunrise that matches the offset minutes on passed in as a parameter. For example passing in 72 minutes for a calendar set to the equinox in Jerusalem returns a value close to 16.1 Please note that this method is very slow and inefficient and should NEVER be used in a loop. TODO: Improve efficiency.
A utility method that returns the time of an offset by degrees below or above the horizon of sunset. Note that the degree offset is from the vertical, so for a calculation of 14 after sunset, an offset of 14 + AstronomicalCalendar.GEOMETRIC_ZENITH = 104 would have to be passed as a parameter.
Returns the dip below the horizon after sunset that matches the offset minutes on passed in as a parameter. For example passing in 72 minutes for a calendar set to the equinox in Jerusalem returns a value close to 16.1 Please note that this method is very slow and inefficient and should NEVER be used in a loop. TODO: Improve efficiency.
A method that returns sundial or solar noon. It occurs when the Sun is transiting the celestial meridian. In this class it is calculated as halfway between the sunrise and sunset passed to this method. This time can be slightly off the real transit time due to changes in declination (the lengthening or shortening day).
A utility method that will allow the calculation of a temporal (solar) hour based on the sunrise and sunset passed as parameters to this method. An example of the use of this method would be the calculation of a non-elevation adjusted temporal hour by passing in sea level sunrise and sea level sunset as parameters.
A method that returns the sunrise in UTC time without correction for time zone offset from GMT and without using daylight savings time. Non-sunrise and sunset calculations such as dawn and dusk, depend on the amount of visible light, something that is not affected by elevation. This method returns UTC sunrise calculated at sea level. This forms the base for dawn calculations that are calculated as a dip below the horizon before sunrise.
A method that returns the sunset in UTC time without correction for elevation, time zone offset from GMT and without using daylight savings time. Non-sunrise and sunset calculations such as dawn and dusk, depend on the amount of visible light, something that is not affected by elevation. This method returns UTC sunset calculated at sea level. This forms the base for dusk calculations that are calculated as a dip below the horizon after sunset.
A method that returns the sunrise in UTC time without correction for time zone offset from GMT and without using daylight savings time.
A method that returns the sunset in UTC time without correction for time zone offset from GMT and without using daylight savings time.
This is a utility method to determine if the current Date (date-time) passed in has a melacha (work) prohibition. Since there are many opinions on the time of tzais, the tzais for the current day has to be passed to this class. Sunset is the classes current day's .getElevationAdjustedSunset that observes the isUseElevation settings. The JewishCalendar.getInIsrael will be set by the inIsrael parameter.