Package com.kosherjava.zmanim
Class AstronomicalCalendar
java.lang.Object
com.kosherjava.zmanim.AstronomicalCalendar
 All Implemented Interfaces:
Cloneable
 Direct Known Subclasses:
ZmanimCalendar
A Java calendar that calculates astronomical times such as
sunrise
, sunset
and twilight times. This class contains a 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 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
Date
is expected and 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
// 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  2023

Field Summary
Modifier and TypeFieldDescriptionstatic final double
Sun's zenith at astronomical twilight (108°).private AstronomicalCalculator
the internalAstronomicalCalculator
used for calculating solar based times.private Calendar
The Java Calendar encapsulated by this class to track the current date used by the classstatic final double
Sun's zenith at civil twilight (96°).private GeoLocation
theGeoLocation
used for calculations.static final double
90° below the vertical.static final long
constant for milliseconds in an hour (3,600,000)static final long
constant for milliseconds in a minute (60,000)static final double
Sun's zenith at nautical twilight (102°). 
Constructor Summary
ConstructorDescriptionDefault constructor will set a defaultGeoLocation()
, a defaultAstronomicalCalculator
and default the calendar to the current date.AstronomicalCalendar
(GeoLocation geoLocation) A constructor that takes in geolocation information as a parameter. 
Method Summary
Modifier and TypeMethodDescriptionclone()
A method that creates a deep copy of the object.boolean
private Calendar
Adjusts theCalendar
to deal with edge cases where the location crosses the antimeridian.A method that returns the currently set AstronomicalCalculator.A method that returns the beginning of astronomical twilight using a zenith of108°
.A method that returns the beginning of civil twilight (dawn) using a zenith of96°
.A method that returns the beginning of nautical twilight using a zenith of102°
.returns the Calendar object encapsulated in this class.protected Date
getDateFromTime
(double time, boolean isSunrise) A method that returns aDate
from the time passed in as a parameter.A method that returns the end of astronomical twilight using a zenith of108°
.A method that returns the end of civil twilight using a zenith of96°
.A method that returns the end of nautical twilight using a zenith of102°
.A method that returns the currently setGeoLocation
which contains location information used for the astronomical calculations.getLocalMeanTime
(double hours) A method that returns local mean time (LMT) time converted to regular clock time for the number of hours (0.0 to 23.999...) passed to this method.A method that returns the sunrise withoutelevation adjustment
.A method that returns the sunset withoutelevation adjustment
.A method that returns "solar" midnight, or the time when the sun is at its nadir.The getSunrise method Returns aDate
representing theelevation adjusted
sunrise time.getSunriseOffsetByDegrees
(double offsetZenith) A utility method that returns the time of an offset by degrees below or above the horizon ofsunrise
.double
getSunriseSolarDipFromOffset
(double minutes) Returns the dip below the horizon before sunrise that matches the offset minutes on passed in as a parameter.The getSunset method Returns aDate
representing theelevation adjusted
sunset time.getSunsetOffsetByDegrees
(double offsetZenith) A utility method that returns the time of an offset by degrees below or above the horizon ofsunset
.double
getSunsetSolarDipFromOffset
(double minutes) Returns the dip below the horizon after sunset that matches the offset minutes on passed in as a parameter.A method that returns sundial or solar noon.getSunTransit
(Date startOfDay, Date endOfDay) A method that returns sundial or solar noon.long
A method that returns anelevation adjusted
temporal (solar) hour.long
getTemporalHour
(Date startOfday, Date 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.static Date
getTimeOffset
(Date time, double offset) A utility method that returns a date offset by the offset time passed in as a parameter.static Date
getTimeOffset
(Date time, long offset) A utility method that returns a date offset by the offset time passed in.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.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.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.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.int
hashCode()
void
setAstronomicalCalculator
(AstronomicalCalculator astronomicalCalculator) A method to set theAstronomicalCalculator
used for astronomical calculations.void
setCalendar
(Calendar calendar) void
setGeoLocation
(GeoLocation geoLocation) Sets theGeoLocation
Object
to be used for astronomical calculations.toJSON()
toString()

Field Details

GEOMETRIC_ZENITH
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 theadjusted 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°. See Also:

CIVIL_ZENITH
Sun's zenith at civil twilight (96°). See Also:

NAUTICAL_ZENITH
Sun's zenith at nautical twilight (102°). See Also:

ASTRONOMICAL_ZENITH
Sun's zenith at astronomical twilight (108°). See Also:

MINUTE_MILLIS
constant for milliseconds in a minute (60,000) See Also:

HOUR_MILLIS
constant for milliseconds in an hour (3,600,000) See Also:

calendar
The Java Calendar encapsulated by this class to track the current date used by the class 
geoLocation
theGeoLocation
used for calculations. 
astronomicalCalculator
the internalAstronomicalCalculator
used for calculating solar based times.


Constructor Details

AstronomicalCalendar
public AstronomicalCalendar()Default constructor will set a defaultGeoLocation()
, a defaultAstronomicalCalculator
and default the calendar to the current date. 
AstronomicalCalendar
A constructor that takes in geolocation information as a parameter. The defaultAstronomicalCalculator
used for solar calculations is the theNOAACalculator
. Parameters:
geoLocation
 The location information used for calculating astronomical sun times. See Also:


Method Details

getSunrise
The getSunrise method Returns aDate
representing theelevation adjusted
sunrise time. The zenith used for the calculation usesgeometric zenith
of 90° plusAstronomicalCalculator.getElevationAdjustment(double)
. This is adjusted by theAstronomicalCalculator
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 of90.83333°
. See documentation for the specific implementation of theAstronomicalCalculator
that you are using. Returns:
 the
Date
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, anull
will be returned. See detailed explanation on top of the page.  See Also:

getSeaLevelSunrise
A method that returns the sunrise withoutelevation 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. Returns:
 the
Date
representing the exact sealevel 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, anull
will be returned. See detailed explanation on top of the page.  See Also:

getBeginCivilTwilight
A method that returns the beginning of civil twilight (dawn) using a zenith of96°
. Returns:
 The
Date
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
A method that returns the beginning of nautical twilight using a zenith of102°
. Returns:
 The
Date
of the beginning of nautical twilight using a zenith of 102°. If the calculation can't be computednull
will be returned. See detailed explanation on top of the page.  See Also:

getBeginAstronomicalTwilight
A method that returns the beginning of astronomical twilight using a zenith of108°
. Returns:
 The
Date
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:

getSunset
The getSunset method Returns aDate
representing theelevation adjusted
sunset time. The zenith used for the calculation usesgeometric zenith
of 90° plusAstronomicalCalculator.getElevationAdjustment(double)
. This is adjusted by theAstronomicalCalculator
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 of90.83333°
. See documentation for the specific implementation of theAstronomicalCalculator
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
Date
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, anull
will be returned. See detailed explanation on top of the page.  See Also:

getSeaLevelSunset
A method that returns the sunset withoutelevation 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. Returns:
 the
Date
representing the exact sealevel 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, anull
will be returned. See detailed explanation on top of the page.  See Also:

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

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

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

getTimeOffset
A utility method that returns a date offset by the offset time passed in as a parameter. This method casts the offset as along
and callsgetTimeOffset(Date, long)
. Parameters:
time
 the start timeoffset
 the offset in milliseconds to add to the time Returns:
 the
Date
with the offset added to it

getTimeOffset
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. Parameters:
time
 the start timeoffset
 the offset in milliseconds to add to the time. Returns:
 the
Date
with the offset in milliseconds added to it

getSunriseOffsetByDegrees
A utility method that returns the time of an offset by degrees below or above the horizon ofsunrise
. 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 beforegetSunrise()
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
Date
of the offset after (or before)getSunrise()
. 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, anull
will be returned. See detailed explanation on top of the page.

getSunsetOffsetByDegrees
A utility method that returns the time of an offset by degrees below or above the horizon ofsunset
. 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 aftergetSunset()
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
Date
of the offset after (or before)getSunset()
. 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, anull
will be returned. See detailed explanation on top of the page.

getUTCSunrise
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
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. 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
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
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. 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
A method that returns anelevation adjusted
temporal (solar) hour. The day fromsunrise
tosunset
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
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 insea level sunrise
andsea level 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 aLong.MIN_VALUE
will be returned. See detailed explanation on top of the page.  See Also:

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 theAstronomicalCalculator
used. If this calendar instance isset
to use theNOAACalculator
(the default) it will calculate astronomical noon. If the calendar instance is to use theSunTimesCalculator
, 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
Date
representing Sun's transit. If the calculation can't be computed such as when using theUSNO 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), anull
will be returned. See detailed explanation on top of the page.  See Also:

