SolarTime (Time4J-Base 5.8 API)

java.lang.Object
- net.time4j.calendar.astro.SolarTime

All Implemented Interfaces:: Serializable, GeoLocation

public final class SolarTime
extends Object
implements GeoLocation, Serializable

Contains various routines to determine solar time.

Notice: Most chronological functions use the astronomical equation of time. Hence they are only applicable for years between -2000 and +3000 otherwise an IllegalArgumentException will be thrown.

Example for sunrise and sunset on the top of Africas highest mountain Kilimanjaro:

     PlainDate date = PlainDate.of(2017, 12, 22);
     TZID tzid = () -> "Africa/Dar_es_Salaam"; // Tanzania: UTC+03:00

     // high altitude implies earlier sunrise and later sunset
     SolarTime kibo5895 =
       SolarTime.ofLocation()
          .southernLatitude(3, 4, 0)
          .easternLongitude(37, 21, 33)
          .atAltitude(5895)
          .usingCalculator(StdSolarCalculator.TIME4J) // this calculator takes into account the altitude
          .build();

     assertThat(
       date.get(kibo5895.sunrise()).get().toZonalTimestamp(tzid).toTime(),
       is(PlainTime.of(6, 10, 35)));
     assertThat(
       date.get(kibo5895.sunset()).get().toZonalTimestamp(tzid).toTime(),
       is(PlainTime.of(18, 47, 47)));

About limitations of accuracy:

Time4J only models a spherical geometry but not local topology with mountains which can break the horizon line. Furthermore, special weather conditions which can have a bigger impact on atmospheric refraction are not calculatable. The concrete calculator in use is also a limiting factor for accuracy. Users should therefore not expect more than minute precision. This can be even worse for polar regions because the sun crosses then the horizon under a very shallow angle.

Interpretation of calendar dates:

This class interpretes every calendar date input as on LMT (Local Mean Time) unless the builder-method SolarTime.Builder.inTimezone(TZID) is called. Users only need to pay attention to this subtile difference if a few areas along the international date border like Kiribati or Samoa are involved. Following example demonstrates the difference:

LMT-date

     TZID tzid = Timezone.of("Pacific/Apia").getID();
     SolarTime apia = SolarTime.ofLocation().southernLatitude(13, 50, 0).westernLongitude(171, 45, 0).build();
     assertThat(
       PlainDate.of(2011, 12, 31).get(apia.sunrise()).get().toZonalTimestamp(tzid),
       is(PlainTimestamp.of(2012, 1, 1, 7, 2, 13))); // civil date is one day later than LMT-date

Zoned date

     TZID tzid = Timezone.of("Pacific/Apia").getID();
     SolarTime apia =
       SolarTime.ofLocation()
         .southernLatitude(13, 50, 0)
         .westernLongitude(171, 45, 0)
         .inTimezone(tzid)
         .build();
     assertThat(
       PlainDate.of(2012, 1, 1).get(apia.sunrise()).get().toZonalTimestamp(tzid),
       is(PlainTimestamp.of(2012, 1, 1, 7, 2, 13))); // civil date is same as input

