Class NOAACalculator
java.lang.Object
com.kosherjava.zmanim.util.AstronomicalCalculator
com.kosherjava.zmanim.util.NOAACalculator
- All Implemented Interfaces:
Cloneable
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 - 2025
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprotected static enum
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final double
The Julian day of January 1, 2000, known as J2000.0.private static final double
Julian days per century. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionReturns the name of the algorithm.private static double
getEarthOrbitEccentricity
(double julianCenturies) Return the unitless eccentricity of earth's orbit.private static double
getEquationOfTime
(double julianCenturies) Return the Equation of Time - the difference between true solar time and mean solar timeprivate static double
getJulianCenturiesFromJulianDay
(double julianDay) Convert Julian day to centuries since J2000.0.private static double
getJulianDay
(Calendar calendar) Return the Julian day from a Java Calendar.private static double
getMeanObliquityOfEcliptic
(double julianCenturies) Returns the mean obliquity of the ecliptic (Axial tilt).private static double
getObliquityCorrection
(double julianCenturies) Returns the corrected obliquity of the ecliptic (Axial tilt).static double
getSolarAzimuth
(Calendar calendar, double latitude, double longitude) Return the Solar Azimuth for the horizontal coordinate system at the given location at the given time.static double
getSolarElevation
(Calendar calendar, double latitude, double longitude) Return the Solar Elevation for the horizontal coordinate system at the given location at the given time.private static double
getSolarNoonMidnightUTC
(double julianDay, double longitude, NOAACalculator.SolarEvent solarEvent) Return the Universal Coordinated Time (UTC) of the current day solar noon or the the upcoming midnight (about 12 hours after solar noon) of the given day at the given location on earth.private static double
getSunApparentLongitude
(double julianCenturies) Return the apparent longitude of the sun.private static double
getSunDeclination
(double julianCenturies) Return the declination of the sun.private static double
getSunEquationOfCenter
(double julianCenturies) Returns the equation of center for the sun in degrees.private static double
getSunGeometricMeanAnomaly
(double julianCenturies) Returns the Geometric Mean Anomaly of the Sun in degrees.private static double
getSunGeometricMeanLongitude
(double julianCenturies) Returns the Geometric Mean Longitude of the Sun.private static double
getSunHourAngle
(double latitude, double solarDeclination, double zenith, NOAACalculator.SolarEvent solarEvent) Return the hour angle of the sun in radians at for the latitude.private static double
getSunRiseSetUTC
(Calendar calendar, double latitude, double longitude, double zenith, NOAACalculator.SolarEvent solarEvent) Return the Universal Coordinated Time (UTC) of sunrise or sunset in minutes for the given day at the given location on earth.private static double
getSunTrueLongitude
(double julianCenturies) Return the true longitude of the sun.double
getUTCMidnight
(Calendar calendar, GeoLocation geoLocation) Return the Universal Coordinated Time (UTC) of the solar midnight for the end of the given civil day at the given location on earth (about 12 hours after solar noon).double
getUTCNoon
(Calendar calendar, GeoLocation geoLocation) Return the Universal Coordinated Time (UTC) of solar noon for the given day at the given location on earth.double
getUTCSunrise
(Calendar calendar, GeoLocation geoLocation, double zenith, boolean adjustForElevation) A method that calculates UTC sunrise as well as any time based on an angle above or below sunrise.double
getUTCSunset
(Calendar calendar, GeoLocation geoLocation, double zenith, boolean adjustForElevation) A method that calculates UTC sunset as well as any time based on an angle above or below sunset.Methods inherited from class com.kosherjava.zmanim.util.AstronomicalCalculator
adjustZenith, clone, getDefault, getEarthRadius, getElevationAdjustment, getRefraction, getSolarRadius, setEarthRadius, setRefraction, setSolarRadius
-
Field Details
-
JULIAN_DAY_JAN_1_2000
The Julian day of January 1, 2000, known as J2000.0.- See Also:
-
JULIAN_DAYS_PER_CENTURY
-
-
Constructor Details
-
NOAACalculator
public NOAACalculator()Default constructor of the NOAACalculator.
-
-
Method Details
-
getCalculatorName
Description copied from class:AstronomicalCalculator
Returns the name of the algorithm.- Specified by:
getCalculatorName
in classAstronomicalCalculator
- Returns:
- the descriptive name of the algorithm.
- See Also:
-
getUTCSunrise
public double getUTCSunrise(Calendar calendar, GeoLocation geoLocation, double zenith, boolean adjustForElevation) Description copied from class:AstronomicalCalculator
A method that calculates UTC sunrise as well as any time based on an angle above or below sunrise. This abstract method is implemented by the classes that extend this class.- Specified by:
getUTCSunrise
in classAstronomicalCalculator
- Parameters:
calendar
- Used to calculate day of year.geoLocation
- The location information used for astronomical calculating sun times.zenith
- the azimuth below the vertical zenith of 90 degrees. for sunrise typically thezenith
used for the calculation uses geometric zenith of 90° andadjusts
this slightly to account for solar refraction and the sun's radius. Another example would beAstronomicalCalendar.getBeginNauticalTwilight()
that passesAstronomicalCalendar.NAUTICAL_ZENITH
to this method.adjustForElevation
- Should the time be adjusted for elevation- Returns:
- 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,
Double.NaN
will be returned. - See Also:
-
getUTCSunset
public double getUTCSunset(Calendar calendar, GeoLocation geoLocation, double zenith, boolean adjustForElevation) Description copied from class:AstronomicalCalculator
A method that calculates UTC sunset as well as any time based on an angle above or below sunset. This abstract method is implemented by the classes that extend this class.- Specified by:
getUTCSunset
in classAstronomicalCalculator
- Parameters:
calendar
- Used to calculate day of year.geoLocation
- The location information used for astronomical calculating sun times.zenith
- the azimuth below the vertical zenith of 90°. For sunset typically thezenith
used for the calculation uses geometric zenith of 90° andadjusts
this slightly to account for solar refraction and the sun's radius. Another example would beAstronomicalCalendar.getEndNauticalTwilight()
that passesAstronomicalCalendar.NAUTICAL_ZENITH
to this method.adjustForElevation
- Should the time be adjusted for elevation- Returns:
- 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,
Double.NaN
will be returned. - See Also:
-
getJulianDay
Return the Julian day from a Java Calendar.- Parameters:
calendar
- The Java Calendar- Returns:
- the Julian day corresponding to the date Note: Number is returned for start of day. Fractional days should be added later.
-
getJulianCenturiesFromJulianDay
Convert Julian day to centuries since J2000.0.- Parameters:
julianDay
- the Julian Day to convert- Returns:
- the centuries since 2000 Julian corresponding to the Julian Day
-
getSunGeometricMeanLongitude
Returns the Geometric Mean Longitude of the Sun.- Parameters:
julianCenturies
- the number of Julian centuries since J2000.0.- Returns:
- the Geometric Mean Longitude of the Sun in degrees
-
getSunGeometricMeanAnomaly
Returns the Geometric Mean Anomaly of the Sun in degrees.- Parameters:
julianCenturies
- the number of Julian centuries since J2000.0.- Returns:
- the Geometric Mean Anomaly of the Sun in degrees
-
getEarthOrbitEccentricity
Return the unitless eccentricity of earth's orbit.- Parameters:
julianCenturies
- the number of Julian centuries since J2000.0.- Returns:
- the unitless eccentricity
-
getSunEquationOfCenter
Returns the equation of center for the sun in degrees.- Parameters:
julianCenturies
- the number of Julian centuries since J2000.0.- Returns:
- the equation of center for the sun in degrees
-
getSunTrueLongitude
Return the true longitude of the sun.- Parameters:
julianCenturies
- the number of Julian centuries since J2000.0.- Returns:
- the sun's true longitude in degrees
-
getSunApparentLongitude
Return the apparent longitude of the sun.- Parameters:
julianCenturies
- the number of Julian centuries since J2000.0.- Returns:
- sun's apparent longitude in degrees
-
getMeanObliquityOfEcliptic
Returns the mean obliquity of the ecliptic (Axial tilt).- Parameters:
julianCenturies
- the number of Julian centuries since J2000.0.- Returns:
- the mean obliquity in degrees
-
getObliquityCorrection
Returns the corrected obliquity of the ecliptic (Axial tilt).- Parameters:
julianCenturies
- the number of Julian centuries since J2000.0.- Returns:
- the corrected obliquity in degrees
-
getSunDeclination
Return the declination of the sun.- Parameters:
julianCenturies
- the number of Julian centuries since J2000.0.- Returns:
- the sun's declination in degrees
-
getEquationOfTime
Return the Equation of Time - the difference between true solar time and mean solar time- Parameters:
julianCenturies
- the number of Julian centuries since J2000.0.- Returns:
- equation of time in minutes of time
-
getSunHourAngle
private static double getSunHourAngle(double latitude, double solarDeclination, double zenith, NOAACalculator.SolarEvent solarEvent) Return the hour angle of the sun in radians at for the latitude. -
getSolarElevation
Return 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.- Parameters:
calendar
- time of calculationlatitude
- latitude of location for calculationlongitude
- longitude of location for calculation- Returns:
- solar elevation in degrees - horizon is 0 degrees, civil twilight is -6 degrees
-
getSolarAzimuth
Return 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.- Parameters:
calendar
- time of calculationlatitude
- latitude of location for calculationlongitude
- longitude of location for calculation- Returns:
- the solar azimuth
-
getUTCNoon
Return the Universal Coordinated Time (UTC) of solar noon for the given day at the given location on earth. This implementation returns true solar noon as opposed to the time halfway between sunrise and sunset. Other calculators may return a more simplified calculation of halfway between sunrise and sunset. See The Definition of Chatzos for details on solar noon calculations.- Specified by:
getUTCNoon
in classAstronomicalCalculator
- Parameters:
calendar
- The Calendar representing the date to calculate solar noon forgeoLocation
- The location information used for astronomical calculating sun times. This class uses only requires the longitude for calculating noon since it is the same time anywhere along the longitude line.- Returns:
- the time in minutes from zero UTC
- See Also:
-
getUTCMidnight
Return the Universal Coordinated Time (UTC) of the solar midnight for the end of the given civil day at the given location on earth (about 12 hours after solar noon). This implementation returns true solar midnight as opposed to the time halfway between sunrise and sunset. Other calculators may return a more simplified calculation of halfway between sunrise and sunset. See The Definition of Chatzos for details on solar noon / midnight calculations.- Specified by:
getUTCMidnight
in classAstronomicalCalculator
- Parameters:
calendar
- The Calendar representing the date to calculate solar noon forgeoLocation
- The location information used for astronomical calculating sun times. This class uses only requires the longitude for calculating noon since it is the same time anywhere along the longitude line.- Returns:
- the time in minutes from zero UTC
- See Also:
-
getSolarNoonMidnightUTC
private static double getSolarNoonMidnightUTC(double julianDay, double longitude, NOAACalculator.SolarEvent solarEvent) Return the Universal Coordinated Time (UTC) of the current day solar noon or the the upcoming midnight (about 12 hours after solar noon) of the given day at the given location on earth. -
getSunRiseSetUTC
private static double getSunRiseSetUTC(Calendar calendar, double latitude, double longitude, double zenith, NOAACalculator.SolarEvent solarEvent) Return the Universal Coordinated Time (UTC) of sunrise or sunset in minutes for the given day at the given location on earth.- Parameters:
calendar
- The calendarlatitude
- The latitude of observer in degreeslongitude
- Longitude of observer in degreeszenith
- ZenithsolarEvent
- If the calculation is forSUNRISE
orSUNSET
- Returns:
- the time in minutes from zero Universal Coordinated Time (UTC)
- TODO:
- Possibly increase the number of passes for improved accuracy, especially in the Arctic areas.
-