Astronomical
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 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 Exceptions 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 timeZone 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.calendar.set(Calendar.MONTH, Calendar.FEBRUARY); ac.calendar.set(Calendar.DAY_OF_MONTH, 8); Date sunrise = ac.getSunrise();*
Author
Eliyahu Hershfeld 2004 - 2023
Inheritors
Properties
The internal AstronomicalCalculator used for calculating solar based times. A method to set the AstronomicalCalculator used for astronomical calculations. The Zmanim package ships with a number of different implementations of the abstract AstronomicalCalculator based on different algorithms, including the default com.kosherjava.zmanim.util.NOAACalculator based on NOAA's implementation of Jean Meeus's algorithms as well as [] based on the US * Naval Observatory's algorithm,. This allows easy runtime switching and comparison of different algorithms.
A method that returns the beginning of astronomical twilight using a zenith of .ASTRONOMICAL_ZENITH.
A method that returns the beginning of civil twilight (dawn) using a zenith of .CIVIL_ZENITH.
A method that returns the beginning of nautical twilight using a zenith of NAUTICAL_ZENITH.
A method that returns the end of astronomical twilight using a zenith of .ASTRONOMICAL_ZENITH.
A method that returns the end of civil twilight using a zenith of .CIVIL_ZENITH.
A method that returns the end of nautical twilight using a zenith of .NAUTICAL_ZENITH.
the GeoLocation used for calculations.
The Java Calendar encapsulated by this class to track the current date used by the class
A method that returns the sunrise without elevation. Non-sunrise 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.
A method that returns the sunset without elevation. Non-sunrise 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.
The sunrise method returns an Instant representing the elevation adjusted sunrise time. The zenith used for the calculation uses geometric zenith of 90 plus AstronomicalCalculator.getElevationAdjustment. This is adjusted by the 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 90.83333˚. See documentation for the specific implementation of the AstronomicalCalculator that you are using.
The getSunset method Returns a Date representing the elevation adjusted sunset time. The zenith used for the calculation uses geometric zenith of 90 plus AstronomicalCalculator.getElevationAdjustment. This is adjusted by the 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 90.83333˚. See documentation for the specific implementation of the 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.
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 the AstronomicalCalculator used. If this calendar instance is astronomicalCalculator to use the com.kosherjava.zmanim.util.NOAACalculator (the default) it will calculate astronomical noon. If the calendar instance is to use the com.kosherjava.zmanim.util.SunTimesCalculator, 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.
A method that returns an elevation adjusted temporal (solar) hour. The day from sunrise to sunset is split into 12 equal parts with each one being a temporal hour.
Functions
A method that creates a deep copy of the object.
A utility method that returns the time of an offset by degrees below or above the horizon of sunrise. Note that the degree offset is from the vertical, so for a calculation of 14 before sunrise, an offset of 14 + AstronomicalCalendar.GEOMETRIC_ZENITH = 104 would have to be passed as a parameter.
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.
A utility method that returns the time of an offset by degrees below or above the horizon of sunset. Note that the degree offset is from the vertical, so for a calculation of 14 after sunset, an offset of 14 + AstronomicalCalendar.GEOMETRIC_ZENITH = 104 would have to be passed as a parameter.
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.
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).
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 non-elevation adjusted temporal hour by passing in sea level sunrise and sea level sunset as parameters.
A method that returns the sunrise in UTC time without correction for time zone offset from GMT and without using daylight savings time. Non-sunrise 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.
A method that returns the sunset in UTC time without correction for elevation, time zone offset from GMT and without using daylight savings time. Non-sunrise 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.
A method that returns the sunrise in UTC time without correction for time zone offset from GMT and without using daylight savings time.
A method that returns the sunset in UTC time without correction for time zone offset from GMT and without using daylight savings time.