Since:: 3.33/4.28
Author:: Meno Hochschild
See Also:: Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`SolarTime.Builder` Helper class to construct a new instance of `SolarTime`.
`static interface`	`SolarTime.Calculator` An SPI-interface representing a facade for the calculation engine regarding sunrise or sunset.
`static class`	`SolarTime.Sunshine` Collects various data around sunrise and sunset.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static ChronoFunction<Moment,PlainTimestamp>`	`apparentAt(ZonalOffset offset)` Determines the apparent solar time of any moment at given local time zone offset.
`static ChronoFunction<Moment,PlainTimestamp>`	`apparentAt(ZonalOffset offset, String calculator)` Determines the apparent solar time of any moment at given local time zone offset.
`boolean`	`equals(Object obj)`
`static double`	`equationOfTime(Moment moment)` Determines the difference between apparent and mean solar time at given moment.
`static double`	`equationOfTime(Moment moment, String calculator)` Determines the difference between apparent and mean solar time at given moment.
`int`	`getAltitude()` Obtains the geographical altitude of this instance relative to sea level.
`SolarTime.Calculator`	`getCalculator()` Obtains the underlying calculator.
`double`	`getLatitude()` Obtains the geographical latitude of this instance.
`double`	`getLongitude()` Obtains the geographical longitude of this instance.
`Optional<TZID>`	`getObserverZoneID()` Obtains the optional observer timezone which might be associated with any calendar date input.
`int`	`hashCode()`
`ChronoCondition<CalendarDate>`	`midnightSun()` Determines if the sun is visible all day on a given calendar date.
`static SolarTime`	`ofJerusalem()` Obtains an instance of solar time for the temple area in Jerusalem which has a prominent meaning in Hebrew calendar and time.
`static SolarTime.Builder`	`ofLocation()` Obtains a builder for creating a new instance of local solar time.
`static SolarTime`	`ofLocation(double latitude, double longitude)` Obtains the solar time for given geographical location at sea level.
`static SolarTime`	`ofLocation(double latitude, double longitude, int altitude, SolarTime.Calculator calculator)` Obtains the solar time for given geographical location.
`static SolarTime`	`ofLocation(double latitude, double longitude, int altitude, String calculator)` Obtains the solar time for given geographical location.
`static SolarTime`	`ofMecca()` Obtains an instance of solar time for the Kaaba in Mecca which has a prominent meaning in islamic calendar.
`static ChronoFunction<Moment,PlainTimestamp>`	`onAverage(ZonalOffset offset)` Determines the mean solar time of any moment at given local time zone offset.
`ChronoCondition<CalendarDate>`	`polarNight()` Determines if the sun is invisible all day on a given calendar date.
`ChronoFunction<CalendarDate,Optional<Moment>>`	`sunrise()` Calculates the moment of sunrise at the location of this instance.
`ChronoFunction<CalendarDate,Optional<Moment>>`	`sunrise(Twilight twilight)` Calculates the time of given twilight at sunrise and the location of this instance.
`ChronoFunction<CalendarDate,Optional<Moment>>`	`sunset()` Calculates the moment of sunset at the location of this instance.
`ChronoFunction<CalendarDate,Optional<Moment>>`	`sunset(Twilight twilight)` Calculates the time of given twilight at sunset and the location of this instance.
`ChronoFunction<CalendarDate,SolarTime.Sunshine>`	`sunshine(TZID tzid)` Queries a given calendar date for its associated sunshine data.
`ChronoFunction<CalendarDate,Optional<Moment>>`	`timeOfShadowAfterNoon(double objectHeight, double shadowLength)` Calculates the moment after noon when the given shadow occurs on given date at the location of this instance.
`ChronoFunction<CalendarDate,Optional<Moment>>`	`timeOfShadowBeforeNoon(double objectHeight, double shadowLength)` Calculates the moment before noon when the given shadow occurs on given date at the location of this instance.
`String`	`toString()`
`ChronoFunction<CalendarDate,Moment>`	`transitAtMidnight()` Calculates the moment of midnight at the location of this instance (lowest position of sun).
`ChronoFunction<CalendarDate,Moment>`	`transitAtNoon()` Calculates the moment of noon at the location of this instance (solar transit).

Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface net.time4j.calendar.astro.GeoLocation
of, of

- Method Detail
  - ofLocation
```
public static SolarTime.Builder ofLocation()
```
    Obtains a builder for creating a new instance of local solar time.
    
    This method is the recommended approach if any given geographical position is described in degrees including arc minutes and arc seconds in order to avoid manual conversions to decimal degrees.
    
    Returns:
    
    builder for creating a new instance of local solar time
    
    Since:
    
    3.35/4.30
  - ofLocation
```
public static SolarTime ofLocation(double latitude,
                                   double longitude)
