Package com.kosherjava.zmanim

Class ZmanimCalendar

java.lang.Object
com.kosherjava.zmanim.AstronomicalCalendar
com.kosherjava.zmanim.ZmanimCalendar
All Implemented Interfaces:
Cloneable
Direct Known Subclasses:
ComplexZmanimCalendar
public class ZmanimCalendar extends AstronomicalCalendar
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 setUseElevation(boolean). This will impact sunrise and sunset-based zmanim such as AstronomicalCalendar.getSunrise(), AstronomicalCalendar.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 ComplexZmanimCalendar.getSofZmanShmaMGA16Point1Degrees() 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:

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 lema'aseh.
Author:
© Eliyahu Hershfeld 2004 - 2024

  • Field Details

  • Constructor Details

  • Method Details

    • isUseElevation

      public boolean isUseElevation()
      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 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(boolean). This will impact sunrise and sunset based zmanim such as AstronomicalCalendar.getSunrise(), AstronomicalCalendar.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().
      Returns:
      if the use of elevation is active
      See Also:

    • setUseElevation

      public void setUseElevation(boolean useElevation)
      Sets whether elevation above sea level is factored into zmanim calculations for times besides sunrise and sunset. See isUseElevation() for more details.
      Parameters:
      useElevation - set to true to use elevation in zmanim calculations
      See Also:

    • isUseAstronomicalChatzos

      public boolean isUseAstronomicalChatzos()
      Is astronomical chatzos used for getChatzos() for enhanced accuracy. For example as the day is lengthens, the second half of the day is longer than the first and astronomical chatzos would be a drop earlier than half of the time between sunrise and sunset.
      Returns:
      if the use of astronomical chatzos is active.
      See Also:
      TODO:
      In the future, if this is set to true, the following may change to enhance accuracy. Sof zman Shma GRA would be calculated as 3 shaaos zmaniyos after sunrise, but the shaaos zmaniyos would be calculated a a 6th of the time between sunrise and chatzos, as opposed to a 12th of the time between sunrise and sunset. mincha gedola will be calculated as half a shaah zmanis of afternoon hours (a 6th of the time between chatzos and sunset after astronomical chatzos as opposed to 6.5 shaaos zmaniyos after sunrise. Plag hamincha would be calculated as 4.75 shaaos zmaniyos after astronomical chatzos as opposed to 10.75 shaaos zmaniyos after sunrise. Etc.

    • setUseAstronomicalChatzos

      public void setUseAstronomicalChatzos(boolean useAstronomicalChatzos)
      Sets if astronomical chatzos should be used in calculations of other zmanim for enhanced accuracy.
      Parameters:
      useAstronomicalChatzos - set to true to use astronomical in chatzos in zmanim calculations.
      See Also:

    • isUseAstronomicalChatzosForOtherZmanim

      public boolean isUseAstronomicalChatzosForOtherZmanim()
      Is astronomical chatzos used for zmanim calculations besides chatzos itself for enhanced accuracy. For example as the day is lengthening (as we approach spring season), the second half of the day is longer than the first and astronomical chatzos would be a drop earlier than half of the time between sunrise and sunset. Conversely, the second half of the day would be shorter in the fall season as the days start getting shorter.
      Returns:
      if the use of astronomical chatzos is active.
      See Also:
      TODO:
      In the future, if this is set to true, the following may change to enhance accuracy. Sof zman Shma GRA would be calculated as 3 shaaos zmaniyos after sunrise, but the shaaos zmaniyos would be calculated a a 6th of the time between sunrise and chatzos, as opposed to a 12th of the time between sunrise and sunset. mincha gedola will be calculated as half a shaah zmanis of afternoon hours (a 6th of the time between chatzos and sunset after astronomical chatzos as opposed to 6.5 shaaos zmaniyos after sunrise. Plag hamincha would be calculated as 4.75 shaaos zmaniyos after astronomical chatzos as opposed to 10.75 shaaos zmaniyos after sunrise. Etc.

    • setUseAstronomicalChatzosForOtherZmanim

      public void setUseAstronomicalChatzosForOtherZmanim(boolean useAstronomicalChatzosForOtherZmanim)
      Sets if astronomical chatzos should be used in calculations of other zmanim for enhanced accuracy.
      Parameters:
      useAstronomicalChatzosForOtherZmanim - set to true to use astronomical in chatzos in zmanim calculations.
      See Also:

    • getElevationAdjustedSunrise

      protected Date getElevationAdjustedSunrise()
      This method will return 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.
      Returns:
      AstronomicalCalendar.getSeaLevelSunrise() if isUseElevation() is false (the default), or elevation adjusted AstronomicalCalendar.getSunrise() if it is true.
      See Also:

    • getElevationAdjustedSunset

      protected Date getElevationAdjustedSunset()
      This method will return 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.
      Returns:
      AstronomicalCalendar.getSeaLevelSunset() if isUseElevation() is false (the default), or elevation adjusted AstronomicalCalendar.getSunset() if it is true.
      See Also:

    • getTzais

      public Date getTzais()
      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.
      Returns:
      The Date of nightfall. If the calculation can't be computed such as northern and southern locations even south of the Arctic Circle and north of the Antarctic Circle where the sun may not reach low enough below the horizon for this calculation, a null will be returned. See detailed explanation on top of the AstronomicalCalendar documentation.
      See Also:

    • getAlosHashachar

      public Date getAlosHashachar()
      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 / equilux is 16.1° below AstronomicalCalendar.GEOMETRIC_ZENITH.
      Returns:
      The Date of dawn. If the calculation can't be computed such as northern and southern locations even south of the Arctic Circle and north of the Antarctic Circle where the sun may not reach low enough below the horizon for this calculation, a null will be returned. See detailed explanation on top of the AstronomicalCalendar documentation.
      See Also:

    • getAlos72

      public Date getAlos72()
      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:
      the Date representing the time. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the AstronomicalCalendar documentation.

    • getChatzos

      public Date getChatzos()
      This method returns Astronomical chatzos if the calculator class used supports it and isUseAstronomicalChatzos() is set to true or the halfway point between sunrise and sunset if it does not support it or it is not configured to use it. There are currently two calculators available in the API, the default NOAA calculator and the USNO calculator. The USNO calculator calculates chatzos as halfway between sunrise and sunset (identical to six shaaos zmaniyos after sunrise), while the NOAACalculator calculates it more accurately as astronomical chatzos. See The Definition of Chatzos for a detailed explanation of the ways to calculate Chatzos. Since half-day chatzos can be null in the Arctic on a day when either sunrise or sunset did not happen and astronomical chatzos can be calculated even in the Arctic, if half-day chatzos calculates as null and astronomical chatzos is supported by the calculator, astronomical chatzos will be returned to avoid returning a null.
      Returns:
      the Date of chatzos. If the calculation can't be computed such as in the Arctic Circle where there is at least one day where the sun does not rise, and one where it does not set, and the calculator does not support astronomical calculations (that will never report a null) a null will be returned. See detailed explanation on top of the AstronomicalCalendar documentation.
      See Also:

    • getChatzosAsHalfDay

      public Date getChatzosAsHalfDay()
      Returns chatzos calculated as halfway between sunrise and sunset. Many are of the opinion opinion that chatzos is calculated as the the midpoint between sea level sunrise and sea level sunset, despite it not being the most accurate way to calculate it. A day starting at alos and ending at tzais using the same time or degree offset will also return the same time. In reality due to lengthening or shortening of day, this is not necessarily the exact midpoint of the day, but it is very close. This method allows you to use the NOAACalculator and still calculate chatzos as six shaaos zmaniyos after sunrise. There are currently two calculators available in the API, the NOAACalculator and the SunTimesCalculator. The SunTimesCalculator calculates chatzos as halfway between sunrise and sunset (and of six shaaos zmaniyos), while the NOAACalculator calculates it as astronomical chatzos that is slightly more accurate. This method allows you to use the NOAACalculator and still calculate chatzos as six shaaos zmaniyos after sunrise. See The Definition of Chatzos for a detailed explanation of the ways to calculate Chatzos.
      Returns:
      the Date of the latest chatzos. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the AstronomicalCalendar documentation.
      See Also:

    • getSofZmanShma

      public Date getSofZmanShma(Date startOfDay, Date endOfDay, boolean synchronous)
      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. If isUseAstronomicalChatzosForOtherZmanim() is true, the 3 shaos zmaniyos will be based on 1/6 of the time between sunrise and astronomical chatzos. As an example, passing sunrise and sunset or sea level sunrise and sea level sunset to this method (or getElevationAdjustedSunrise() and getElevationAdjustedSunset() that is driven off the isUseElevation() setting) will return sof zman krias shema according to the opinion of the GRA. In cases where the start and end dates are not synchronous such as in #getSofZmanShmaAlos16Point1ToTzaisGeonim7Point083Degrees() false should be passed to the synchronous parameter to ensure that isUseAstronomicalChatzosForOtherZmanim() will not be used.
      Parameters:
      startOfDay - the start of day for calculating zman krias shema. This can be sunrise or any alos passed to this method.
      endOfDay - the end of day for calculating zman krias shema. This can be sunset or any tzais passed to this method.
      synchronous - If the zman has a synchronous start and end of the day. If this is false, using a isUseAstronomicalChatzosForOtherZmanim() makes no sense and will be ignored even if set to true, since by definition chatzos will not be the middle of the day for the zman.
      Returns:
      the Date of the latest zman shema based on the start and end of day times passed to this method. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the AstronomicalCalendar documentation.
      See Also:

    • getSofZmanShma

      public Date getSofZmanShma(Date startOfDay, Date endOfDay)
      A generic method for calculating the latest zman krias shema that calls getSofZmanShma(Date, Date, boolean) passing false to the synchronous parameter since there is now way to know if the start and end of the day are synchronous. Passing true when they are not synchronous is too much of a risk. See information on that method for more details.
      Parameters:
      startOfDay - the start of day for calculating zman krias shema. This can be sunrise or any alos passed to this method.
      endOfDay - the end of day for calculating zman krias shema. This can be sunset or any tzais passed to this method.
      Returns:
      the Date of the latest zman shema based on the start and end of day times passed to this method. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the AstronomicalCalendar documentation.
      See Also:

    • getSofZmanShmaGRA

      public Date getSofZmanShmaGRA()
      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 sunset or sunrise to sunset (depending on the isUseElevation() setting).
      Returns:
      the Date of the latest zman shema according to the GRA. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See the detailed explanation on top of the AstronomicalCalendar documentation.
      See Also:

    • getSofZmanShmaMGA

      public Date getSofZmanShmaMGA()
      This method returns the latest zman krias shema (time to recite shema in the morning) that is 3 * shaos zmaniyos (solar hours) after getAlos72(), according to the Magen Avraham (MGA). The day is calculated from 72 minutes before sea level sunrise to 72 minutes after sea level sunset or from 72 minutes before sunrise to sunset (depending on the isUseElevation() setting).
      Returns:
      the Date of the latest zman shema. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the AstronomicalCalendar documentation.
      See Also:

    • getTzais72

      public Date getTzais72()
      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.
      Returns:
      the Date representing 72 minutes after sunset. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned See detailed explanation on top of the AstronomicalCalendar documentation.
      See Also:

    • getCandleLighting

      public Date getCandleLighting()
      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 AstronomicalCalendar.getTimeOffset(Date, long).
      Returns:
      candle lighting time. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the AstronomicalCalendar documentation.
      See Also:

    • getSofZmanTfila

      public Date getSofZmanTfila(Date startOfDay, Date endOfDay, boolean synchronous)
      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. This method's synchronous parameter indicates if the start and end of day for the calculation are synchronous, having the same offset. This is typically the case, but some zmanim calculations are based on a start and end at different offsets from the real start and end of the day, such as starting the day at alos and an ending it at tzais genoim or some other variant. If the day is not synchronous a half-day based calculations will be bypassed. It would be illogical to use a half-day based calculation that start/end at chatzos when the two "halves" of the day are not equal, and the halfway point between them is not at chatzos.
      Parameters:
      startOfDay - the start of day for calculating zman tfilah. This can be sunrise or any alos passed to this method.
      endOfDay - the end of day for calculating zman tfilah. This can be sunset or any tzais passed to this method.
      synchronous - If the zman has a synchronous start and end of the day. If this is false, using a isUseAstronomicalChatzosForOtherZmanim() makes no sense and will be ignored even if set to true, since by definition chatzos will not be the middle of the day for the zman.
      Returns:
      the Date of the latest zman tfilah based on the start and end of day times passed to this method. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the AstronomicalCalendar documentation.

    • getSofZmanTfila

      public Date getSofZmanTfila(Date startOfDay, Date endOfDay)
      A generic method for calculating the latest zman tfila that calls getSofZmanTfila(Date, Date, boolean) passing false to the synchronous parameter since there is now way to know if the start and end of the day are synchronous. Passing true when they are not synchronous is too much of a risk. See information on that method for more details.
      Parameters:
      startOfDay - the start of day for calculating zman tfilah. This can be sunrise or any alos passed to this method.
      endOfDay - the end of day for calculating zman tfilah. This can be sunset or any tzais passed to this method.
      Returns:
      the Date of the latest zman tfilah based on the start and end of day times passed to this method. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the AstronomicalCalendar documentation.
      See Also:

    • getSofZmanTfilaGRA

      public Date getSofZmanTfilaGRA()
      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 sunset or sunrise to sunset (depending on the isUseElevation() setting).
      Returns:
      the Date of the latest zman tfilah. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the AstronomicalCalendar documentation.
      See Also:

    • getSofZmanTfilaMGA

      public Date getSofZmanTfilaMGA()
      This method returns the latest zman tfila (time to recite shema in the morning) that is 4 * shaos zmaniyos (solar hours) after getAlos72(), according to the Magen Avraham (MGA). The day is calculated from 72 minutes before sea level sunrise to 72 minutes after sea level sunset or from 72 minutes before sunrise to sunset (depending on the isUseElevation() setting).
      Returns:
      the Date of the latest zman tfila. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set), a null will be returned. See detailed explanation on top of the AstronomicalCalendar documentation.
      See Also:

    • getMinchaGedola

      public Date getMinchaGedola(Date startOfDay, Date endOfDay, boolean synchronous)
      A generic method for calculating mincha gedola (the earliest time to recite the mincha1 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 sunrise and sea level sunset (depending on the isUseElevation() elevation setting) to this method will return mincha gedola according to the opinion of the GRA. Alternatively, this method uses isUseAstronomicalChatzosForOtherZmanim() to control if the time is based on 6.5 sha'os zmaniyos into the day mentioned above, or as half an hour zmaniyos based on the second half of the day after chatzos (astronomical chatzos if supported by the calculator and configured or chatzos as half a day if not. This method's synchronous parameter indicates if the start and end of day for the calculation are synchronous, having the same offset. This is typically the case, but some zmanim calculations are based on a start and end at different offsets from the real start and end of the day, such as starting the day at alos and an ending it at tzais genoim or some other variant. If the day is not synchronous a half-day based calculations will be bypassed. It would be illogical to use a half-day based calculation that start/end at chatzos when the two "halves" of the day are not equal, and the halfway point between them is not at chatzos.
      Parameters:
      startOfDay - the start of day for calculating Mincha gedola. This can be sunrise or any alos passed to this method.
      endOfDay - the end of day for calculating Mincha gedola. This can be sunset or any tzais passed to this method.
      synchronous - If the zman has a synchronous start and end of the day. If this is false, using a isUseAstronomicalChatzosForOtherZmanim() makes no sense and will be ignored even if set to true, since by definition chatzos will not be the middle of the day for the zman.
      Returns:
      the Date of the time of Mincha gedola based on the start and end of day times passed to this method. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the AstronomicalCalendar documentation.
      See Also:

    • getMinchaGedola

      public Date getMinchaGedola(Date startOfDay, Date endOfDay)
      A generic method for calculating mincha gedola that calls getMinchaGedola(Date, Date, boolean) passing false to the synchronous parameter since there is now way to know if the start and end of the day are synchronous. Passing true when they are not synchronous is too much of a risk. See information on that method for more details.
      Parameters:
      startOfDay - the start of day for calculating Mincha gedola. This can be sunrise or any alos passed to this method.
      endOfDay - the end of day for calculating Mincha gedola. This can be sunset or any tzais passed to this method.
      Returns:
      the Date of the latest Mincha gedola based on the start and end of day times passed to this method. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the AstronomicalCalendar documentation.
      See Also:

    • getMinchaGedola

      public Date getMinchaGedola()
      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 mincha ketana 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 sunset or sunrise to sunset (depending on the isUseElevation() setting).
      Returns:
      the Date of the time of mincha gedola. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the AstronomicalCalendar documentation.
      See Also:
      TODO:
      Consider adjusting this to calculate the time as half an hour zmaniyos after either astronomical chatzos or chatzos as half a day for calculators that support it, based on isUseAstronomicalChatzos().

    • getSamuchLeMinchaKetana

      public Date getSamuchLeMinchaKetana(Date startOfDay, Date endOfDay, boolean synchronous)
      A generic method for calculating samuch lemincha ketana, / near mincha ketana time that is half an hour before getMinchaKetana(Date, Date) 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 level sunrise 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. See the Mechaber and Mishna Berurah 232 and 249:2.
      Parameters:
      startOfDay - the start of day for calculating samuch lemincha ketana. This can be sunrise or any alos passed to to this method.
      endOfDay - the end of day for calculating samuch lemincha ketana. This can be sunset or any tzais passed to this method.
      synchronous - If the zman has a synchronous start and end of the day. If this is false, using a isUseAstronomicalChatzosForOtherZmanim() makes no sense and will be ignored even if set to true, since by definition chatzos will not be the middle of the day for the zman.
      Returns:
      the Date of the time of Mincha ketana based on the start and end of day times passed to this method. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the AstronomicalCalendar documentation.
      See Also:

    • getSamuchLeMinchaKetana

      public Date getSamuchLeMinchaKetana(Date startOfDay, Date endOfDay)
      A generic method for calculating samuch lemincha ketana that calls getSamuchLeMinchaKetana(Date, Date, boolean) passing false to the synchronous parameter since there is now way to know if the start and end of the day are synchronous. Passing true when they are not synchronous is too much of a risk. See information on that method for more details.
      Parameters:
      startOfDay - the start of day for calculating samuch lemincha ketana. This can be sunrise or any alos passed to to this method.
      endOfDay - the end of day for calculating samuch lemincha ketana. This can be sunset or any tzais passed to this method.
      Returns:
      the Date of the time of samuch lemincha ketana based on the start and end of day times passed to this method. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the AstronomicalCalendar documentation.
      See Also:

    • getMinchaKetana

      public Date getMinchaKetana(Date startOfDay, Date endOfDay, boolean synchronous)
      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 level sunrise and sea level sunset (depending on the isUseElevation() elevation setting) to this method will return mincha ketana according to the opinion of the GRA. This method's synchronous parameter indicates ifthe start and end of day for the calculation are synchronous, having the same offset. This is typically the case, but some zmanim calculations are based on a start and end at different offsets from the real start and end of the day, such as starting the day at alos and an ending it at tzais genoim or some other variant. If the day is not synchronous a half-day based calculations will be bypassed. It would be illogical to use a half-day based calculation that start/end at chatzos when the two "halves" of the day are not equal, and the halfway point between them is not at chatzos.
      Parameters:
      startOfDay - the start of day for calculating Mincha ketana. This can be sunrise or any alos passed to this method.
      endOfDay - the end of day for calculating Mincha ketana. This can be sunset or any tzais passed to this method.
      synchronous - If the zman has a synchronous start and end of the day. If this is false, using a isUseAstronomicalChatzosForOtherZmanim() makes no sense and will be ignored even if set to true, since by definition chatzos will not be the middle of the day for the zman.
      Returns:
      the Date of the time of Mincha ketana based on the start and end of day times passed to this method. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the AstronomicalCalendar documentation.

    • getMinchaKetana

      public Date getMinchaKetana(Date startOfDay, Date endOfDay)
      A generic method for calculating mincha ketana that calls getMinchaKetana(Date, Date, boolean) passing false to the synchronous parameter since there is now way to know if the start and end of the day are synchronous. Passing true when they are not synchronous is too much of a risk. See information on that method for more details.
      Parameters:
      startOfDay - the start of day for calculating Mincha ketana. This can be sunrise or any alos passed to this method.
      endOfDay - the end of day for calculating Mincha ketana. This can be sunset or any tzais passed to this method.
      Returns:
      the Date of the time of Mincha ketana based on the start and end of day times passed to this method. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the AstronomicalCalendar documentation.
      See Also:

    • getMinchaKetana

      public Date getMinchaKetana()
      This method returns mincha ketana,the preferred earliest time to pray mincha in the opinion of the Rambam and others, that is 9.5 * shaos zmaniyos (solar hours) after sunrise or sea level sunrise (depending on the isUseElevation() setting), according to the GRA. For more information on this see the documentation on mincha gedola. The day is calculated from sea level sunrise to sea level sunset or sunrise to sunset (depending on the isUseElevation() setting.
      Returns:
      the Date of the time of mincha ketana. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the AstronomicalCalendar documentation.
      See Also:

    • getPlagHamincha

      public Date getPlagHamincha(Date startOfDay, Date endOfDay, boolean synchronous)
      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 sunrise and sea level sunset (depending on the isUseElevation() elevation setting) to this method will return plag mincha according to the opinion of the GRA. This method's synchronous parameter indicates if the start and end of day for the calculation are synchronous, having the same offset. This is typically the case, but some zmanim calculations are based on a start and end at different offsets from the real start and end of the day, such as starting the day at alos and an ending it at tzais genoim or some other variant. If the day is not synchronous a half-day based calculations will be bypassed. It would be illogical to use a half-day based calculation that start/end at chatzos when the two "halves" of the day are not equal, and the halfway point between them is not at chatzos.
      Parameters:
      startOfDay - the start of day for calculating plag hamincha. This can be sunrise or any alos passed to this method.
      endOfDay - the end of day for calculating plag hamincha. This can be sunset or any tzais passed to this method.
      synchronous - If the zman has a synchronous start and end of the day. If this is false, using a isUseAstronomicalChatzosForOtherZmanim() makes no sense and will be ignored even if set to true, since by definition chatzos will not be the middle of the day for the zman.
      Returns:
      the Date of the time of plag hamincha based on the start and end of day times passed to this method. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the AstronomicalCalendar documentation.

    • getPlagHamincha

      public Date getPlagHamincha(Date startOfDay, Date endOfDay)
      A generic method for calculating plag hamincha that calls getPlagHamincha(Date, Date, boolean) passing false to the synchronous parameter since there is no way to know if the start and end of the day are synchronous. Passing true when they are not synchronous is too much of a risk. See information on that method for more details.
      Parameters:
      startOfDay - the start of day for calculating plag hamincha. This can be sunrise or any alos passed to this method.
      endOfDay - the end of day for calculating plag hamincha. This can be sunset or any tzais passed to this method.
      Returns:
      the Date of the time of plag hamincha based on the start and end of day times passed to this method. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the AstronomicalCalendar documentation.
      See Also:

    • getPlagHamincha

      public Date getPlagHamincha()
      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 sunset or sunrise to sunset (depending on the isUseElevation()
      Returns:
      the Date of the time of plag hamincha. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the AstronomicalCalendar documentation.
      See Also:

    • getShaahZmanisGra

      public long getShaahZmanisGra()
      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 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 AstronomicalCalendar.getTemporalHour(), but can account for elevation.
      Returns:
      the long millisecond length of a shaah zmanis calculated from sunrise to sunset. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, Long.MIN_VALUE will be returned. See detailed explanation on top of the AstronomicalCalendar documentation.
      See Also:

    • getShaahZmanisMGA

      public long getShaahZmanisMGA()
      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.
      Returns:
      the long millisecond length of a shaah zmanis. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, Long.MIN_VALUE will be returned. See detailed explanation on top of the AstronomicalCalendar documentation.

    • getCandleLightingOffset

      public double getCandleLightingOffset()
      A method to get the offset in minutes before 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.
      Returns:
      Returns the currently set candle lighting offset in minutes.
      See Also:

    • setCandleLightingOffset

      public void setCandleLightingOffset(double candleLightingOffset)
      A method to set the offset in minutes before 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.
      Parameters:
      candleLightingOffset - The candle lighting offset to set in minutes.
      See Also:

    • isAssurBemlacha

      public boolean isAssurBemlacha(Date currentTime, Date tzais, boolean inIsrael)
      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 elevation adjusted sunset that observes the isUseElevation() settings. The JewishCalendar.getInIsrael() will be set by the inIsrael parameter.
      Parameters:
      currentTime - the current time
      tzais - the time of tzais
      inIsrael - whether to use Israel holiday scheme or not
      Returns:
      true if melacha is prohibited or false if it is not.
      See Also:

    • getShaahZmanisBasedZman

      public Date getShaahZmanisBasedZman(Date startOfDay, Date endOfDay, double hours)
      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(Date, Date) and cuts down on code replication. As an example, passing sunrise and sunset or sea level sunrise 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.
      Parameters:
      startOfDay - the start of day for calculating the zman. This can be sunrise or any alos passed to this method.
      endOfDay - the end of day for calculating the zman. This can be sunset or any tzais passed to this method.
      hours - the number of shaahos zmaniyos (temporal hours) to offset from the start of day
      Returns:
      the Date of the time of zman with the shaahos zmaniyos (temporal hours) in the day offset from the start of day passed to this method. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the AstronomicalCalendar documentation.

    • getPercentOfShaahZmanisFromDegrees

      public double getPercentOfShaahZmanisFromDegrees(double degrees, boolean sunset)
      A utility method that returns the percentage of a shaah zmanis after sunset (or before sunrise) for a given degree offset. For the equilux where there is a 720-minute day, passing 16.1° for the location of Jerusalem will return about 1.2. This will work for any location or date, but will typically only be of interest at the equinox/equilux to calculate the percentage of a shaah zmanis for those who want to use the Minchas Cohen in Ma'amar 2:4 and the Pri Chadash who calculate tzais as a percentage of the day after sunset. While the Minchas Cohen only applies this to 72 minutes or a 1/10 of the day around the world (based on the equinox / equilux in Israel, this method allows calculations for any degrees level for any location.
      Parameters:
      degrees - the number of degrees below the horizon after sunset.
      sunset - if true the calculation should be degrees after sunset, or if false, degrees before sunrise.
      Returns:
      the double percentage of a sha'ah zmanis for a given set of degrees below the astronomical horizon for the current calendar. If the calculation can't be computed a Double.MIN_VALUE will be returned. See detailed explanation on top of the page.

    • getHalfDayBasedZman

      public Date getHalfDayBasedZman(Date startOfHalfDay, Date endOfHalfDay, double hours)
      A utility method to calculate zmanim based on Rav Moshe Feinstein and others as calculated in MTJ, Yeshiva of Staten Island, and Camp Yeshiva of Staten Island and other calendars. The day is split in two, from alos / sunrise to chatzos, and the second half of the day, from chatzos to sunset / tzais. Morning based times are calculated. based on the first 6 hours of the day, and afternoon times based on the second half of the day. As an example, passing 0.5, a start of chatzos and an end of day as sunset will return the time of mincha gedola GRA as half an hour zmanis based on the second half of the day. Some zmanim calculations can be based on subtracting sha'os zmaniyos from the end of the day, and that is supported by passing a negative hour to this method.
      Parameters:
      startOfHalfDay - The start of the half day. This would be alos or sunrise for morning based times such as sof zman krias shema and chatzos for afternoon based times such as mincha gedola.
      endOfHalfDay - The end of the half day. This would be chatzos for morning based times such as sof zman krias shema and sunset or tzais for afternoon based times such as mincha gedola.
      hours - The number of sha'os zmaniyos (hours) to offset the beginning of the first or second half of the day. For example, 3 for sof zman Shma, 0.5 for mincha gedola (half an hour after chatzos) and 4.75 for plag hamincha. If the number of hours is negative, it will subtract the number of sha'os zmaniyos from the end of the day.
      Returns:
      the Date of zman based on calculation of the first or second half of the day. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the AstronomicalCalendar documentation.
      See Also:

    • getHalfDayBasedShaahZmanis

      public long getHalfDayBasedShaahZmanis(Date startOfHalfDay, Date endOfHalfDay)
      A utility method to calculate the length of a sha'ah zmanis based on 1/6 of a 6 hour day.
      Parameters:
      startOfHalfDay - The start of the half-day. This would be alos or sunrise for the first half of the day, or chatzos for the second half of the day.
      endOfHalfDay - The end of the half-day. This would be chatzos for the first half of the day, or sunset or tzais for the second half of the day.
      Returns:
      The long millisecond length of a shaah zmanis based on 1/6 of a half-day. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, Long.MIN_VALUE will be returned. See detailed explanation on top of the AstronomicalCalendar documentation.
      See Also:
      TODO:
      Consider adjusting various shaah zmanis times to use this.