AstronomicalCalendar class
A Java calendar that calculates astronomical times such as {@link #getSunrise() sunrise}, {@link #getSunset()
sunset} and twilight times. This class contains a {@link #getCalendar() Calendar} 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 {@link AstronomicalCalculator} and setting it with
the {@link #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
{@link java.util.Date}
is expected and {@link Long#MIN_VALUE} when a long
is expected. The
reason that Exception
s 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 getTimeZone() has to be a valid timezone listed in // {@link java.util.TimeZone#getAvailableIDs()} TimeZone timeZone = TimeZone.getTimeZone("America/New_York"); GeoLocation location = new GeoLocation(locationName, latitude, longitude, elevation, timeZone); 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):
ac.getCalendar().set(Calendar.MONTH, Calendar.FEBRUARY); ac.getCalendar().set(Calendar.DAY_OF_MONTH, 8); Date sunrise = ac.getSunrise();
@author © Eliyahu Hershfeld 2004  2020
 Implementers
Constructors
 AstronomicalCalendar({GeoLocation geoLocation})
 A constructor that takes in geolocation information as a parameter. The default {@link AstronomicalCalculator#getDefault() AstronomicalCalculator} used for solar calculations is the the {@link net.sourceforge.zmanim.util.NOAACalculator}. [...]
Properties
 astronomicalCalculator ↔ AstronomicalCalculator

read / write
 geoLocation ↔ GeoLocation

read / write
 hashCode → int

The hash code for this object. [...]
readonly, inherited
 runtimeType → Type

A representation of the runtime type of the object.
readonly, inherited
Methods

getAdjustedCalendar(
) → DateTime 
Adjusts the
Calendar
to deal with edge cases where the location crosses the antimeridian. [...] 
getAstronomicalCalculator(
) → AstronomicalCalculator  A method that returns the currently set AstronomicalCalculator. [...]

getBeginAstronomicalTwilight(
) → DateTime  A method that returns the beginning of astronomical twilight using a zenith of {@link #ASTRONOMICAL_ZENITH 108°}. [...]

getBeginCivilTwilight(
) → DateTime  A method that returns the beginning of civil twilight (dawn) using a zenith of {@link #CIVIL_ZENITH 96°}. [...]

getBeginNauticalTwilight(
) → DateTime  A method that returns the beginning of nautical twilight using a zenith of {@link #NAUTICAL_ZENITH 102°}. [...]

getCalendar(
) → DateTime  returns the Calendar object encapsulated in this class. [...]

getDateFromTime(
double time, bool isSunrise) → DateTime 
A method that returns a
Date
from the time passed in as a parameter. [...] 
getEndAstronomicalTwilight(
) → DateTime  A method that returns the end of astronomical twilight using a zenith of {@link #ASTRONOMICAL_ZENITH 108°}. [...]

getEndCivilTwilight(
) → DateTime  A method that returns the end of civil twilight using a zenith of {@link #CIVIL_ZENITH 96°}. [...]

getEndNauticalTwilight(
) → DateTime  A method that returns the end of nautical twilight using a zenith of {@link #NAUTICAL_ZENITH 102°}. [...]

getGeoLocation(
) → GeoLocation  A method that returns the currently set {@link GeoLocation} which contains location information used for the astronomical calculations. [...]

getSeaLevelSunrise(
) → DateTime  A method that returns the sunrise without {@link AstronomicalCalculator#getElevationAdjustment(double) elevation adjustment}. Nonsunrise 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. [...]

getSeaLevelSunset(
) → DateTime  A method that returns the sunset without {@link AstronomicalCalculator#getElevationAdjustment(double) elevation adjustment}. Nonsunrise 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. [...]

getSunrise(
) → DateTime 
The getSunrise method Returns a
Date
representing the {@link AstronomicalCalculator#getElevationAdjustment(double) elevation adjusted} sunrise time. The zenith used for the calculation uses {@link #GEOMETRIC_ZENITH geometric zenith} of 90° plus {@link AstronomicalCalculator#getElevationAdjustment(double)}. This is adjusted by the {@link 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 {@link AstronomicalCalculator#adjustZenith 90.83333°}. See documentation for the specific implementation of the {@link AstronomicalCalculator} that you are using. [...] 
getSunriseOffsetByDegrees(
double offsetZenith) → DateTime  A utility method that returns the time of an offset by degrees below or above the horizon of {@link #getSunrise() sunrise}. Note that the degree offset is from the vertical, so for a calculation of 14° before sunrise, an offset of 14 + {@link #GEOMETRIC_ZENITH} = 104 would have to be passed as a parameter. [...]

getSunriseSolarDipFromOffset(
double minutes) → double  Returns the dip 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° Please note that this method is very slow and inefficient and should NEVER be used in a loop. TODO: Improve efficiency. [...]

getSunset(
) → DateTime 
The getSunset method Returns a
Date
representing the {@link AstronomicalCalculator#getElevationAdjustment(double) elevation adjusted} sunset time. The zenith used for the calculation uses {@link #GEOMETRIC_ZENITH geometric zenith} of 90° plus {@link AstronomicalCalculator#getElevationAdjustment(double)}. This is adjusted by the {@link 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 {@link AstronomicalCalculator#adjustZenith 90.83333°}. See documentation for the specific implementation of the {@link 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. [...] 
getSunsetOffsetByDegrees(
double offsetZenith) → DateTime  A utility method that returns the time of an offset by degrees below or above the horizon of {@link #getSunset() sunset}. Note that the degree offset is from the vertical, so for a calculation of 14° after sunset, an offset of 14 + {@link #GEOMETRIC_ZENITH} = 104 would have to be passed as a parameter. [...]

getSunsetSolarDipFromOffset(
double minutes) → double  Returns the dip below the horizon after sunset 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° Please note that this method is very slow and inefficient and should NEVER be used in a loop. TODO: Improve efficiency. [...]

getSunTransit(
[DateTime startOfDay, DateTime endOfDay]) → DateTime  A method that returns sundial or solarnoon. 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). [...]

getTemporalHour(
[DateTime startOfDay, DateTime endOfDay]) → double  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 nonelevation adjusted temporal hour by passing in {@link #getSeaLevelSunrise() sea level sunrise} and {@link #getSeaLevelSunset() sea level sunset} as parameters. [...]

getUTCSeaLevelSunrise(
double zenith) → double  A method that returns the sunrise in UTC time without correction for time zone offset from GMT and without using daylight savings time. Nonsunrise 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. [...]

getUTCSeaLevelSunset(
double zenith) → double  A method that returns the sunset in UTC time without correction for elevation, time zone offset from GMT and without using daylight savings time. Nonsunrise 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. [...]

getUTCSunrise(
double zenith) → double  A method that returns the sunrise in UTC time without correction for time zone offset from GMT and without using daylight savings time. [...]

getUTCSunset(
double zenith) → double  A method that returns the sunset in UTC time without correction for time zone offset from GMT and without using daylight savings time. [...]

noSuchMethod(
Invocation invocation) → dynamic 
Invoked when a nonexistent method or property is accessed. [...]
inherited

setAstronomicalCalculator(
AstronomicalCalculator astronomicalCalculator) → void 
A method to set the {@link AstronomicalCalculator} used for astronomical calculations. The Zmanim package ships
with a number of different implementations of the
abstract
{@link AstronomicalCalculator} based on different algorithms, including {@link net.sourceforge.zmanim.util.SunTimesCalculator one implementation} based on the US Naval Observatory's algorithm, and {@link net.sourceforge.zmanim.util.NOAACalculator another} based on NOAA's algorithm. This allows easy runtime switching and comparison of different algorithms. [...] 
setCalendar(
DateTime calendar) → void  @param calendar The calendar to set.

setGeoLocation(
GeoLocation geoLocation) → void 
Sets the {@link GeoLocation}
Object
to be used for astronomical calculations. [...] 
toString(
) → String 
Returns a string representation of this object.
inherited
Operators

operator ==(
Object other) → bool 
The equality operator. [...]
inherited
Static Methods

getTimeOffset(
DateTime time, double offset) → DateTime  A utility method that returns a date 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. [...]
Constants
 ASTRONOMICAL_ZENITH → const double

Sun's zenith at astronomical twilight (108°).
108
 CIVIL_ZENITH → const double

Sun's zenith at civil twilight (96°).
96
 GEOMETRIC_ZENITH → const double

90° below the vertical. Used as a basis for most calculations since the location of the sun is 90° below
the horizon at sunrise and sunset.
Note : it is important to note that for sunrise and sunset the {@link AstronomicalCalculator#adjustZenith
adjusted zenith} is required to account for the radius of the sun and refraction. The adjusted zenith should not
be used for calculations above or below 90° since they are usually calculated as an offset to 90°.
90
 HOUR_MILLIS → const double

constant for milliseconds in an hour (3,600,000)
MINUTE_MILLIS * 60
 MINUTE_MILLIS → const double

constant for milliseconds in a minute (60,000)
60.0 * 1000.0
 NAUTICAL_ZENITH → const double

Sun's zenith at nautical twilight (102°).
102