Class AstronomicalCalendar

java.lang.Object
com.kosherjava.zmanim.AstronomicalCalendar
All Implemented Interfaces:
Cloneable
Direct Known Subclasses:
ZmanimCalendar
public class AstronomicalCalendar extends Object implements Cloneable
A Java calendar that calculates astronomical times such as sunrise, sunset and twilight times. This class contains a LocalDate and can therefore use the standard Calendar functionality to change dates etc. The calculation engine used to calculate the astronomical times can be changed to a different implementation by implementing the abstract AstronomicalCalculator and setting it with the setAstronomicalCalculator(AstronomicalCalculator). A number of different calculation engine implementations are included in the util package. Note: There are times when the algorithms can't calculate proper values for sunrise, sunset and twilight. This is usually caused by trying to calculate times for areas either very far North or South, where sunrise / sunset never happen on that date. This is common when calculating twilight with a deep dip below the horizon for locations as far south of the North Pole as London, in the northern hemisphere. The sun never reaches this dip at certain times of the year. When the calculations encounter this condition a null will be returned when a Instant is expected and Long.MIN_VALUE when a long is expected. The reason that Exceptions are not thrown in these cases is because the lack of a rise/set or twilight is not an exception, but an expected condition in many parts of the world.

Here is a simple example of how to use the API to calculate sunrise. First create the Calendar for the location you would like to calculate sunrise or sunset times for: 