```
    Obtains the solar time for given geographical location at sea level.
    
    The default calculator is usually StdSolarCalculator.NOAA unless another calculator was set up via the service loader mechnism.
    
    This method handles the geographical location in decimal degrees only. If these data are given in degrees, arc minutes and arc seconds then users should apply the builder approach instead.
    
    Parameters:
    
    latitude - geographical latitude in decimal degrees (-90.0 <= x <= +90.0)
    
    longitude - geographical longitude in decimal degrees (-180.0 <= x < 180.0)
    
    Returns:
    
    instance of local solar time
    
    Throws:
    
    IllegalArgumentException - if the coordinates are out of range
    
    Since:
    
    3.34/4.29
    
    See Also:
    
    ofLocation(double, double, int, String)
  - ofLocation
```
public static SolarTime ofLocation(double latitude,
                                   double longitude,
                                   int altitude,
                                   String calculator)
```
    Obtains the solar time for given geographical location.
    
    This method handles the geographical location in decimal degrees only. If these data are given in degrees, arc minutes and arc seconds then users should apply the builder approach instead.
    
    Parameters:
    
    latitude - geographical latitude in decimal degrees (-90.0 <= x <= +90.0)
    
    longitude - geographical longitude in decimal degrees (-180.0 <= x < 180.0)
    
    altitude - geographical altitude relative to sea level in meters (0 <= x < 11,0000)
    
    calculator - name of solar time calculator
    
    Returns:
    
    instance of local solar time
    
    Throws:
    
    IllegalArgumentException - if the coordinates are out of range or the calculator is unknown
    
    Since:
    
    3.34/4.29
    
    See Also:
    
    SolarTime.Calculator.name()
  - ofLocation
```
public static SolarTime ofLocation(double latitude,
                                   double longitude,
                                   int altitude,
                                   SolarTime.Calculator calculator)
```
    Obtains the solar time for given geographical location.
    
    This method handles the geographical location in decimal degrees only. If these data are given in degrees, arc minutes and arc seconds then users should apply the builder approach instead.
    
    Parameters:
    
    latitude - geographical latitude in decimal degrees (-90.0 <= x <= +90.0)
    
    longitude - geographical longitude in decimal degrees (-180.0 <= x < 180.0)
    
    altitude - geographical altitude relative to sea level in meters (0 <= x < 11,0000)
    
    calculator - instance of solar time calculator
    
    Returns:
    
    instance of local solar time
    
    Throws:
    
    IllegalArgumentException - if the coordinates are out of range
    
    Since:
    
    3.36/4.31
  - ofJerusalem
```
public static SolarTime ofJerusalem()
```
    Obtains an instance of solar time for the temple area in Jerusalem which has a prominent meaning in Hebrew calendar and time.
    
    Returns:
    
    SolarTime
    
    Since:
    
    3.37/4.32
  - ofMecca
```
public static SolarTime ofMecca()
```
    Obtains an instance of solar time for the Kaaba in Mecca which has a prominent meaning in islamic calendar.
    
    The start of day in Mecca can be obtained by the expression StartOfDay.definedBy(SolarTime.ofMecca().sunset()).
    
    Returns:
    
    SolarTime
    
    Since:
    
    3.37/4.32
    
    See Also:
    
    StartOfDay.definedBy(ChronoFunction)
  - getLatitude
```
public double getLatitude()
```
    Description copied from interface: GeoLocation
    
    Obtains the geographical latitude of this instance.
    
    Specified by:
    
    getLatitude in interface GeoLocation
    
    Returns:
    
    latitude in decimal degrees (-90.0 <= x <= +90.0)
  - getLongitude
```
public double getLongitude()
```
    Description copied from interface: GeoLocation
    
    Obtains the geographical longitude of this instance.
    
    Specified by:
    
    getLongitude in interface GeoLocation
    
    Returns:
    
    longitude in decimal degrees (-180.0 <= x < 180.0)
  - getAltitude
```
public int getAltitude()
```
    Description copied from interface: GeoLocation
    
    Obtains the geographical altitude of this instance relative to sea level.
    
    Specified by:
    
    getAltitude in interface GeoLocation
    
    Returns:
    
    altitude in meters (0 <= x < 11,0000)
  - getCalculator
```
public SolarTime.Calculator getCalculator()
```
    Obtains the underlying calculator.
    
    Returns:
    
    String
    
    Since:
    
    3.34/4.29
  - getObserverZoneID
```
public Optional<TZID> getObserverZoneID()
```
    Obtains the optional observer timezone which might be associated with any calendar date input.
    
    Usually, this setting is not relevant for most regions of Earth but can be specified via the builder approach to handle some special cases.
    
    Returns:
    
    optional zone identifier associated with this geographical position
    
    Since:
    
    5.6
    
    See Also:
    
    ofLocation(), SolarTime.Builder.inTimezone(TZID)
  - sunrise
```
public ChronoFunction<CalendarDate,Optional<Moment>> sunrise()
```
    Calculates the moment of sunrise at the location of this instance.
    
    Example:
```
     SolarTime hamburg = SolarTime.ofLocation(53.55, 10.0);
     Optional<Moment> result = PlainDate.nowInSystemTime().get(hamburg.sunrise());
     System.out.println(result.get().toZonalTimestamp(() -> "Europe/Berlin"));
 