getSolarMidnight
A method that returns "solar" midnight, or the time when the sun is at its nadir. The current calculation is halfway between today and tomorrow'ssun transit
. Returns:
 the
Date
of astronomical solar midnight. If the calculation can't be computed such as when using theUSNO 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), anull
will be returned. See detailed explanation on top of the page.  See Also:

getSunTransit
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
Date
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.

getDateFromTime
A method that returns aDate
from the time passed in as a parameter. Parameters:
time
 The time to be set as the time for theDate
. The time expected is in the format: 18.75 for 6:45:00 PM.time is sunrise and false if it is sunsetisSunrise
 true if the Returns:
 The Date.

getSunriseSolarDipFromOffset
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. Parameters:
minutes
 offset Returns:
 the degrees below the horizon before sunrise that match the offset in minutes passed it as a parameter.
 See Also:
 TODO:
 Improve efficiency of this method by not brute forcing the calculation.

getSunsetSolarDipFromOffset
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. Parameters:
minutes
 offset Returns:
 the degrees below the horizon after sunset that match the offset in minutes passed it as a parameter.
 See Also:
 TODO:
 Improve efficiency of this method by not brute forcing the calculation.

getLocalMeanTime
A method that returns local mean time (LMT) time converted to regular clock time for the number of hours (0.0 to 23.999...) 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:
hours
 the hour (such as 12.0 for noon and 0.0 for midnight) to calculate as LMT. Valid values are in the range of 0.0 to 23.999.... An IllegalArgumentException will be thrown if the value does not fit in the expected range. Returns:
 the Date representing the local mean time (LMT) for the number of hours passed in. In Lakewood, NJ, passing 12 (noon) will return 11:56:50am.
 See Also:

