Class SunTimesCalculator

java.lang.Object
com.kosherjava.zmanim.util.AstronomicalCalculator
com.kosherjava.zmanim.util.SunTimesCalculator
All Implemented Interfaces:
Cloneable
public class SunTimesCalculator extends AstronomicalCalculator
Implementation of sunrise and sunset methods to calculate astronomical times. This calculator uses the Java algorithm written by Kevin Boone that is based on the US Naval Observatory'sAstronomical Almanac and used with his permission. Added to Kevin's code is adjustment of the zenith to account for elevation. This algorithm returns the same time every year and does not account for leap years. It is not as accurate as the Jean Meeus based NOAACalculator that is the default calculator use by the KosherJava zmanim library. It also does not have an implementation of some solar calculation methods.
Author:
© Eliyahu Hershfeld 2004 - 2026, © Kevin Boone 2000

  • Field Details

    • DEG_PER_HOUR

      private static final double DEG_PER_HOUR
      The number of degrees of longitude that corresponds to one hour of time difference.
      See Also:

  • Constructor Details

    • SunTimesCalculator

      public SunTimesCalculator()
      Default constructor of the SunTimesCalculator.

  • Method Details

    • getCalculatorName

      public String getCalculatorName()
      Description copied from class: AstronomicalCalculator
      Returns the name of the algorithm.
      Specified by:
      getCalculatorName in class AstronomicalCalculator
      Returns:
      the descriptive name of the algorithm.

    • getUTCSunrise

      public double getUTCSunrise(LocalDate localDate, GeoLocation geoLocation, double zenith, boolean adjustForElevation)
      Description copied from class: AstronomicalCalculator
      A method that calculates UTC sunrise as well as any time based on an angle above or below sunrise. This abstract method is implemented by the classes that extend this class.
      Specified by:
      getUTCSunrise in class AstronomicalCalculator
      Parameters:
      localDate - The LocalDate representing the date to calculate sunrise for.
      geoLocation - The location information used for astronomical calculation of solar times.
      zenith - the azimuth below the vertical zenith of 90 degrees. for sunrise typically the zenith used for the calculation uses geometric zenith of 90° and adjusts this slightly to account for solar refraction and the sun's radius. Another example would be AstronomicalCalendar.getBeginNauticalTwilight() that passes AstronomicalCalendar.NAUTICAL_ZENITH to this method.
      adjustForElevation - Should the time be adjusted for elevation
      Returns:
      The UTC time of sunrise in 24-hour format. 5:45:00 AM will return 5.75. If an error was encountered in the calculation (expected behavior for some locations such as near the poles, Double.NaN will be returned.
      See Also:

    • getUTCSunset

      public double getUTCSunset(LocalDate localDate, GeoLocation geoLocation, double zenith, boolean adjustForElevation)
      Description copied from class: AstronomicalCalculator
      A method that calculates UTC sunset as well as any time based on an angle above or below sunset. This abstract method is implemented by the classes that extend this class.
      Specified by:
      getUTCSunset in class AstronomicalCalculator
      Parameters:
      localDate - The LocalDate representing the date to calculate sunset for.
      geoLocation - The location information used for astronomical calculation of solar times.
      zenith - the azimuth below the vertical zenith of 90°. For sunset typically the zenith used for the calculation uses geometric zenith of 90° and adjusts this slightly to account for solar refraction and the sun's radius. Another example would be AstronomicalCalendar.getEndNauticalTwilight() that passes AstronomicalCalendar.NAUTICAL_ZENITH to this method.
      adjustForElevation - Should the time be adjusted for elevation
      Returns:
      The UTC time of sunset in 24-hour format. 5:45:00 AM will return 5.75. If an error was encountered in the calculation (expected behavior for some locations such as near the poles, Double.NaN will be returned.
      See Also:

    • sinDeg

      private static double sinDeg(double deg)
      The sine in degrees.
      Parameters:
      deg - the degrees
      Returns:
      sin of the angle in degrees

    • acosDeg

      private static double acosDeg(double x)
      Return the arc cosine in degrees.
      Parameters:
      x - angle
      Returns:
      acos of the angle in degrees

    • asinDeg

      private static double asinDeg(double x)
      Return the arc sine in degrees.
      Parameters:
      x - angle
      Returns:
      asin of the angle in degrees

    • tanDeg

      private static double tanDeg(double deg)
      Return the tangent in degrees.
      Parameters:
      deg - degrees
      Returns:
      tan of the angle in degrees

    • cosDeg

      private static double cosDeg(double deg)
      Calculate cosine of the angle in degrees
      Parameters:
      deg - degrees
      Returns:
      cosine of the angle in degrees

    • getHoursFromMeridian

      private static double getHoursFromMeridian(double longitude)
      Get time difference between location's longitude and the Meridian, in hours.
      Parameters:
      longitude - the longitude
      Returns:
      time difference between the location's longitude and the Meridian, in hours. West of Meridian has a negative time difference

    • getApproxTimeDays

      private static double getApproxTimeDays(int dayOfYear, double hoursFromMeridian, boolean isSunrise)
      Calculate the approximate time of sunset or sunrise in days since midnight Jan 1st, assuming 6am and 6pm events. We need this figure to derive the Sun's mean anomaly.
      Parameters:
      dayOfYear - the day of year
      hoursFromMeridian - hours from the meridian
      isSunrise - true for sunrise and false for sunset
      Returns:
      the approximate time of sunset or sunrise in days since midnight Jan 1st, assuming 6am and 6pm events. We need this figure to derive the Sun's mean anomaly.

    • getMeanAnomaly

      private static double getMeanAnomaly(int dayOfYear, double longitude, boolean isSunrise)
      Calculate the Sun's mean anomaly in degrees, at sunrise or sunset, given the longitude in degrees
      Parameters:
      dayOfYear - the day of the year
      longitude - longitude
      isSunrise - true for sunrise and false for sunset
      Returns:
      the Sun's mean anomaly in degrees

    • getSunTrueLongitude

      private static double getSunTrueLongitude(double sunMeanAnomaly)
      Returns the Sun's true longitude in degrees.
      Parameters:
      sunMeanAnomaly - the Sun's mean anomaly in degrees
      Returns:
      the Sun's true longitude in degrees. The result is an angle >= 0 and <= 360.

    • getSunRightAscensionHours

      private static double getSunRightAscensionHours(double sunTrueLongitude)
      Calculates the Sun's right ascension in hours.
      Parameters:
      sunTrueLongitude - the Sun's true longitude in degrees > 0 and < 360.
      Returns:
      the Sun's right ascension in hours in angles > 0 and < 360.

    • getCosLocalHourAngle

      private static double getCosLocalHourAngle(double sunTrueLongitude, double latitude, double zenith)
      Calculate the cosine of the Sun's local hour angle
      Parameters:
      sunTrueLongitude - the sun's true longitude
      latitude - the latitude
      zenith - the zenith
      Returns:
      the cosine of the Sun's local hour angle

    • getLocalMeanTime

      private static double getLocalMeanTime(double localHour, double sunRightAscensionHours, double approxTimeDays)
      Calculate local mean time of rising or setting. By 'local' is meant the exact time at the location, assuming that there were no time zone. That is, the time difference between the location and the Meridian depended entirely on the longitude. We can't do anything with this time directly; we must convert it to UTC and then to a local time.
      Parameters:
      localHour - the local hour
      sunRightAscensionHours - the sun's right ascension in hours
      approxTimeDays - approximate time days
      Returns:
      the fractional number of hours since midnight as a double

    • getTimeUTC

      private static double getTimeUTC(LocalDate localDate, GeoLocation geoLocation, double zenith, boolean isSunrise)
      Get sunrise or sunset time in UTC, according to flag. This time is returned as a double and is not adjusted for time-zone.
      Parameters:
      localDate - the LocalDate object to extract the day of year for calculation
      geoLocation - The location information used for astronomical calculation of solar times.
      zenith - Sun's zenith in degrees
      isSunrise - True for sunrise and false for sunset.
      Returns:
      the time as a double. If an error was encountered in the calculation (expected behavior for some locations such as near the poles, Double.NaN will be returned.

    • getUTCNoon

      public double getUTCNoon(LocalDate localDate, GeoLocation geoLocation)
      Description copied from class: AstronomicalCalculator
      Return the Universal Coordinated Time (UTC) of solar noon (UTC) for the given day at the given location. The NOAACalculator, the default calculator implementation calculates true solar noon, something that can be calculated even in the Arctic / Antarctic where there may be no sunrise or sunset, while the SunTimesCalculator approximates it, calculating the time as halfway between sunrise and sunset, something that can't be calculated in Polar regions where there is no sunrise or sunset for part of the year. See The Definition of Chatzos for details on solar noon / midnight calculations.
      Specified by:
      getUTCNoon in class AstronomicalCalculator
      Parameters:
      localDate - The LocalDate representing the date to calculate noon for.
      geoLocation - The location information used for astronomical calculation of solar times.
      Returns:
      The UTC time of solar noon in 24-hour format. 1:45:00 PM will return 13.75. If an error was encountered in the the calculation (expected behavior for some locations such as near the poles, Double.NaN will be returned.
      See Also:

    • getUTCMidnight

      public double getUTCMidnight(LocalDate localDate, GeoLocation geoLocation)
      Description copied from class: AstronomicalCalculator
      Return the Universal Coordinated Time (UTC) of solar midnight (UTC) for the given day at the given location. The NOAACalculator, the default calculator implementation calculates true solar midnight, something that can be calculated even in the Arctic / Antarctic where there may be no sunrise or sunset, while the SunTimesCalculator approximates it, calculating the time as 12 hours after halfway between sunrise and sunset, something that can't be calculated in Polar regions where there is no sunrise or sunset for part of the year. See The Definition of Chatzos for details on solar noon / midnight calculations.
      Specified by:
      getUTCMidnight in class AstronomicalCalculator
      Parameters:
      localDate - The LocalDate representing the date to calculate midnight for. The calculation will be for midnight at the end of the day passed in.
      geoLocation - The location information used for astronomical calculation of solar times.
      Returns:
      The UTC time of solar midnight in in a 24-hour double format. 1:45:00 AM will return 1.75. If an error was encountered in the calculation (expected behavior for the SunTimesCalculator at times of the year in Polar regions), Double.NaN will be returned.
      See Also:

    • getSolarAzimuth

      public double getSolarAzimuth(ZonedDateTime zdt, GeoLocation geoLocation)
      This calculator class does not implement the getSolarAzimuth method, and throws a UnsupportedOperationException. Use the NOAACalculatorif this method is required.
      Return the Solar Azimuth for the horizontal coordinate system at the given location at the given time. Not corrected for altitude. True south is 180 degrees.
      Specified by:
      getSolarAzimuth in class AstronomicalCalculator
      Parameters:
      zdt - The ZonedDateTime to calculate the azimuth for.ac
      geoLocation - The location information used for astronomical calculation of solar times.
      Returns:
      the solar azimuth in degrees. Astronomical midday would be 180 in the norther hemosphere and 0 in the southern hemosphere. Depending on the location and time of year, sunrise will have an azimuth of about 90° and sunset about 270°.
      Throws:
      UnsupportedOperationException - This calculator class does not implement the getSolarAzimuth method. Use the NOAACalculator instead.

    • getSolarElevation

      public double getSolarElevation(ZonedDateTime zdt, GeoLocation geoLocation)
      This calculator class does not implement the getSolarElevation method, and throws a UnsupportedOperationException. Use the NOAACalculatorif this method is required.
      Return the Solar Elevation for the horizontal coordinate system at the given location at the given time. Can be negative if the sun is below the horizon. Not corrected for altitude.
      Specified by:
      getSolarElevation in class AstronomicalCalculator
      Parameters:
      zdt - The ZonedDateTime to calculate the elevation for.
      geoLocation - The location information used for astronomical calculation of solar times.
      Returns:
      solar elevation in degrees. The horizon (calculated in a vacuum using the solar radius as the point) is 090°, civil twilight is -690° etc. This means that sunrise and sunset that do use refraction and are calculated from the upper limb of the sun will return about 0.83390°.
      Throws:
      UnsupportedOperationException - This calculator class does not implement the getSolarElevation method. Use the NOAACalculator instead.

    • getTimeAtAzimuth

      public double getTimeAtAzimuth(LocalDate localDate, GeoLocation geoLocation, double azimuth)
      This calculator class does not implement the getTimeAtAzimuth method, and throws a UnsupportedOperationException. Use the NOAACalculatorif this method is required.
      Returns the time that the azimuth will occur for the date and location passed to this method. As an example, to know when the sun will be directly west, pass in an azimuth of 270°, and for directly east, pass in an azimith of 90°.
      Specified by:
      getTimeAtAzimuth in class AstronomicalCalculator
      Parameters:
      localDate - The LocalDate representing the date to calculate the time of the azimuth for.
      geoLocation - The location information used for astronomical calculation of solar times.
      azimuth - the azimuth to run the calculation for
      Returns:
      The UTC time that the azimuth will be reached in a 24-hour double format. 5:45:00 PM will return 17.75. If an error was encountered in the calculation (expected behavior for some locations such as near the poles, a Double.NaN will be returned.
      Throws:
      UnsupportedOperationException - This calculator class does not implement the getTimeAtAzimuth method. Use the NOAACalculator instead.