A constructor that takes in geolocation information as a parameter.
The location information used for calculating astronomical sun times.
Static ReadonlyASTRONOMICAL_Sun's zenith at astronomical twilight (108°).
Static ReadonlyCIVIL_Sun's zenith at civil twilight (96°).
Static ReadonlyNAUTICAL_Sun's zenith at nautical twilight (102°).
Adjusts the zenith of astronomical sunrise and sunset to account for solar refraction, solar radius and elevation. The value for Sun's zenith and true rise/set Zenith (used in this class and subclasses) is the angle that the center of the Sun makes to a line perpendicular to the Earth's surface. If the Sun were a point and the Earth were without an atmosphere, true sunset and sunrise would correspond to a 90° zenith. Because the Sun is not a point, and because the atmosphere refracts light, this 90° zenith does not, in fact, correspond to true sunset or sunrise, instead the centre of the Sun's disk must lie just below the horizon for the upper edge to be obscured. This means that a zenith of just above 90° must be used. The Sun subtends an angle of 16 minutes of arc, and atmospheric refraction accounts for 34 minutes or so, giving a total of 50 arcminutes. The total value for ZENITH is 90+(5/6) or 90.8333333° for true sunrise/sunset. Since a person at an elevation can see blow the horizon of a person at sea level, this will also adjust the zenith to account for elevation if available. Note that this will only adjust the value if the zenith is exactly 90 degrees. For values below and above this no correction is done. As an example, astronomical twilight is when the sun is 18° below the horizon or 108°. This is traditionally calculated with none of the above mentioned adjustments. The same goes for various tzais and alos times such as the ZmanimCalendar#ZENITH_16_POINT_1 16.1° dip used in ComplexZmanimCalendar#getAlos16Point1Degrees.
the azimuth below the vertical zenith of 90°. For sunset typically the * zenith used for the calculation uses geometric zenith of 90° and adjusts this slightly to account for solar refraction and the sun's radius. Another example would be getEndNauticalTwilight that passes NAUTICAL_ZENITH to this method.
elevation in Meters.
The zenith adjusted to include the sun's radius, refracton and elevation adjustment. This will only be adjusted for sunrise and sunset (if the zenith == 90°)
A method that returns the beginning of astronomical twilight using a zenith of * 108°.
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.
A method that returns the beginning of civil twilight (dawn) using a zenith of 96°.
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.
A method that returns the beginning of nautical twilight using a zenith of 102°.
The Date of the beginning of nautical twilight using a zenith of 102°. If the
calculation can't be computed null will be returned. See detailed explanation on top of the page.
ProtectedgetProtectedA method that returns a Date from the time passed in as a parameter.
The time to be set as the time for the Date. The time expected is in the format: 18.75
for 6:45:00 PM.
true if the time is sunrise, and false if it is sunset
The Date.
Method to return the adjustment to the zenith required to account for the elevation. Since a person at a higher elevation can see farther below the horizon, the calculation for sunrise / sunset is calculated below the horizon used at sea level. This is only used for sunrise and sunset and not times before or after it such as () nautical twilight since those calculations are based on the level of available light at the given dip below the horizon, something that is not affected by elevation, the adjustment should only made if the zenith == 90° adjusted for refraction and solar radius. The algorithm used is
elevationAdjustment = Math.toDegrees(Math.acos(earthRadiusInMeters / (earthRadiusInMeters + elevationMeters)));
The source of this algorithm is Calendrical Calculations by Edward M. Reingold and Nachum Dershowitz. An alternate algorithm that produces an almost identical (but not accurate) result found in Ma'aglay Tzedek by Moishe Kosower and other sources is:
elevationAdjustment = 0.0347 * Math.sqrt(elevationMeters);
elevation in Meters.
the adjusted zenith
A method that returns the end of astronomical twilight using a zenith of 108°.
The Date of the end 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.
A method that returns the end of civil twilight using a zenith of 96°.
The Date of the end 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.
A method that returns the end of nautical twilight using a zenith of 102°.
The Date of the end of nautical twilight using a zenith of 102°
. If the calculation can't be computed, null will be returned. See detailed explanation on top of the
page.
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.
the Date representing the exact sea-level 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, a null will be returned. See detailed explanation on top of the page.
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 Date representing the exact sea-level 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, a null will be returned. See detailed explanation on top of the page.
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).
OptionalstartOfDay: null | ZonedDateTimethe 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.
OptionalendOfDay: null | ZonedDateTimethe 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.
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.
The getSunrise method Returns a Date representing the
elevation adjusted sunrise time. The zenith used
for the calculation uses GEOMETRIC_ZENITH geometric zenith of 90° plus
getElevationAdjustment. This is adjusted
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°.
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, a null will be returned. See detailed explanation on top of the page.
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 + GEOMETRIC_ZENITH = 104 would have to be passed as a parameter.
the degrees before getSunrise 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.
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, a null will be returned. See detailed explanation on top of the
page.
The getSunset method Returns a Date representing the
elevation adjusted sunset time. The zenith used for
the calculation uses GEOMETRIC_ZENITH geometric zenith of 90° plus
getElevationAdjustment. This is adjusted
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°.
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.
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, a null will be returned. See detailed explanation on top of the page.
A utility method that returns the time of an offset by degrees below or above the horizon of (). 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.
the degrees after getSunset 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.
The Dateof 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, a null will be returned. See detailed explanation on top of the
page.
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.
OptionalstartOfDay: null | ZonedDateTimeThe start of the day.
OptionalendOfDay: null | ZonedDateTimeThe end of the day.
the long millisecond length of the temporal hour. If the calculation can't be computed a
NaN will be returned. See detailed explanation on top of the page.
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.
the degrees below the horizon. For time after sunrise use negative numbers.
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, NaN will be returned. See detailed explanation on top of the page.
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.
the degrees below the horizon. For time before sunset use negative numbers.
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, NaN will be returned. See detailed explanation on top of the page.
A method that calculates UTC sunrise as well as any time based on an angle above or below sunrise.
Used to calculate day of year.
The location information used for astronomical calculating sun times.
the azimuth below the vertical zenith of 90 degrees. for sunrise typically the * zenith used for the calculation uses geometric zenith of 90° and adjusts this slightly to account for solar refraction and the sun's radius. Another example would be getBeginNauticalTwilight that passes NAUTICAL_ZENITH to this method.
Should the time be adjusted for elevation
The UTC time of sunrise in 24 hour format. 5:45:00 AM will return 5.75.0. If an error was encountered in
the calculation (expected behavior for some locations such as near the poles,
NaN will be returned.
A method that returns the sunrise in UTC time without correction for time zone offset from GMT and without using daylight savings time.
the degrees below the horizon. For time after sunrise use negative numbers.
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, NaN will be returned. See detailed explanation on top of the page.
A method that calculates UTC sunset as well as any time based on an angle above or below sunset.
Used to calculate day of year.
The location information used for astronomical calculating sun times.
the azimuth below the vertical zenith of 90°. For sunset typically the * zenith used for the calculation uses geometric zenith of 90° and adjusts this slightly to account for solar refraction and the sun's radius. Another example would be getEndNauticalTwilight that passes NAUTICAL_ZENITH to this method.
Should the time be adjusted for elevation
The UTC time of sunset in 24 hour format. 5:45:00 AM will return 5.75.0. If an error was encountered in
the calculation (expected behavior for some locations such as near the poles,
NaN will be returned.
A method that returns the sunset in UTC time without correction for time zone offset from GMT and without using daylight savings time.
the degrees below the horizon. For time after sunset use negative numbers.
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, NaN will be returned. See detailed explanation on top of the page.
StaticgetReturn the Solar Azimuth for the horizontal coordinate system at the given location at the given time. Not corrected for altitude. True south is 0 degrees.
time of calculation
latitude of location for calculation
longitude of location for calculation
StaticgetReturn the Solar Elevation for the horizontal coordinate system at the given location at the given time. Can be negative if the sun is below the horizon. Not corrected for altitude.
time of calculation
latitude of location for calculation
longitude of location for calculation
solar elevation in degrees - horizon is 0 degrees, civil twilight is -6 degrees
StaticgetA 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.
the start time
the offset in milliseconds to add to the time.
the Date with the offset in milliseconds added to it
Implementation of sunrise and sunset methods to calculate astronomical times based on the NOAA algorithm. This calculator uses the Java algorithm based on the implementation by NOAA - National Oceanic and Atmospheric Administration's Surface Radiation Research Branch. NOAA's implementation is based on equations from Astronomical Algorithms by Jean Meeus. Added to the algorithm is an adjustment of the zenith to account for elevation. The algorithm can be found in the Wikipedia Sunrise Equation article.
Author
© Eliyahu Hershfeld 2011 - 2019