String locationName = "Lakewood, NJ";
double latitude = 40.0828; // Lakewood, NJ
double longitude = -74.2094; // Lakewood, NJ
double elevation = 20; // optional elevation correction in Meters
// the String parameter in getZoneId() has to be a valid ZoneId listed in ZoneId.getAvailableZoneIds()
ZoneId zoneId = ZoneId.of("America/New_York");
GeoLocation location = new GeoLocation(locationName, latitude, longitude, elevation, zoneId);
AstronomicalCalendar ac = new AstronomicalCalendar(location);
To get the time of sunrise, first set the date you want (if not set, the date will default to today): 
LocalDate localDate = LocalDate.of(1969, Month.FEBRUARY, 8);
ac.setLocalDate(localDate);
Instant sunrise = ac.getSunrise();
Author:
© Eliyahu Hershfeld 2004 - 2026

  • Field Details

  • Constructor Details

  • Method Details

    • getSunriseWithElevation

      public Instant getSunriseWithElevation()
      The getSunriseWithElevation method returns a Instant representing the elevation adjusted sunrise time. The zenith used for the calculation uses geometric zenith of 90° plus AstronomicalCalculator.getElevationAdjustment(double). 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.
      Returns:
      the Instant representing the exact sunrise 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 page.
      See Also:

    • getSunrise

      @Deprecated(forRemoval=false) public Instant getSunrise()
      Deprecated.
      Use getSunriseWithElevation() instead. This method already accounts for the observer's elevation, but the name does not clearly indicate this behavior. The replacement method has a clearer and more descriptive name.
      Returns:
      the Instant representing the exact sunrise 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 page.
      See Also:

    • getSeaLevelSunrise

      public Instant getSeaLevelSunrise()
      A method that returns the sunrise without elevation adjustment. 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.
      Returns:
      the Instant representing the exact sea-level sunrise 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 page.
      See Also:

    • getBeginCivilTwilight

      public Instant getBeginCivilTwilight()
      A method that returns the beginning of civil twilight (dawn) using a zenith of 96°.
      Returns:
      The Instant of the beginning of civil twilight using a zenith of 96°. If the calculation can't be computed, null will be returned. See detailed explanation on top of the page.
      See Also:

    • getBeginNauticalTwilight

      public Instant getBeginNauticalTwilight()
      A method that returns the beginning of nautical twilight using a zenith of 102°.
      Returns:
      The Instant of the beginning of nautical twilight using a zenith of 102°. If the calculation can't be computed null will be returned. See detailed explanation on top of the page.
      See Also:

    • getBeginAstronomicalTwilight

      public Instant getBeginAstronomicalTwilight()
      A method that returns the beginning of astronomical twilight using a zenith of 108°.
      Returns:
      The Instant of the beginning of astronomical twilight using a zenith of 108°. If the calculation can't be computed, null will be returned. See detailed explanation on top of the page.
      See Also:

    • getSunsetWithElevation

      public Instant getSunsetWithElevation()
      The getSunsetWithElevation method returns an Instant representing the elevation adjusted sunset time. The zenith used for the calculation uses geometric zenith of 90° plus AstronomicalCalculator.getElevationAdjustment(double). 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.
      Returns:
      the Instant representing the exact sunset 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 page.
      See Also:

    • getSunset

      @Deprecated(forRemoval=false) public Instant getSunset()
      Deprecated.
      Use getSunsetWithElevation() instead. This method already accounts for the observer's elevation, but its name does not clearly reflect that behavior. The replacement method provides a more accurate and descriptive name.
      Returns:
      the Instant representing the exact sunset 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 page.
      See Also:

    • getSeaLevelSunset

      public Instant getSeaLevelSunset()
      A method that returns the sunset without elevation adjustment. 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.
      Returns:
      the Instant representing the exact sea-level sunset 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 page.
      See Also:

    • getEndCivilTwilight

      public Instant getEndCivilTwilight()
      A method that returns the end of civil twilight using a zenith of 96°.
      Returns:
      The Instant of the end of civil twilight using a zenith of 96°. If the calculation can't be computed, null will be returned. See detailed explanation on top of the page.
      See Also:

    • getEndNauticalTwilight

      public Instant getEndNauticalTwilight()
      A method that returns the end of nautical twilight using a zenith of 102°.
      Returns:
      The Instant of the end of nautical twilight using a zenith of 102°. If the calculation can't be computed, null will be returned. See detailed explanation on top of the page.
      See Also:

    • getEndAstronomicalTwilight

      public Instant getEndAstronomicalTwilight()
      A method that returns the end of astronomical twilight using a zenith of 108°.
      Returns:
      the Instant of the end of astronomical twilight using a zenith of 108°. If the calculation can't be computed, null will be returned. See detailed explanation on top of the page.
      See Also:

    • getTimeOffset

      public static Instant getTimeOffset(Instant time, double offset)
      A utility method that returns a date offset by the offset time passed in as a parameter. This method casts the offset as a long and calls getTimeOffset(Instant, long).
      Parameters:
      time - the start time
      offset - the offset in milliseconds to add to the time
      Returns:
      the Instant with the offset added to it

    • getTimeOffset

      public static Instant getTimeOffset(Instant time, long offsetMillis)
      A utility method that returns an Instant offset by the offset time passed in. Please note that the level of light during twilight is not affected by elevation, so if this is being used to calculate an offset before sunrise or after sunset with the intent of getting a rough "level of light" calculation, the sunrise or sunset time passed to this method should be sea level sunrise and sunset.
      Parameters:
      time - the start time
      offsetMillis - the offset in milliseconds to add to the time.
      Returns:
      the Instant with the offset in milliseconds added to it

    • getSunriseOffsetByDegrees

      public Instant getSunriseOffsetByDegrees(double offsetZenith)
      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 + GEOMETRIC_ZENITH = 104 would have to be passed as a parameter.
      Parameters:
      offsetZenith - the degrees before getSunriseWithElevation() to use in the calculation. For time after sunrise use negative numbers. 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.
      Returns:
      The Instant of the offset after (or before) getSunriseWithElevation(). 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 page.

    • getSunsetOffsetByDegrees

      public Instant getSunsetOffsetByDegrees(double offsetZenith)
      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 + GEOMETRIC_ZENITH = 104 would have to be passed as a parameter.
      Parameters:
      offsetZenith - the degrees after getSunsetWithElevation() to use in the calculation. For time before sunset use negative numbers. 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.
      Returns:
      The Instant of the offset after (or before) getSunsetWithElevation(). 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 page.

    • getUTCSunrise

      public double getUTCSunrise(double zenith)
      A method that returns the sunrise in UTC time without correction for time zone offset from GMT and without using daylight savings time.
      Parameters:
      zenith - the degrees below the horizon. For time after sunrise use negative numbers.
      Returns:
      The time in the format: 18.75 for 18:45:00 UTC/GMT. 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, Double.NaN will be returned. See detailed explanation on top of the page.

    • getUTCSeaLevelSunrise

      public double getUTCSeaLevelSunrise(double zenith)
      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.
      Parameters:
      zenith - the degrees below the horizon. For time after sunrise use negative numbers.
      Returns:
      The time in the format: 18.75 for 18:45:00 UTC/GMT. 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, Double.NaN will be returned. See detailed explanation on top of the page.
      See Also:

    • getUTCSunset

      public double getUTCSunset(double zenith)
      A method that returns the sunset in UTC time without correction for time zone offset from GMT and without using daylight savings time.
      Parameters:
      zenith - the degrees below the horizon. For time after sunset use negative numbers.
      Returns:
      The time in the format: 18.75 for 18:45:00 UTC/GMT. 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, Double.NaN will be returned. See detailed explanation on top of the page.
      See Also:

    • getUTCSeaLevelSunset

      public double getUTCSeaLevelSunset(double zenith)
      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.
      Parameters:
      zenith - the degrees below the horizon. For time before sunset use negative numbers.
      Returns:
      The time in the format: 18.75 for 18:45:00 UTC/GMT. 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, Double.NaN will be returned. See detailed explanation on top of the page.
      See Also:

    • getTemporalHour

      public long getTemporalHour()
      A method that returns a sea-level based temporal (solar) hour. The day from sea-level sunrise to sea-level sunset is split into 12 equal parts with each one being a temporal hour.
      Returns:
      the long millisecond length of a temporal hour. If the calculation can't be computed, Long.MIN_VALUE will be returned. See detailed explanation on top of the page.
      See Also:

    • getTemporalHour

      public long getTemporalHour(Instant startOfDay, Instant endOfDay)
      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 elevation adjusted temporal hour by passing in sunrise and sunset as parameters.
      Parameters:
      startOfDay - The start of the day.
      endOfDay - The end of the day.
      Returns:
      the long millisecond length of the temporal hour. If the calculation can't be computed a Long.MIN_VALUE will be returned. See detailed explanation on top of the page.
      See Also:

    • getSunTransit

      public Instant getSunTransit()
      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 set to use the NOAACalculator (the default) it will calculate astronomical noon. If the calendar instance is to use the 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.
      Returns:
      the Instant representing Sun's transit. If the calculation can't be computed such as when using the USNO calculator that does not support getting solar noon for 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 page.
      See Also:

    • getSolarMidnight

      public Instant getSolarMidnight()
      A method that returns solar midnight at the end of the current day (that may actually be after midnight of the day it is being calculated for). It occurs when the Sun is transiting the lower celestial meridian, or when the sun is at it's nadir. The calculations used by this class depend on the AstronomicalCalculator used. If this calendar instance is set to use the NOAACalculator (the default) it will calculate astronomical midnight. If the calendar instance is to use the USNO Calculator, that does not have code to calculate astronomical noon, midnight is calculated as 12 hours after halfway between sea level sunrise and sea level sunset of that day. This 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.
      Returns:
      the Instant representing Sun's lower transit at the end of the current day. If the calculation can't be computed such as when using the USNO calculator that does not support getting solar noon or midnight for 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. This is not relevant when using the NOAA Calculator that is never expected to return null. See the detailed explanation on top of the page.
      See Also:

    • getSunTransit

      public Instant getSunTransit(Instant startOfDay, Instant endOfDay)
      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).
      Parameters:
      startOfDay - the start of day for calculating the sun's transit. This can be sea level sunrise, visual sunrise (or any arbitrary start of day) passed to this method.
      endOfDay - the end of day for calculating the sun's transit. This can be sea level sunset, visual sunset (or any arbitrary end of day) passed to this method.
      Returns:
      the Instant representing Sun's transit. 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, null will be returned. See detailed explanation on top of the page.

    • getInstantFromTime

      protected Instant getInstantFromTime(double time, AstronomicalCalendar.SolarEvent solarEvent)
      A method that returns an Instant from the time passed in as a parameter.
      Parameters:
      time - The time to be set as the time for the Instant. The time expected is in the format: 18.75 for 6:45:00 PM.time is sunrise and false if it is sunset
      solarEvent - the type of AstronomicalCalendar.SolarEvent
      Returns:
      The Instant object representation of the time double

    • getSunriseSolarDipFromOffset

      @Deprecated(forRemoval=false) public double getSunriseSolarDipFromOffset(double minutes)
      Deprecated.
      This method is slow and inefficient and should NEVER be used in a loop. This method should be replaced by calls to AstronomicalCalculator.getSolarElevation(Calendar, GeoLocation). That method will efficiently return the the solar elevation (the sun's position in degrees below (or above) the horizon) at the given time even in the arctic when there is no sunrise.
      Returns the sun's elevation (number of degrees) 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°.
      Parameters:
      minutes - minutes before sunrise
      Returns:
      the degrees below the horizon before sunrise that match the offset in minutes passed it as a parameter. If the calculation can't be computed (no sunrise occurs on this day) a Double.NaN will be returned.
      See Also:

    • getSunsetSolarDipFromOffset

      @Deprecated(forRemoval=false) public double getSunsetSolarDipFromOffset(double minutes)
      Deprecated.
      This method is slow and inefficient and should NEVER be used in a loop. This method should be replaced by calls to AstronomicalCalculator.getSolarElevation(ZonedDateTime, GeoLocation). That method will efficiently return the the solar elevation (the sun's position in degrees below (or above) the horizon) at the given time even in the arctic when there is no sunrise.
      Returns the sun's elevation (number of degrees) below the horizon after sunset that matches the offset minutes 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°.
      Parameters:
      minutes - minutes after sunset
      Returns:
      the degrees below the horizon after sunset that match the offset in minutes passed it as a parameter. If the calculation can't be computed (no sunset occurs on this day) a Double.NaN will be returned.
      See Also:

    • getLocalMeanTime

      public Instant getLocalMeanTime(LocalTime localTime)
      A method that returns local mean time (LMT) time converted to regular clock time for the local wall-clock time passed to this method. This time is adjusted from standard time to account for the local latitude. The 360° of the globe divided by 24 calculates to 15° per hour with 4 minutes per degree, so at a longitude of 0 , 15, 30 etc... noon is at exactly 12:00pm. Lakewood, N.J., with a longitude of -74.222, is 0.7906 away from the closest multiple of 15 at -75°. This is multiplied by 4 clock minutes (per degree) to yield 3 minutes and 7 seconds for a noon time of 11:56:53am. This method is not tied to the theoretical 15° time zones, but will adjust to the actual time zone and Daylight saving time to return LMT.
      Parameters:
      localTime - the local wall-clock time (such as 12:00 for noon and 00:00 for midnight) to calculate as LMT.
      Returns:
      the Instant representing the local mean time (LMT) for the time passed in. In Lakewood, NJ, passing noon will return 11:56:50am.
      See Also:

    • getAdjustedLocalDate

      private LocalDate getAdjustedLocalDate()
      Adjusts the LocalDate to deal with edge cases where the location crosses the antimeridian.
      Returns:
      the adjusted Calendar
      See Also:

    • getMidnightLastNight

      protected ZonedDateTime getMidnightLastNight()
      Used by Molad based zmanim to determine if zmanim occur during the current day. This is also used as the anchor for current timezone-offset calculations.
      Returns:
      midnight at the start of the current local date in the configured timezone

    • getMidnightTonight

      protected ZonedDateTime getMidnightTonight()
      Used by Molad based zmanim to determine if zmanim occur during the current day.
      Returns:
      following midnight

    • toString

      public String toString()
      Returns an XML formatted representation of the class using the default output of the toXML method.
      Overrides:
      toString in class Object
      Returns:
      an XML formatted representation of the class. It returns the default output of the toXML method.
      See Also:

    • toJSON

      public String toJSON()
      Returns a JSON formatted representation of the class using the default output of the toJSON method.
      Returns:
      a JSON formatted representation of the class. It returns the default output of the toJSON method.
      See Also:

    • equals

      public boolean equals(Object object)
      Overrides:
      equals in class Object
      See Also:

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object
      See Also:

    • getGeoLocation

      public GeoLocation getGeoLocation()
      A method that returns the currently set GeoLocation which contains location information used for the astronomical calculations.
      Returns:
      Returns the geoLocation.

    • setGeoLocation

      public void setGeoLocation(GeoLocation geoLocation)
      Sets the GeoLocation Object to be used for astronomical calculations.
      Parameters:
      geoLocation - The geoLocation to set.
      TODO:
      Possibly adjust for horizon elevation. It may be smart to just have the calculator check the GeoLocation though it doesn't really belong there.

    • getAstronomicalCalculator

      public AstronomicalCalculator getAstronomicalCalculator()
      A method that returns the currently set AstronomicalCalculator.
      Returns:
      Returns the astronomicalCalculator.
      See Also:

    • setAstronomicalCalculator

      public void setAstronomicalCalculator(AstronomicalCalculator astronomicalCalculator)
      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 NOAACalculator based on NOAA's implementation of Jean Meeus's algorithms as well as SunTimesCalculator based on the US Naval Observatory's algorithm. This allows easy runtime switching and comparison of different algorithms.
      Parameters:
      astronomicalCalculator - The astronomicalCalculator to set.

    • getLocalDate

      public LocalDate getLocalDate()
      returns the LocalDate object encapsulated in this class.
      Returns:
      Returns the LocalDate.

    • setLocalDate

      public void setLocalDate(LocalDate localDate)
      Sets the LocalDate object for us in this class.
      Parameters:
      localDate - The LocalDate to set.

    • clone

      public Object clone()
      A method that creates a deep copy of the object. Note: If the TimeZone in the cloned GeoLocation will be changed from the original, it is critical that getLocalDate().
      Overrides:
      clone in class Object
      See Also: