ZmanimCalendar class

The ZmanimCalendar is arrow_expand specialized calendar that can calculate sunrise and 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. According to Rabbi Dovid Yehudah Bursztyn in his Zmanim Kehilchasam (second edition published in 2007) chapter 2 (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 {@link #setUseElevation(boolean)}. This will impact sunrise and sunset-based zmanim such as getSunrise, getSunset, getSofZmanShmaGRA, alos-based zmanim such as getSofZmanShmaMGA that are based on a fixed offset of sunrise or sunset and zmanim based on a percentage of the day such as ComplexZmanimCalendar.getSofZmanShmaMGA90MinutesZmanis 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 {@link ComplexZmanimCalendar#getSofZmanShmaMGA16Point1Degrees()} or ComplexZmanimCalendar.getSofZmanShmaBaalHatanya.

Note: It is important to read the technical notes on top of the AstronomicalCalculator 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 lemaaseh.

© Eliyahu Hershfeld 2004 - 2020

Implementers

ComplexZmanimCalendar

Constructors

ZmanimCalendar(): Default constructor will set a default GeoLocation.GeoLocation, a default AstronomicalCalculator.getDefault AstronomicalCalculator and default the calendar to the current date.
ZmanimCalendar.intGeolocation(GeoLocation location): A constructor that takes a GeoLocation as a parameter.

Properties

astronomicalCalculator ↔ AstronomicalCalculator: getter/setter pairinherited
geoLocation ↔ GeoLocation: getter/setter pairinherited
hashCode → int: The hash code for this object.
no setterinherited
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited

Methods

getAdjustedCalendar() → DateTime: Adjusts the Calendar to deal with edge cases where the location crosses the antimeridian.
inherited
getAlos72() → DateTime?: Method to return alos (dawn) calculated using 72 minutes before getSunrise sunrise or getSeaLevelSunrise 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.
getAlosHashachar() → DateTime?: Returns alos (dawn) based on the time when the sun is ZENITH_16_POINT_1 16.1° below the eastern GEOMETRIC_ZENITH geometric horizon before getSunrise. 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 getSunrise sunrise in Jerusalem on the equinox (on March 16, about 4 days before the astronomical equinox, the day that a solar hour is 60 minutes) is 16.1° below. See the GEOMETRIC_ZENITH constant.
getAstronomicalCalculator() → AstronomicalCalculator: A method that returns the currently set AstronomicalCalculator.
inherited
getBeginAstronomicalTwilight() → DateTime?: A method that returns the beginning of astronomical twilight using a zenith of ASTRONOMICAL_ZENITH.
inherited
getBeginCivilTwilight() → DateTime?: A method that returns the beginning of civil twilight (dawn) using a zenith of CIVIL_ZENITH.
inherited
getBeginNauticalTwilight() → DateTime?: A method that returns the beginning of nautical twilight using a zenith of NAUTICAL_ZENITH.
inherited
getCalendar() → DateTime: returns the Calendar object encapsulated in this class.
inherited
getCandleLighting() → DateTime?: A method to return candle lighting time, calculated as getCandleLightingOffset minutes before getSeaLevelSunset sea level sunset for Erev Shabat & Yom Tov, and calculated as after TZEIT HACOCHAVIM for secand Yom Tov or Erev Yom Tov after Shabat. Else This method will return null. Elevation adjustments are intentionally not performed by this method, but you can calculate it by passing the elevation adjusted sunset to getTimeOffset.
getCandleLightingOffset() → double: A method to get the offset in minutes before AstronomicalCalendar.getSeaLevelSunset sea level sunset which is used in calculating candle lighting time. The default time used is 18 minutes before sea level sunset. Some calendars use 15 minutes, while the custom in Jerusalem is to use a 40 minute offset. Please check the local custom for candle lighting time.
getChatzos() → DateTime?: This method returns chatzos (midday) following most opinions that chatzos is the midpoint between getSeaLevelSunrise sea level sunrise and getSeaLevelSunset 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 getSunTransit. In reality due to lengthening or shortening of day, this is not necessarily the exact midpoint of the day, but it is very close.
getDateFromTime(double time, bool isSunrise) → DateTime?: A method that returns a Date from the time passed in as a parameter.
inherited
getElevationAdjustedSunrise() → DateTime?: This method will return getSeaLevelSunrise sea level sunrise if isUseElevation is false (the default), or elevation adjusted AstronomicalCalendar.getSunrise if it is true. This allows relevant zmanim in this and extending classes (such as the ComplexZmanimCalendar to automatically adjust to the elevation setting.
getElevationAdjustedSunset() → DateTime?: This method will return getSeaLevelSunrise sea level sunrise} if isUseElevation is false (the default), or elevation adjusted AstronomicalCalendar.getSunrise if it is true. This allows relevant zmanim in this and extending classes (such as the ComplexZmanimCalendar to automatically adjust to the elevation setting.
getEndAstronomicalTwilight() → DateTime?: A method that returns the end of astronomical twilight using a zenith of ASTRONOMICAL_ZENITH.
inherited
getEndCivilTwilight() → DateTime?: A method that returns the end of civil twilight using a zenith of CIVIL_ZENITH.
inherited
getEndNauticalTwilight() → DateTime?: A method that returns the end of nautical twilight using a zenith of NAUTICAL_ZENITH.
inherited
getGeoLocation() → GeoLocation: A method that returns the currently set GeoLocation which contains location information used for the astronomical calculations.
inherited
getMinchaGedola([DateTime? startOfDay, DateTime? endOfDay]) → DateTime?: 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 getSunrise sunrise and getSunset sunset or getSeaLevelSunrise sea level sunrise and getSeaLevelSunset sea level sunset (depending on the isUseElevation elevation setting) to this method will return mincha gedola according to the opinion of the GRA.
getMinchaKetana([DateTime? startOfDay, DateTime? endOfDay]) → DateTime?: 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 getSunrise sunrise and getSunset sunset or getSeaLevelSunrise sea level sunrise and getSeaLevelSunset sea level sunset (depending on the isUseElevation elevation setting) to this method will return mincha ketana according to the opinion of the GRA.
getPlagHamincha([DateTime? startOfDay, DateTime? endOfDay]) → DateTime?: 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 getSunrise sunrise and getSunset sunset or getSeaLevelSunrise sea level sunrise and getSeaLevelSunset sea level sunset (depending on the isUseElevation elevation setting) to this method will return plag mincha according to the opinion of the GRA.
getSeaLevelSunrise() → DateTime?: A method that returns the sunrise without AstronomicalCalculator.getElevationAdjustment. 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.
inherited
getSeaLevelSunset() → DateTime?: A method that returns the sunset without AstronomicalCalculator.getElevationAdjustment. 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.
inherited
getShaahZmanisBasedZman(DateTime startOfDay, DateTime endOfDay, double hours) → DateTime?: 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 getSunrise and getSunset or {@link #getSeaLevelSunrise() sea level sunrise} and getSeaLevelSunset (depending on the isUseElevation elevation setting) and 10.75 hours to this method will return plag mincha according to the opinion of the GRA.
getShaahZmanisGra() → double: A method that returns a shaah zmanis (getTemporalHour 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 from getSeaLevelSunrise sea level sunrise to getSeaLevelSunrise sea level sunset or getSunrise sunrise to getSunset 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 getTemporalHour, but can account for elevation.
getShaahZmanisMGA() → double: 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 getSunrise sunrise or getSeaLevelSunrise sea level sunrise (depending on the isUseElevation elevation setting) and dusk is 72 minutes after getSunset sunset or getSeaLevelSunset 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.
getSofZmanShma(DateTime? startOfDay, DateTime? endOfDay) → DateTime?: 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 getSunrise and getSunset or getSeaLevelSunrise sea level sunrise and getSeaLevelSunset 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.
getSofZmanShmaGRA() → DateTime?: This method returns the latest zman krias shema (time to recite shema in the morning) that is 3 * getShaahZmanisGra shaos zmaniyos (solar hours) after getSunrise sunrise or getSeaLevelSunrise sea level sunrise (depending on the isUseElevation setting), according to the GRA. The day is calculated from getSeaLevelSunrise sea level sunrise to getSeaLevelSunrise sea level sunset or getSunrise sunrise to getSunset sunset (depending on the isUseElevation setting).
getSofZmanShmaMGA() → DateTime?: This method returns the latest zman krias shema (time to recite shema in the morning) that is 3 * getShaahZmanisMGA shaos zmaniyos (solar hours) after getAlos72, according to the Magen Avraham (MGA). The day is calculated from 72 minutes before getSeaLevelSunrise sea level sunrise} to 72 minutes after getSeaLevelSunrise sea level sunset or from 72 minutes before getSunrise sunrise to getSunset sunset (depending on the isUseElevation setting).
getSofZmanTfila(DateTime? startOfDay, DateTime? endOfDay) → DateTime?: 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 getSunrise sunrise and getSunset sunset or getSeaLevelSunrise sea level sunrise and getSeaLevelSunset sea level sunset (depending on the isUseElevation elevation setting) to this method will return zman tfilah according to the opinion of the GRA.
getSofZmanTfilaGRA() → DateTime?: This method returns the latest zman tfila (time to recite shema in the morning) that is 4 * getShaahZmanisGra shaos zmaniyos (solar hours) after getSunrise sunrise or getSeaLevelSunrise sea level sunrise (depending on the isUseElevation setting), according to the GRA. The day is calculated from getSeaLevelSunrise sea level sunrise to getSeaLevelSunrise sea level sunset or getSunrise sunrise to getSunset sunset (depending on the isUseElevation setting).
getSofZmanTfilaMGA() → DateTime?: This method returns the latest zman tfila (time to recite shema in the morning) that is 4 * getShaahZmanisMGA] shaos zmaniyos (solar hours) after getAlos72 according to the Magen Avraham (MGA). The day is calculated from 72 minutes before getSeaLevelSunrise sea level sunrise to 72 minutes after getSeaLevelSunrise sea level sunset or from 72 minutes before getSunrise sunrise to getSunset sunset (depending on the isUseElevation setting).
getSunrise() → DateTime?: The getSunrise method Returns a Date representing the AstronomicalCalculator.getElevationAdjustment 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 AstronomicalCalculator.adjustZenith. See documentation for the specific implementation of the AstronomicalCalculator that you are using.
inherited
getSunriseOffsetByDegrees(double offsetZenith) → DateTime?: A utility method that returns the time of an offset by degrees below or above the horizon of getSunrise. Note that the degree offset is from the vertical, so for a calculation of 14° before sunrise, an offset of 14 + GEOMETRIC_ZENITH = 104 would have to be passed as a parameter.
inherited
getSunriseSolarDipFromOffset(double minutes) → double: 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.
inherited
getSunset() → DateTime?: The getSunset method Returns a Date representing the AstronomicalCalculator.getElevationAdjustment 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 AstronomicalCalculator.adjustZenith. 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.
inherited
getSunsetOffsetByDegrees(double offsetZenith) → DateTime?: A utility method that returns the time of an offset by degrees below or above the horizon of getSunset. Note that the degree offset is from the vertical, so for a calculation of 14° after sunset, an offset of 14 + GEOMETRIC_ZENITH = 104 would have to be passed as a parameter.
inherited
getSunsetSolarDipFromOffset(double minutes) → double: 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.
inherited
getSunTransit([DateTime? startOfDay, DateTime? endOfDay]) → DateTime?: A method that returns sundial or solarnoon. 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).
inherited
getTemporalHour([DateTime? startOfDay, DateTime? endOfDay]) → double: 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 getSeaLevelSunrise and getSeaLevelSunset as parameters.
inherited
getTzais() → DateTime?: A method that returns tzais (nightfall) when the sun is ZENITH_8_POINT_5 8.5° below the GEOMETRIC_ZENITH geometric horizon (90°) after getSunset 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.
getTzais72() → DateTime?: 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 getSunset or getSeaLevelSunset is used.
getUTCSeaLevelSunrise(double zenith) → double: 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.
inherited
getUTCSeaLevelSunset(double zenith) → double: 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.
inherited
getUTCSunrise(double zenith) → double: A method that returns the sunrise in UTC time without correction for time zone offset from GMT and without using daylight savings time.
inherited
getUTCSunset(double zenith) → double: A method that returns the sunset in UTC time without correction for time zone offset from GMT and without using daylight savings time.
inherited
isAssurBemlacha(DateTime currentTime, DateTime tzais, bool inIsrael) → bool: 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 elevation adjusted sunset that observes the isUseElevation settings. The JewishCalendar#getInIsrael will be set by the inIsrael parameter.
isUseElevation() → bool: Is elevation above sea level calculated for times besides sunrise and sunset. According to Rabbi Dovid Yehuda Bursztyn in his Zmanim Kehilchasam (second edition published in 2007) chapter 2 (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 <a href= 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), unless the setting is changed to true in setUseElevation. This will impact sunrise and sunset based zmanim such as getSunrise(), getSunset, getSofZmanShmaGRA, alos based zmanim such as _getSofZmanShmaMGA that are based on a fixed offset of sunrise or sunset and zmanim based on a percentage of the day such as ComplexZmanimCalendar.getSofZmanShmaMGA90MinutesZmanis that are based on sunrise and sunset. It will not impact zmanim that are a degree based offset of sunrise and sunset, such as ComplexZmanimCalendar.getSofZmanShmaMGA16Point1Degrees or ComplexZmanimCalendar.getSofZmanShmaBaalHatanya. /// return if the use of elevation is active /// see setUseElevation
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
setAstronomicalCalculator(AstronomicalCalculator astronomicalCalculator) → void: 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 SunTimesCalculator based on the US Naval Observatory's algorithm, and NOAACalculator based on NOAA's algorithm. This allows easy runtime switching and comparison of different algorithms.
inherited
setCalendar(DateTime calendar) → void: calendar: The calendar to set.

inherited
setCandleLightingOffset(double candleLightingOffset) → void: A method to set the offset in minutes before AstronomicalCalendar.getSeaLevelSunset sea level sunset that is used in calculating candle lighting time. The default time used is 18 minutes before sunset. Some calendars use 15 minutes, while the custom in Jerusalem is to use a 40 minute offset.
setGeoLocation(GeoLocation geoLocation) → void: Sets the GeoLocation Object to be used for astronomical calculations.
inherited
setUseElevation(bool useElevation) → void: Sets whether elevation above sea level is factored into zmanim calculations for times besides sunrise and sunset. See isUseElevation for more details.
toString() → String: A string representation of this object.
inherited

Operators

operator ==(Object object) → bool: See also Object.equals.
inherited

Constants

ZENITH_8_POINT_5 → const double: The zenith of 8.5° below geometric zenith (90°). This calculation is used for calculating alos (dawn) and tzais (nightfall) in some opinions. This calculation is based on the position of the sun 36 minutes after getSunset in Jerusalem on March 16, about 4 days before the equinox, the day that a solar hour is 60 minutes, which is 8.5° below GEOMETRIC_ZENITH. The Ohr Meir considers this the time that 3 small stars are visible, which is later than the required 3 medium stars.
ZENITH_16_POINT_1 → const double: The zenith of 16.1° below geometric zenith (90°). This calculation is used for determining alos (dawn) and tzais (nightfall) in some opinions. It 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 equinox (on March 16, about 4 days before the astronomical equinox, the day that a solar hour is 60 minutes) is 16.1° below geometric zenith.