```
    Note: The precision is generally constrained to minutes.
    
    The result might be undefined (indicated by Optional.empty()) if the sun does not rise on given day (midnight sun or polar night).
    Returns:
    
    sunrise function applicable on any calendar date
    
    Since:
    
    3.34/4.29
  - sunrise
```
public ChronoFunction<CalendarDate,Optional<Moment>> sunrise(Twilight twilight)
```
    Calculates the time of given twilight at sunrise and the location of this instance.
    
    Note: The precision is generally constrained to minutes. And the atmospheric refraction is here not taken into account.
    
    The result might be undefined (indicated by Optional.empty()) if the twilight event does not happen on given day.
    
    Parameters:
    
    twilight - relevant definition of twilight
    
    Returns:
    
    twilight function at sunrise applicable on any calendar date
    
    Since:
    
    3.34/4.29
  - sunset
```
public ChronoFunction<CalendarDate,Optional<Moment>> sunset()
```
    Calculates the moment of sunset at the location of this instance.
    
    Example:
```
     SolarTime hamburg = SolarTime.ofLocation(53.55, 10.0);
     Optional<Moment> result = PlainDate.nowInSystemTime().get(hamburg.sunset());
     System.out.println(result.get().toZonalTimestamp(() -> "Europe/Berlin"));
 
```
    Note: The precision is generally constrained to minutes.
    
    The result might be undefined (indicated by Optional.empty()) if the sun does not set on given day (midnight sun or polar night).
    Returns:
    
    sunset function applicable on any calendar date
    
    Since:
    
    3.34/4.29
  - sunset
```
public ChronoFunction<CalendarDate,Optional<Moment>> sunset(Twilight twilight)
```
    Calculates the time of given twilight at sunset and the location of this instance.
    
    Note: The precision is generally constrained to minutes. And the atmospheric refraction is here not taken into account.
    
    The result might be undefined (indicated by Optional.empty()) if the twilight event does not happen on given day.
    
    Parameters:
    
    twilight - relevant definition of twilight
    
    Returns:
    
    twilight function at sunset applicable on any calendar date
    
    Since:
    
    3.34/4.29
  - sunshine
```
public ChronoFunction<CalendarDate,SolarTime.Sunshine> sunshine(TZID tzid)
```
    Queries a given calendar date for its associated sunshine data.
    
    The timezone parameter enables users to query for solar time data described in terms of a potentially quite different zone of the earth. However, the parameter does not interprete the input calendar date.
    
    The calculation is only possible if the underlying calculator supports the feature of solar declination. Otherwise an UnsupportedOperationException will be thrown.
    
    Parameters:
    
    tzid - the identifier of the timezone any local times of the result refer to
    
    Returns:
    
    function for obtaining sunshine data
    
    Since:
    
    3.34/4.29
  - polarNight
```
public ChronoCondition<CalendarDate> polarNight()
```
    Determines if the sun is invisible all day on a given calendar date.
    
    The calculation is only possible if the underlying calculator supports the feature of solar declination. Otherwise an UnsupportedOperationException will be thrown.
    
    Returns:
    
    ChronoCondition
    
    Since:
    
    3.34/4.29
  - midnightSun
```
public ChronoCondition<CalendarDate> midnightSun()
```
    Determines if the sun is visible all day on a given calendar date.
    
    The calculation is only possible if the underlying calculator supports the feature of solar declination. Otherwise an UnsupportedOperationException will be thrown.
    
    Returns:
    
    ChronoCondition
    
    Since:
    
    3.34/4.29
  - transitAtNoon
```
public ChronoFunction<CalendarDate,Moment> transitAtNoon()
```
    Calculates the moment of noon at the location of this instance (solar transit).
    
    Note 1: The transit time does not tell if the sun is above or below the horizon.
    
    Note 2: Here, the term noon is not related to civil timekeeping but the sundial time.
    
    Returns:
    
    noon function applicable on any calendar date
    
    Since:
    
    3.34/4.29
  - transitAtMidnight
```
public ChronoFunction<CalendarDate,Moment> transitAtMidnight()
```
    Calculates the moment of midnight at the location of this instance (lowest position of sun).
    
    Note 1: The transit time does not tell if the sun is above or below the horizon.
    
    Note 2: Here, the term midnight is not related to civil timekeeping but the sundial time.
    
    Returns:
    
    midnight function applicable on any calendar date
    
    Since:
    
    3.34/4.29
  - timeOfShadowBeforeNoon
```
public ChronoFunction<CalendarDate,Optional<Moment>> timeOfShadowBeforeNoon(double objectHeight,
                                                                            double shadowLength)
```
    Calculates the moment before noon when the given shadow occurs on given date at the location of this instance.
    
    The function is not supported in polar regions (+/- 66°) because the angle of sun is often changing too slowly to guarantee reliable results. Furthermore, the function might obtain an empty result if the given shadow is too short for the date in question.
    
    Parameters:
    
    objectHeight - the height of object in meters, must be positive
    
    shadowLength - the length of shadow thrown by the object in meters, must not be negative
    
    Returns:
    
    function for calculating the time of shadow applicable on any calendar date in minute precision
    
    Throws:
    
    IllegalArgumentException - if one or both parameters are not finite or out of range
    
    UnsupportedOperationException - if this instance is within the arctic or antarctic circle
    
    Since:
    
    5.7
    
    See Also:
    
    SunPosition.getShadowLength(double), timeOfShadowAfterNoon(double, double)
  - timeOfShadowAfterNoon
```
public ChronoFunction<CalendarDate,Optional<Moment>> timeOfShadowAfterNoon(double objectHeight,
                                                                           double shadowLength)
```
    Calculates the moment after noon when the given shadow occurs on given date at the location of this instance.
    
    The function is not supported in polar regions (+/- 66°) because the angle of sun is often changing too slowly to guarantee reliable results. Furthermore, the function might obtain an empty result if the given shadow is too short for the date in question.
    
    Parameters:
    
    objectHeight - the height of object in meters, must be positive
    
    shadowLength - the length of shadow thrown by the object in meters, must not be negative
    
    Returns:
    
    function for calculating the time of shadow applicable on any calendar date in minute precision
    
    Throws:
    
    IllegalArgumentException - if one or both parameters are not finite or out of range
    
    UnsupportedOperationException - if this instance is within the arctic or antarctic circle
    
    Since:
    
    5.7
    
    See Also:
    
    SunPosition.getShadowLength(double), timeOfShadowBeforeNoon(double, double)
  - equals
```
public boolean equals(Object obj)
```
    Overrides:
    
    equals in class Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - apparentAt
```
public static ChronoFunction<Moment,PlainTimestamp> apparentAt(ZonalOffset offset)
```
    Determines the apparent solar time of any moment at given local time zone offset.
    
    Based on the astronomical equation of time. The default calculator is usually StdSolarCalculator.NOAA unless another calculator was set up via the service loader mechnism.
    
    Parameters:
    
    offset - the time zone offset which might depend on the geographical longitude
    
    Returns:
    
    function for getting the apparent solar time
    
    See Also:
    
    ZonalOffset.atLongitude(OffsetSign, int, int, double), equationOfTime(Moment)
  - apparentAt
```
public static ChronoFunction<Moment,PlainTimestamp> apparentAt(ZonalOffset offset,
                                                               String calculator)
```
    Determines the apparent solar time of any moment at given local time zone offset.
    
    Based on the astronomical equation of time.
    
    Parameters:
    
    offset - the time zone offset which might depend on the geographical longitude
    
    calculator - name of solar time calculator
    
    Returns:
    
    function for getting the apparent solar time
    
    Since:
    
    3.34/4.29
    
    See Also:
    
    ZonalOffset.atLongitude(OffsetSign, int, int, double), equationOfTime(Moment, String)
  - onAverage
```
public static ChronoFunction<Moment,PlainTimestamp> onAverage(ZonalOffset offset)
```
    Determines the mean solar time of any moment at given local time zone offset.
    
    Parameters:
    
    offset - the time zone offset which might depend on the geographical longitude
    
    Returns:
    
    function for getting the mean solar time
    
    See Also:
    
    ZonalOffset.atLongitude(OffsetSign, int, int, double)
  - equationOfTime
```
public static double equationOfTime(Moment moment)
```
    Determines the difference between apparent and mean solar time at given moment.
    
    See also Wikipedia. Relation: mean-solar-time + equation-of-time = apparent-solar-time
    
    The default calculator is usually StdSolarCalculator.NOAA unless another calculator was set up via the service loader mechnism.
    
    Parameters:
    
    moment - the moment when to determine the equation of time
    
    Returns:
    
    difference between apparent solar time and mean solar time in seconds
    
    Throws:
    
    IllegalArgumentException - if the moment is out of year range -2000/+3000
  - equationOfTime
```
public static double equationOfTime(Moment moment,
                                    String calculator)
```
    Determines the difference between apparent and mean solar time at given moment.
    
    See also Wikipedia.
    
    Relation: mean-solar-time + equation-of-time = apparent-solar-time
    
    Parameters:
    
    moment - the moment when to determine the equation of time
    
    calculator - name of solar time calculator
    
    Returns:
    
    difference between apparent solar time and mean solar time in seconds
    
    Throws:
    
    IllegalArgumentException - if the moment is out of year range -2000/+3000 or if the calculator is unknown
    
    Since:
    
    3.34/4.29

Class SolarTime

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface net.time4j.calendar.astro.GeoLocation

Method Detail

ofLocation

ofLocation

ofLocation

ofLocation

ofJerusalem

ofMecca

getLatitude

getLongitude

getAltitude

getCalculator

getObserverZoneID

sunrise

sunrise

sunset

sunset

sunshine

polarNight

midnightSun

transitAtNoon

transitAtMidnight

timeOfShadowBeforeNoon

timeOfShadowAfterNoon

equals

hashCode

toString

apparentAt

apparentAt

onAverage

equationOfTime

equationOfTime