getAdjustedCalendar
Adjusts theCalendar
to deal with edge cases where the location crosses the antimeridian. Returns:
 the adjusted Calendar
 See Also:

toString

toJSON
 Returns:
 a JSON formatted representation of the class. It returns the default output of the
toJSON
method.  See Also:

equals

hashCode

getGeoLocation
A method that returns the currently setGeoLocation
which contains location information used for the astronomical calculations. Returns:
 Returns the geoLocation.

setGeoLocation
Sets theGeoLocation
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
A method that returns the currently set AstronomicalCalculator. Returns:
 Returns the astronomicalCalculator.
 See Also:

setAstronomicalCalculator
A method to set theAstronomicalCalculator
used for astronomical calculations. The Zmanim package ships with a number of different implementations of theabstract
AstronomicalCalculator
based on different algorithms, including the defaultNOAACalculator
based on NOAA's implementation of Jean Meeus's algorithms as well asSunTimesCalculator
based on the US Naval Observatory's algorithm,. This allows easy runtime switching and comparison of different algorithms. Parameters:
astronomicalCalculator
 The astronomicalCalculator to set.

getCalendar
returns the Calendar object encapsulated in this class. Returns:
 Returns the calendar.

setCalendar
 Parameters:
calendar
 The calendar to set.

clone
A method that creates a deep copy of the object. Note: If theTimeZone
in the clonedGeoLocation
will be changed from the original, it is critical thatgetCalendar()
.setTimeZone(TimeZone)
be called in order for the AstronomicalCalendar to output times in the expected offset after being cloned.
