Package net.time4j.calendar.astro

Interface SolarTime.Calculator

All Known Implementing Classes:
StdSolarCalculator
Enclosing class:
SolarTime
public static interface SolarTime.Calculator

An SPI-interface representing a facade for the calculation engine regarding sunrise or sunset.

Note: All implementations must have a public no-arg constructor.

Since:
3.34/4.29
See Also:
ServiceLoader

  • Method Summary

    Modifier and Type
    Method
    Description
    double
    equationOfTime​(double jde)
    Calculates the difference between true and mean solar time.
    default double
    getFeature​(double jde, String nameOfFeature)
    Calculates a value suitable for given time and feature.
    default double
    getGeodeticAngle​(double latitude, int altitude)
    Calculates the additional geodetic angle due to the extra altitude of the observer.
    default double
    getZenithAngle​(double latitude, int altitude)
    Calculates the angle of the sun relative to the zenith at sunrise or sunset.
    String
    name()
    Obtains the name of the calculation method.
    Optional<Moment>
    sunrise​(CalendarDate date, double latitude, double longitude, double zenith)
    Calculates the moment of sunrise.
    Optional<Moment>
    sunset​(CalendarDate date, double latitude, double longitude, double zenith)
    Calculates the moment of sunset.

  • Method Details

    • name

      String name()

      Obtains the name of the calculation method.

      Returns:
      String

    • sunrise

      Optional<Moment> sunrise​(CalendarDate date, double latitude, double longitude, double zenith)

      Calculates the moment of sunrise.

      The zenith angle can be represented by the result of the method getZenithAngle(latitude, altitude).

      Parameters:
      date - the local calendar date
      latitude - geographical latitude in degrees, positive for North, negative for South
      longitude - geographical longitude in degrees, positive for East, negative for West
      zenith - the distance of the center of the sun from geographical local zenith in degrees
      Returns:
      moment of sunrise if it exists for given parameters else not present (polar day or night)
      Throws:
      IllegalArgumentException - if any parameter is out of range

    • sunset

      Optional<Moment> sunset​(CalendarDate date, double latitude, double longitude, double zenith)

      Calculates the moment of sunset.

      The zenith angle can be represented by the result of the method getZenithAngle(latitude, altitude).

      Parameters:
      date - the local calendar date
      latitude - geographical latitude in degrees, positive for North, negative for South
      longitude - geographical longitude in degrees, positive for East, negative for West
      zenith - the distance of the center of the sun from geographical local zenith in degrees
      Returns:
      moment of sunset if it exists for given parameters else not present (polar day or night)
      Throws:
      IllegalArgumentException - if any parameter is out of range

    • equationOfTime

      double equationOfTime​(double jde)

      Calculates the difference between true and mean solar time.

      Parameters:
      jde - julian day in ephemeris time
      Returns:
      value in seconds

    • getFeature

      default double getFeature​(double jde, String nameOfFeature)

      Calculates a value suitable for given time and feature.

      Subclasses overriding this method document which features are supported. At least the feature of "declination" should be supported.

      Parameters:
      jde - julian day in ephemeris time
      nameOfFeature - describes what kind of value shall be calculated
      Returns:
      result value or Double.NaN if the feature is not supported

    • getGeodeticAngle

      default double getGeodeticAngle​(double latitude, int altitude)

      Calculates the additional geodetic angle due to the extra altitude of the observer.

      The default implementation just returns 0.0. Negative altitudes modelling a valley between hight mountains are not supported but might be approximated by an angle calculation using the altitude difference between valley and mountain and also using the distance between valley and mountain resulting in a negative angle.

      Parameters:
      latitude - the geographical latitude in degrees
      altitude - the altitude of the observer in meters, not negative
      Returns:
      geodetic angle correction in degrees
      Since:
      3.36/4.31

    • getZenithAngle

      default double getZenithAngle​(double latitude, int altitude)

      Calculates the angle of the sun relative to the zenith at sunrise or sunset.

      The default implementation just uses the standard refraction angle of 34 arc minutes, adds to it 90° and the geodetic angle correction. In case users do not want to take into account the geodetic angle correction, they might simply subtract latter one. Example for the situation of Denver in USA which is suited in a valley with far mountain ranges: 

        double zenith = 
      calculator.getZenithAngle(latitude, altitude) 
      - calculator.getGeodeticAngle(latitude, altitude);
      Parameters:
      latitude - the geographical latitude in degrees
      altitude - the altitude of the observer in meters, not negative
      Returns:
      effective zenith angle in degrees
      Since:
      3.36/4.31