Class SPACalculator
- All Implemented Interfaces:
Cloneable
Refraction is fully configurable through the parent AstronomicalCalculator. Many SPA ports hardcode their
refraction model (and even their solar radius); this one does not:
- Sunrise / sunset (the geometric 90° zenith only). The horizon geometry is taken entirely from the parent's
AstronomicalCalculator.adjustZenith(double, double, LocalDate):AstronomicalCalculator.getRefraction()/AstronomicalCalculator.setRefraction(double)(default 0.5667° / 34′); the solar radius - the date-basedAstronomicalCalculator.getApparentSolarRadius(LocalDate)by default (it varies slightly day to day), or the fixedAstronomicalCalculator.getSolarRadius()(default 0.26667° / 16′) whenAstronomicalCalculator.isUseApparentSolarRadius()isfalse; and theelevation dip. SPA's own atmospheric refraction is not applied on this path - the calculator solves for the geometric (parallax-included, un-refracted) center of the Sun reaching the parent-supplied zenith, exactly asNOAACalculatorandMeeusCalculatordo. The parent only adds these corrections when the zenith is exactly 90°, soAstronomicalCalculator.setRefraction(double)andAstronomicalCalculator.setSolarRadius(double)change sunrise / sunset (and any 90°-based time) and nothing else. - Twilight and depression-angle zmanim (e.g. alos / tzais at 16.1°, 19.8°). These pass a zenith
other than 90°, so
AstronomicalCalculator.adjustZenith(double, double, LocalDate)adds nothing: no refraction, no solar radius. The time is solved for the Sun's true geometric depression, as such zmanim are defined. None ofAstronomicalCalculator.setRefraction(double),AstronomicalCalculator.setSolarRadius(double),setPressure(double)orsetTemperature(double)affect them. - Instantaneous
elevation/azimuthonly. Here the full SPA (Reda-Andreas / Sæmundsson) atmospheric-refraction model is used, with its horizon parameter taken from the parent'sAstronomicalCalculator.getRefraction()and thepressureandtemperaturesettable. These two settings affect this path and only this path - they have no effect on sunrise, sunset, twilight or any depression-angle zman. (Note that within the KosherJava calendar nothing callsgetSolarElevation(Instant, GeoLocation)/#getSolarAzimuth(Instant, GeoLocation); they are direct-query methods, so in normal calendar use the pressure and temperature settings are inert.)
ΔT (TT − UT) is integral to SPA and is applied here. It defaults to an Espenak-Meeus estimate but can be overridden
exactly via setDeltaTOverride(Double) (the published SPA test case fixes ΔT = 67 seconds), or disabled via setApplyDeltaT(boolean).
Topocentric note. Unlike NOAACalculator.getSolarElevation(Instant, GeoLocation) (sea-level, altitude-independent),
this calculator's elevation / azimuth are genuinely topocentric: the observer's elevation feeds
the parallax term. The adjustForElevation flag on sunrise / sunset continues to control only the geometric horizon
dip via the parent.
Coefficient coverage. The VSOP87 Earth tables are the abridged Appendix III set (validated to about 0.1′ against Meeus's worked example), and the nutation uses the principal terms. These give a few arc-seconds of accuracy - vastly beyond any zmanim requirements. For the full published SPA ±0.0003° envelope, the VSOP87 tables and the IAU 1980 nutation series can be extended without changing the algorithm.
- Author:
- © Eliyahu Hershfeld 2026; NREL SPA (Reda and Andreas) port
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate static final classThe bracketing crossing search of solarpositioning 3.0 (SolarEvents.CrossingSearch), unchanged.private static final classThe part of a rise / set solution that does not depend on the zenith: the declination and the equation of time at solar noon.private static final classThe exact series values atINTERPOLATION_NODESevenly spaced times across one day (TT), used to interpolate the series within that day.protected static enum -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate booleanWhether to apply the ΔT (TT−UT) correction.private DoubleAn explicit ΔT (seconds) override;nullmeans estimate it from the date.private static final double[][][]Earth heliocentric latitude series B0..B1.private static final double[][][]Earth heliocentric longitude series L0..L5.private static final double[][][]Earth radius-vector series R0..R4 (AU).private static final doubleMinimum rate, in degrees per minute, at which the Sun must cross the zenith along the whole secant search for its result to be used.private static final doubleMinimum rate (degrees per minute) at which the sun must cross the zenith along the whole search for an interpolated result to be used.private static final doubleMaximum time error (minutes) of an interpolated result, checked with one exact evaluation: 0.5 ms.private static final intInterpolation nodes per one day (TT) window: 5 nodes, so quartic interpolation.private static final intNumber of day windows kept.private static final doubleThe Julian day of J2000.0.private static final doubleJulian days per century.private SPACalculator.NoonSolutionThe lastSPACalculator.NoonSolutioncalculated.private static final doubleLargest distance in degrees between the requested zenith and the Sun's zenith at an accepted secant result.private static final double[][]Polynomial coefficients of the nutation arguments X0 - X4 (Reda & Andreas, equations 15 - 19).private doubleAnnual average local pressure in millibars, used by the SPA refraction model.private static final doubleAllowance for Julian date quantisation and floating point evaluation (as solarpositioning).private SPACalculator.SeriesWindow[]The most recently used day windows, newest first, at mostINTERPOLATION_WINDOWS.private doubleAnnual average local temperature in °C, used by the SPA refraction model.private static final double[][]The a, b, c, d coefficients of Δψ and Δε for each of the 63 nutation terms (Reda & Andreas, Table A4.3).private static final double[][]Multipliers of X0 - X4 for each of the 63 nutation terms (Reda & Andreas, Table A4.3).private static final doubleBracket resolution of the search: one millisecond, in hours (as solarpositioning). -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionprivate doublebracketRiseSet(double jdDay, double latitude, double longitude, double elevation, double adjustedZenith, SPACalculator.SolarEvent solarEvent) Finds the first rise (or set) crossing of the adjusted zenith inside this date's window (seegetRiseSetWindowMinutes(double, SolarEvent)) with the bracketing search of Klaus Brunner's solarpositioning library 3.0 (SolarEvents): the interval is split until a bracket with a guaranteed sign change is found, then refined with ITP to one millisecond, keeping the later endpoint.booleanprivate doubleequationOfTime(double julianDayUT) The equation of time (apparent minus mean solar time) in minutes of time (Meeus chapter 28), built from the SPA geocentric apparent right ascension.private static doubleestimateDeltaT(double julianDay) ΔT (TT - UT) estimate in seconds for a Julian day, as solarpositioning'sDeltaT.estimate(LocalDate): the Espenak & Meeus polynomials with its post-2005 extrapolation, evaluated at the decimal year of the date's month.private static doubleestimateDeltaTForYear(double year) Estimates ΔT for a decimal year, using the same branches and coefficients as solarpositioning 3.0.private static double[]exactSeries(double jme, double jce) The exact VSOP87 Earth series (heliocentric longitude and latitude in degrees, radius vector in AU) and nutation (Δψ, Δε in degrees).Returns the name of the algorithm.Return the explicit ΔT (TT - UT) override in seconds, ornullif ΔT is being estimated from the date (the default).private double[]getInterpolatedSeries(double jde) Returns the series values at a time, interpolated (Lagrange, through all nodes) within its one day window.private static doublegetJulianDay(LocalDate localDate) Return the Julian day from a JavaLocalDate.private SPACalculator.NoonSolutiongetNoonSolution(double jdDay, double lonWest) Returns the noon solution for the day and longitude, reusing the last one when every input matches.doubleReturn the pressure in millibars used by the refraction model.private static double[]getRiseSetWindowMinutes(double longitude, SPACalculator.SolarEvent solarEvent) The window, in minutes from 0h UT of the date, in which a rise or set belongs to the date.doublegetSolarAzimuth(Instant instant, GeoLocation geoLocation) Return the Solar Azimuth for the horizontal coordinate system at the given location at the given time.doublegetSolarElevation(Instant instant, GeoLocation geoLocation) Return the Solar Elevation for the horizontal coordinate system at the given location at the given time.doubleReturns the temperature in °C used by the refraction model.doublegetTimeAtAzimuth(LocalDate localDate, GeoLocation geoLocation, double targetAzimuth) Returns the time that the azimuth will occur for the date and location passed to this method.doublegetUTCMidnight(LocalDate localDate, GeoLocation geoLocation) Return the Universal Coordinated Time (UTC) of solar midnight (UTC) for the given day at the given location.doublegetUTCNoon(LocalDate localDate, GeoLocation geoLocation) Return the Universal Coordinated Time (UTC) of solar noon (UTC) for the given day at the given location.doublegetUTCSunrise(LocalDate dt, 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.private doublegetUTCSunRiseSet(LocalDate localDate, GeoLocation geoLocation, double zenith, boolean adjustForElevation, SPACalculator.SolarEvent solarEvent) Calculate UTC sunrise or sunset (or any twilight angle) in 24-hour format.doublegetUTCSunset(LocalDate dt, 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.inthashCode()booleanReturns whether the ΔT correction is being applied.private booleanisInterpolatedSolutionAcceptable(double t, double[] stats, double jdDay, double lat, double longitude, double elevation, double adjustedZenith) Verifies a rise / set time found with the interpolated solar coordinates.protected booleanWhether this calculator's results depend only on the method arguments and on settings whose setters callAstronomicalCalculator.clearResultCache(), so they can be cached.private static doublejulianDayFromInstant(Instant instant) Julian day (including fractional day) for anInstantin UTC.private static doublemeanObliquity(double jme) The mean obliquity of the ecliptic in degrees (SPA / Meeus 22.2 polynomial in U = JME/10).private static double[]nutation(double jce) Nutation in longitude and obliquity, using the full 63-term SPA series (Reda & Andreas, Table A4.3) as implemented in Klaus Brunner's solarpositioning library (same operations, including fused multiply-add).private static doublepolynomial(double x, double... coeffs) Polynomial with coefficients in ascending order, evaluated with fused multiply-add (as solarpositioning's MathUtil).private doublerefractionCorrection(double trueElevation) The SPA atmospheric-refraction correction (Reda and Andreas) in degrees.private doublesecant(double jdDay, double lat, double longitude, double elevation, double adjustedZenith, double guess, boolean interpolate, double[] stats) The secant search for the time (minutes from 0h UT) at which the topocentric true zenith equals the adjusted zenith.voidsetApplyDeltaT(boolean applyDeltaT) Sets to apply ΔTtrue(default), orfalseto omit it (UT = TT).voidsetDeltaTOverride(Double deltaTSeconds) Override the estimated ΔT with an explicit value in seconds (for example 67 seconds for the published SPA test case), ornullto revert to the date-based estimate.voidsetPressure(double pressureMillibars) Set the annual average local pressure used by the SPA atmospheric-refraction model.voidsetTemperature(double temperatureCelsius) Set the annual average local temperature used by the SPA atmospheric-refraction model.private double[]solarCoords(double julianDayUT) Compute the Sun's geocentric apparent coordinates and the apparent sidereal time for the given UT Julian day.private double[]solarCoords(double julianDayUT, boolean interpolate) Solar coordinates, optionally with the VSOP87 series and nutation taken from the per-day interpolation (seegetInterpolatedSeries(double)).private doublesolveNoonMidnight(double julianDay, double lonWest, SPACalculator.SolarEvent solarEvent) Solar transit (noon) or anti-transit (midnight) in UTC minutes after 0:00, using the high-accuracy SPA equation of time.private doublesolveRiseSet(LocalDate localDate, GeoLocation geoLocation, double adjustedZenith, SPACalculator.SolarEvent solarEvent) Solve for the UTC time, in minutes after 0:00, at which the topocentric (parallax-corrected, un-refracted) center of the Sun reachesadjustedZenith.private static doublesumSeries(double[][][] series, double tau) Evaluate a VSOP87 series Σn (Σi Ai·cos(Bi + Ci·τ)) · τn with coefficients in 1e-8 of the native unit (radians or AU).private double[]topocentric(double julianDayUT, double latitude, double longitude, double elevationMeters) Full SPA topocentric reduction (observer parallax + atmospheric refraction).private double[]topocentric(double julianDayUT, double latitude, double longitude, double elevationMeters, boolean interpolate) Astopocentric(double, double, double, double), optionally using the interpolated series values.private doubletopocentricTrueZenith(double julianDayUT, double latitude, double longitude, double elevationMeters) Topocentric true (un-refracted) zenith of the Sun's center, used by the rise/set solver so that refraction is supplied solely by the parentadjustZenith.private doubletopocentricTrueZenith(double julianDayUT, double latitude, double longitude, double elevationMeters, boolean interpolate) AstopocentricTrueZenith(double, double, double, double), optionally using the interpolated series values.Methods inherited from class AstronomicalCalculator
acosDegrees, adjustZenith, asinDegrees, clearResultCache, clone, cosDegrees, getApparentSolarRadius, getCachedUTCMidnight, getCachedUTCNoon, getCachedUTCSunrise, getCachedUTCSunset, getDefault, getEarthRadius, getElevationAdjustment, getRefraction, getSolarRadius, isUseApparentSolarRadius, isUseResultCache, setEarthRadius, setRefraction, setSolarRadius, setUseApparentSolarRadius, setUseResultCache, sinDegrees, tanDegreesModifier and TypeMethodDescriptionprotected static doubleacosDegrees(double angle) A helper method to retun the arc cosine in degrees.(package private) doubleadjustZenith(double zenith, double elevation, LocalDate localDate) Adjusts the zenith of astronomical sunrise and sunset to account for solar refraction, solar radius and elevation.protected static doubleasinDegrees(double angle) A helper method to retun the arc sine in degrees.protected voidDiscards all cached results.clone()protected static doublecosDegrees(double angle) A helper method to retun the cosine in degrees.doublegetApparentSolarRadius(LocalDate localDate) Returns the Sun's apparent angular semi-diameter (the "solar radius") for the given date, in degrees.final doublegetCachedUTCMidnight(LocalDate localDate, GeoLocation geoLocation) AstronomicalCalculator.getUTCMidnight(LocalDate, GeoLocation)with result caching (seeAstronomicalCalculator.isUseResultCache()).final doublegetCachedUTCNoon(LocalDate localDate, GeoLocation geoLocation) AstronomicalCalculator.getUTCNoon(LocalDate, GeoLocation)with result caching (seeAstronomicalCalculator.isUseResultCache()).final doublegetCachedUTCSunrise(LocalDate localDate, GeoLocation geoLocation, double zenith, boolean adjustForElevation) final doublegetCachedUTCSunset(LocalDate localDate, GeoLocation geoLocation, double zenith, boolean adjustForElevation) static AstronomicalCalculatorReturns the default class for calculating sunrise and sunset.doubleA method that returns the earth radius in KM.(package private) doublegetElevationAdjustment(double elevation) Method to return the adjustment to the zenith required to account for the elevation.doubleMethod to get the refraction value to be used when calculating sunrise and sunset.doubleMethod to get the fixed sun's radius.booleanReturns if useApparentSolarRadius is true (the default) or false.booleanWhether rise / set / noon / midnight results are cached (when the calculator supports it, seeAstronomicalCalculator.isResultCacheable()).voidsetEarthRadius(double earthRadius) A method that allows setting the earth's radius.voidsetRefraction(double refraction) A method to allow overriding the default refraction of the calculator.voidsetSolarRadius(double solarRadius) Sets the Sun's radius as a fixed, date-independent value in degrees, for example16.0 / 60.0for the conventional 16′.voidsetUseApparentSolarRadius(boolean useApparentSolarRadius) Sets if useApparentSolarRadius should be true (the default) or false.voidsetUseResultCache(boolean useResultCache) Sets whether rise / set / noon / midnight results are cached.protected static doublesinDegrees(double angle) A helper method to retun the sine in degrees.protected static doubletanDegrees(double angle) A helper method to retun the tan / tangent in degrees.
-
Field Details
-
JULIAN_DAY_JAN_1_2000
-
JULIAN_DAYS_PER_CENTURY
-
applyDeltaT
Whether to apply the ΔT (TT−UT) correction. Defaults totrue. -
deltaTOverride
An explicit ΔT (seconds) override;nullmeans estimate it from the date. -
pressure
Annual average local pressure in millibars, used by the SPA refraction model. Default 1013.25. -
temperature
Annual average local temperature in °C, used by the SPA refraction model. Default 10. -
lastNoonSolution
The lastSPACalculator.NoonSolutioncalculated. A single entry (callers almost always move one day at a time), so memory use is fixed and nothing accumulates. Swapped atomically as one immutable object, so concurrent callers at most recalculate, and can never see a partial or mismatched entry. Not part ofequals(Object)orhashCode(). -
INTERPOLATION_NODES
Interpolation nodes per one day (TT) window: 5 nodes, so quartic interpolation.- See Also:
-
INTERPOLATION_WINDOWS
Number of day windows kept. A day's zmanim span at most two or three UT/TT days, so 4 avoids thrashing.- See Also:
-
GUARD_MIN_SLOPE
Minimum rate (degrees per minute) at which the sun must cross the zenith along the whole search for an interpolated result to be used.- See Also:
-
GUARD_TOLERANCE_MINUTES
Maximum time error (minutes) of an interpolated result, checked with one exact evaluation: 0.5 ms.- See Also:
-
seriesWindows
The most recently used day windows, newest first, at mostINTERPOLATION_WINDOWS. The array is never modified after it is published: a new window is added by publishing a new array, so concurrent callers can not see a partial state (at most one window is computed twice). Fixed memory. Not part ofequals(Object)orhashCode(). -
MAX_ZENITH_RESIDUAL
Largest distance in degrees between the requested zenith and the Sun's zenith at an accepted secant result. Converged results end within about 1e-7° to 8e-7° (the time resolution of a Julian date held in a double), failed ones far away; 1e-4° is well above the first and below SPA's stated ±0.0003° accuracy.- See Also:
-
GRAZING_MIN_SLOPE
Minimum rate, in degrees per minute, at which the Sun must cross the zenith along the whole secant search for its result to be used. Ordinary crossings are about 0.1 - 0.25°/min; below this the day is near grazing and the bracketing search is used.- See Also:
-
TIME_TOLERANCE
Bracket resolution of the search: one millisecond, in hours (as solarpositioning).- See Also:
-
ROUNDING_ERROR
Allowance for Julian date quantisation and floating point evaluation (as solarpositioning).- See Also:
-
NUTATION_COEFFS
Polynomial coefficients of the nutation arguments X0 - X4 (Reda & Andreas, equations 15 - 19). -
TERMS_Y
Multipliers of X0 - X4 for each of the 63 nutation terms (Reda & Andreas, Table A4.3). -
TERMS_PE
The a, b, c, d coefficients of Δψ and Δε for each of the 63 nutation terms (Reda & Andreas, Table A4.3). -
EARTH_L
Earth heliocentric longitude series L0..L5. -
EARTH_B
Earth heliocentric latitude series B0..B1. -
EARTH_R
Earth radius-vector series R0..R4 (AU).
-
-
Constructor Details
-
SPACalculator
public SPACalculator()Default constructor of the SPACalculator.
-
-
Method Details
-
isResultCacheable
Whether this calculator's results depend only on the method arguments and on settings whose setters callAstronomicalCalculator.clearResultCache(), so they can be cached. Defaults tofalse, so a calculator written without the cache in mind is never cached. A subclass that returnstruemust callAstronomicalCalculator.clearResultCache()from every setter that can change a rise, set, noon or midnight result. This calculator's results depend only on the arguments and on settings whose setters clear the cache.- Overrides:
isResultCacheablein classAstronomicalCalculator- Returns:
- whether results may be cached
-
getNoonSolution
Returns the noon solution for the day and longitude, reusing the last one when every input matches.- Parameters:
jdDay- the Julian daylonWest- the longitude, positive west- Returns:
- the noon solution
-
getCalculatorName
Description copied from class:AstronomicalCalculatorReturns the name of the algorithm.- Specified by:
getCalculatorNamein classAstronomicalCalculator- Returns:
- the descriptive name of the algorithm.
-
setApplyDeltaT
Sets to apply ΔTtrue(default), orfalseto omit it (UT = TT).- Parameters:
applyDeltaT-true(default) to apply ΔT,falseto omit it (UT = TT).- See Also:
-
isApplyDeltaT
Returns whether the ΔT correction is being applied. @see #setApplyDeltaT(boolean).- Returns:
- whether the ΔT correction is being applied. @see #setApplyDeltaT(boolean)
-
setDeltaTOverride
Override the estimated ΔT with an explicit value in seconds (for example 67 seconds for the published SPA test case), ornullto revert to the date-based estimate.- Parameters:
deltaTSeconds- ΔT in seconds, ornullto estimate.
-
getDeltaTOverride
Return the explicit ΔT (TT - UT) override in seconds, ornullif ΔT is being estimated from the date (the default). Note that this returns the override setting, not the estimated value in use.- Returns:
- the explicit ΔT override in seconds, or
nullif it is being estimated from the date. - See Also:
-
setPressure
Set the annual average local pressure used by the SPA atmospheric-refraction model. This affects onlygetSolarElevation(Instant, GeoLocation)andgetSolarAzimuth(Instant, GeoLocation); it has no effect on sunrise, sunset, twilight or any depression-angle zman, whose refraction (if any) comes from the parent's fixedAstronomicalCalculator.getRefraction(). See the class documentation.- Parameters:
pressureMillibars- the pressure in millibars (hPa).
-
getPressure
Return the pressure in millibars used by the refraction model.- Returns:
- the pressure in millibars used by the refraction model.
-
setTemperature
Set the annual average local temperature used by the SPA atmospheric-refraction model. This affects onlygetSolarElevation(Instant, GeoLocation)andgetSolarAzimuth(Instant, GeoLocation); it has no effect on sunrise, sunset, twilight or any depression-angle zman, whose refraction (if any) comes from the parent's fixedAstronomicalCalculator.getRefraction(). See the class documentation.- Parameters:
temperatureCelsius- the temperature in degrees Celsius.
-
getTemperature
Returns the temperature in °C used by the refraction model.- Returns:
- the temperature in °C used by the refraction model.
-
getUTCSunrise
public double getUTCSunrise(LocalDate dt, GeoLocation geoLocation, double zenith, boolean adjustForElevation) Description copied from class:AstronomicalCalculatorA 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:
getUTCSunrisein classAstronomicalCalculator- Parameters:
dt- TheLocalDaterepresenting the date to calculate sunrise for.geoLocation- The location information used for astronomical calculation of solar times.zenith- the azimuth below the vertical zenith of 90°. For sunrise typically thezenithused for the calculation uses geometric zenith of 90° andadjuststhis slightly to account for solar refraction and the sun's radius. Another example would beAstronomicalCalendar.getBeginNauticalTwilight()that passesAstronomicalCalendar.NAUTICAL_ZENITHto 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. If an error was encountered in the
calculation (expected behavior for some locations such as near the poles,
Double.NaNwill be returned. - See Also:
-
getUTCSunset
public double getUTCSunset(LocalDate dt, GeoLocation geoLocation, double zenith, boolean adjustForElevation) Description copied from class:AstronomicalCalculatorA 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:
getUTCSunsetin classAstronomicalCalculator- Parameters:
dt- TheLocalDate> representing the date to calculate sunset for.geoLocation- The location information used for astronomical calculation of solar times.zenith- the azimuth below the vertical zenith of 90°. For sunset typically the zenith used for the calculation uses geometric zenith of 90° andadjuststhis slightly to account for solar refraction and the sun's radius. Another example would beAstronomicalCalendar.getEndNauticalTwilight()that passesAstronomicalCalendar.NAUTICAL_ZENITHto 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. If an error was encountered in the
calculation (expected behavior for some locations such as near the poles,
Double.NaNwill be returned. - See Also:
-
getUTCSunRiseSet
private double getUTCSunRiseSet(LocalDate localDate, GeoLocation geoLocation, double zenith, boolean adjustForElevation, SPACalculator.SolarEvent solarEvent) Calculate UTC sunrise or sunset (or any twilight angle) in 24-hour format. The horizon geometry (refraction, the sun's radius and the elevation dip) is supplied entirely by the parentAstronomicalCalculator.adjustZenith(double, double, LocalDate), so the SPA topocentric solution is solved for the un-refracted, parallax-corrected center of the Sun reaching that zenith.- Parameters:
localDate- the date.geoLocation- the observer location.zenith- the (un-adjusted) zenith;adjustedby the parent before use.adjustForElevation- whether to include the geometric elevation dip.solarEvent-SPACalculator.SolarEvent.SUNRISEorSPACalculator.SolarEvent.SUNSET.- Returns:
- the UTC time in hours, or
Double.NaNif the event does not occur (polar day / night).
-
solveRiseSet
private double solveRiseSet(LocalDate localDate, GeoLocation geoLocation, double adjustedZenith, SPACalculator.SolarEvent solarEvent) Solve for the UTC time, in minutes after 0:00, at which the topocentric (parallax-corrected, un-refracted) center of the Sun reachesadjustedZenith. A first guess is taken from the closed-form hour-angle equation (geocentric declination at local noon), then refined by a secant iteration on the full SPA topocentric zenith.- Parameters:
localDate- the date.geoLocation- the observer location.adjustedZenith- the target zenith (already including refraction / radius / dip from the parent).solarEvent-SPACalculator.SolarEvent.SUNRISEorSPACalculator.SolarEvent.SUNSET.- Returns:
- UTC minutes after 0:00, or
Double.NaNif the event does not occur.
-
isInterpolatedSolutionAcceptable
private boolean isInterpolatedSolutionAcceptable(double t, double[] stats, double jdDay, double lat, double longitude, double elevation, double adjustedZenith) Verifies a rise / set time found with the interpolated solar coordinates. It is accepted only if the search was well conditioned all along its path (the sun crossed the zenith at no less thanGUARD_MIN_SLOPE), so it converged to the same crossing the exact solve would, and if the exact zenith at that time is withinGUARD_TOLERANCE_MINUTESof the target. Otherwise the caller repeats the solve exactly.- Parameters:
t- the time found, in minutes from 0h UT of the datestats- the path statistics fromsecant(double, double, double, double, double, double, boolean, double[]): {minimum |slope|, last slope}, in degrees per minutejdDay- the Julian day (0h UT) of the datelat- the latitude in degreeslongitude- the longitude in degreeselevation- the elevation in metersadjustedZenith- the target zenith in degrees- Returns:
- true if the interpolated solution can be used, false if the solve must be repeated exactly
-
secant
private double secant(double jdDay, double lat, double longitude, double elevation, double adjustedZenith, double guess, boolean interpolate, double[] stats) The secant search for the time (minutes from 0h UT) at which the topocentric true zenith equals the adjusted zenith. With interpolate false this is exactly the original algorithm.- Parameters:
jdDay- the Julian day (0h UT) of the datelat- the latitude in degreeslongitude- the longitude in degreeselevation- the elevation in metersadjustedZenith- the target zenith in degreesguess- the starting guess, in minutes from 0h UTinterpolate- whether to use the interpolated series valuesstats- if not null, receives {minimum |slope| along the path (0 if not converged), last slope}, slopes in degrees per minute- Returns:
- the time in minutes from 0h UT of the date (not checked for convergence; see the callers)
-
exactSeries
The exact VSOP87 Earth series (heliocentric longitude and latitude in degrees, radius vector in AU) and nutation (Δψ, Δε in degrees).- Parameters:
jme- the Julian ephemeris millenniumjce- the Julian ephemeris century- Returns:
- {L, B, R, Δψ, Δε}
-
getInterpolatedSeries
Returns the series values at a time, interpolated (Lagrange, through all nodes) within its one day window.- Parameters:
jde- the Julian ephemeris day (TT)- Returns:
- {L, B, R, Δψ, Δε} as
exactSeries(double, double)
-
getRiseSetWindowMinutes
private static double[] getRiseSetWindowMinutes(double longitude, SPACalculator.SolarEvent solarEvent) The window, in minutes from 0h UT of the date, in which a rise or set belongs to the date. These are exactly the windowsAstronomicalCalendaruses when it converts the 0 - 24 hour result back to an instant (by local mean time: a rise after 18:00 belongs to the previous date, a set before 06:00 to the next), so a result found here always maps back to the right instant. Rises: (18:00 local mean time the evening before, 18:00]; sets: [06:00, 06:00 the next morning).- Parameters:
longitude- the longitude in degrees, positive eastsolarEvent-SPACalculator.SolarEvent.SUNRISEorSPACalculator.SolarEvent.SUNSET- Returns:
- {start, end} in minutes from 0h UT of the date
-
bracketRiseSet
private double bracketRiseSet(double jdDay, double latitude, double longitude, double elevation, double adjustedZenith, SPACalculator.SolarEvent solarEvent) Finds the first rise (or set) crossing of the adjusted zenith inside this date's window (seegetRiseSetWindowMinutes(double, SolarEvent)) with the bracketing search of Klaus Brunner's solarpositioning library 3.0 (SolarEvents): the interval is split until a bracket with a guaranteed sign change is found, then refined with ITP to one millisecond, keeping the later endpoint. A tangency is not a crossing. Returns NaN when no crossing exists in the window.- Parameters:
jdDay- the Julian day (0h UT) of the datelatitude- the latitude in degreeslongitude- the longitude in degreeselevation- the elevation in metersadjustedZenith- the target zenith in degreessolarEvent- sunrise or sunset- Returns:
- minutes from 0h UT of the date, or NaN
-
getUTCNoon
Return the Universal Coordinated Time (UTC) of solar noon (UTC) for the given day at the given location. TheNOAACalculator, the default calculator implementation calculates true solar noon, something that can be calculated even in the Arctic / Antarctic where there may be no sunrise or sunset, while theSunTimesCalculatorapproximates it, calculating the time as halfway between sunrise and sunset, something that can't be calculated in Polar regions where there is no sunrise or sunset for part of the year. See The Definition of Chatzos for details on solar noon / midnight calculations.- Specified by:
getUTCNoonin classAstronomicalCalculator- Parameters:
localDate- TheLocalDaterepresenting the date to calculate noon for.geoLocation- The location information used for astronomical calculation of solar times.- Returns:
- The UTC time of solar noon in 24-hour format. 1:45:00 PM will return 13.75. If an error was encountered in the
the calculation (expected behavior for some locations such as near the poles,
Double.NaNwill be returned. - See Also:
-
getUTCMidnight
Return the Universal Coordinated Time (UTC) of solar midnight (UTC) for the given day at the given location. TheNOAACalculator, the default calculator implementation calculates true solar midnight, something that can be calculated even in the Arctic / Antarctic where there may be no sunrise or sunset, while theSunTimesCalculatorapproximates it, calculating the time as 12 hours after halfway between sunrise and sunset, something that can't be calculated in Polar regions where there is no sunrise or sunset for part of the year. See The Definition of Chatzos for details on solar noon / midnight calculations.- Specified by:
getUTCMidnightin classAstronomicalCalculator- Parameters:
localDate- TheLocalDaterepresenting the date to calculate midnight for. The calculation will be for midnight at the end of the day passed in.geoLocation- The location information used for astronomical calculation of solar times.- Returns:
- The UTC time of solar midnight in a 24-hour
doubleformat. 1:45:00 AM will return 1.75. If an error was encountered in the calculation (expected behavior for theSunTimesCalculatorat times of the year in Polar regions),Double.NaNwill be returned. - See Also:
-
solveNoonMidnight
private double solveNoonMidnight(double julianDay, double lonWest, SPACalculator.SolarEvent solarEvent) Solar transit (noon) or anti-transit (midnight) in UTC minutes after 0:00, using the high-accuracy SPA equation of time. Parallax has a negligible (sub-second) effect on transit time, so the geocentric equation of time is used.- Parameters:
julianDay- the (UT) Julian day for 0:00.lonWest- the observer longitude in degrees, positive west.solarEvent-SPACalculator.SolarEvent.NOONorSPACalculator.SolarEvent.MIDNIGHT.- Returns:
- UTC minutes after 0:00.
-
getTimeAtAzimuth
Returns the time that the azimuth will occur for the date and location passed to this method. As an example, to know when the sun will be directly west, pass in an azimuth of 270°, and for directly east, pass in an azimuth of 90°. The current implementation in this class only supports azimuth values of 90° (directly east) or 270° (directly west) that are directly needed in this library for theComprehensiveZmanimCalendar.getPolarSunsetBenIshChai()andComprehensiveZmanimCalendar.getPolarSunriseBenIshChai().- Specified by:
getTimeAtAzimuthin classAstronomicalCalculator- Parameters:
localDate- TheLocalDaterepresenting the date to calculate the time of the azimuth for.geoLocation- The location information used for astronomical calculation of solar times.targetAzimuth- the azimuth to run the calculation for- Returns:
- The UTC time that the azimuth will be reached in a 24-hour
doubleformat. 5:45:00 PM will return 17.75. If an error was encountered in the calculation (expected behavior for some dates at latitudes below 23.44°, aDouble.NaNwill be returned. - Throws:
IllegalArgumentException- if the azimuth is not 90° or 270°.- TODO:
- complete the implementation for other azimuths. While not needed by this library, they may be of value to some projects. There will be edge cases where the azimuth will occur more than once a day when based on the equation of time, the day is shorter than 24 hours. In that case, the time for the first one will be returned.
-
getSolarElevation
Description copied from class:AstronomicalCalculatorReturn 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.- Specified by:
getSolarElevationin classAstronomicalCalculator- Parameters:
instant- Theinstantto calculate the elevation for.geoLocation- The location information used for astronomical calculation of solar times.- Returns:
- solar elevation in degrees. The horizon (calculated in a vacuum using the solar radius as the point)is 90°, civil twilight is 96° etc. This means that sunrise and sunset that do use refraction and are calculated from the upper limb of the sun will return about 0.8333°.
-
getSolarAzimuth
Description copied from class:AstronomicalCalculatorReturn the Solar Azimuth for the horizontal coordinate system at the given location at the given time. Not corrected for altitude. True south is 180°.- Specified by:
getSolarAzimuthin classAstronomicalCalculator- Parameters:
instant- Theinstantto calculate the azimuth for.geoLocation- The location information used for astronomical calculation of solar times.- Returns:
- the solar azimuth in degrees. Astronomical midday would be 180° in the northern hemisphere and 0° in the southern hemisphere. Depending on the location and time of year, sunrise will have an azimuth of about 90° and sunset about 270°.
-
solarCoords
Compute the Sun's geocentric apparent coordinates and the apparent sidereal time for the given UT Julian day.- Parameters:
julianDayUT- the UT Julian day (including fractional day).- Returns:
- {alpha (geocentric apparent RA, deg 0-360), delta (geocentric apparent declination, deg), epsilon (true obliquity, deg), nu (apparent Greenwich sidereal time, deg 0-360), radius (AU), lambda (apparent longitude, deg)}.
-
solarCoords
Solar coordinates, optionally with the VSOP87 series and nutation taken from the per-day interpolation (seegetInterpolatedSeries(double)). Only the first rise / set search uses interpolated values, and its result is always verified exactly (seeisInterpolatedSolutionAcceptable(double, double[], double, double, double, double, double)); everything else is exact.- Parameters:
julianDayUT- the Julian day (UT)interpolate- whether to use the interpolated series values- Returns:
- the same values as
solarCoords(double)
-
topocentric
private double[] topocentric(double julianDayUT, double latitude, double longitude, double elevationMeters) Full SPA topocentric reduction (observer parallax + atmospheric refraction).- Parameters:
julianDayUT- the UT Julian day.latitude- observer latitude in degrees.longitude- observer longitude in degrees, positive east.elevationMeters- observer elevation in meters.- Returns:
- {trueElevation (topocentric, no refraction, deg), observedElevation (refraction-corrected, deg), azimuth (eastward from north, deg 0-360)}.
-
topocentric
private double[] topocentric(double julianDayUT, double latitude, double longitude, double elevationMeters, boolean interpolate) Astopocentric(double, double, double, double), optionally using the interpolated series values.- Parameters:
julianDayUT- the Julian day (UT)latitude- the latitude in degreeslongitude- the longitude in degreeselevationMeters- the elevation in metersinterpolate- whether to use the interpolated series values- Returns:
- as
topocentric(double, double, double, double)
-
topocentricTrueZenith
private double topocentricTrueZenith(double julianDayUT, double latitude, double longitude, double elevationMeters) Topocentric true (un-refracted) zenith of the Sun's center, used by the rise/set solver so that refraction is supplied solely by the parentadjustZenith.- Parameters:
julianDayUT- the UT Julian day.latitude- observer latitude in degrees.longitude- observer longitude in degrees, positive east.elevationMeters- observer elevation in meters.- Returns:
- the topocentric true zenith in degrees.
-
topocentricTrueZenith
private double topocentricTrueZenith(double julianDayUT, double latitude, double longitude, double elevationMeters, boolean interpolate) AstopocentricTrueZenith(double, double, double, double), optionally using the interpolated series values.- Parameters:
julianDayUT- the Julian day (UT)latitude- the latitude in degreeslongitude- the longitude in degreeselevationMeters- the elevation in metersinterpolate- whether to use the interpolated series values- Returns:
- the topocentric zenith angle in degrees, without refraction
-
refractionCorrection
The SPA atmospheric-refraction correction (Reda and Andreas) in degrees. The horizon refraction parameter is the parent'sAstronomicalCalculator.getRefraction(), and thepressure/temperatureare settable, so the model is fully configurable rather than hardcoded.- Parameters:
trueElevation- the true (un-refracted) topocentric elevation in degrees.- Returns:
- the refraction correction in degrees to add to the true elevation.
-
equationOfTime
The equation of time (apparent minus mean solar time) in minutes of time (Meeus chapter 28), built from the SPA geocentric apparent right ascension. The sign matchesNOAACalculator.- Parameters:
julianDayUT- the UT Julian day.- Returns:
- the equation of time in minutes.
-
getJulianDay
Return the Julian day from a JavaLocalDate. Julian day for 0h UT of the date (Meeus chapter 7).- Parameters:
localDate- theLocalDateto get the Julian date for.- Returns:
- the Julian day corresponding to the date Note: Number is returned for the start of the Julian day. Fractional days / time should be added later.
-
julianDayFromInstant
Julian day (including fractional day) for anInstantin UTC.- Parameters:
instant- the day to calculate the Julian day for.- Returns:
- the Julian day as a
double
-
meanObliquity
The mean obliquity of the ecliptic in degrees (SPA / Meeus 22.2 polynomial in U = JME/10).- Parameters:
jme- Julian millennia of ephemeris time since J2000.0.- Returns:
- mean obliquity in degrees.
-
nutation
Nutation in longitude and obliquity, using the full 63-term SPA series (Reda & Andreas, Table A4.3) as implemented in Klaus Brunner's solarpositioning library (same operations, including fused multiply-add).- Parameters:
jce- Julian ephemeris century- Returns:
- {Δψ, Δε} in degrees
-
polynomial
Polynomial with coefficients in ascending order, evaluated with fused multiply-add (as solarpositioning's MathUtil).- Parameters:
x- the variablecoeffs- the coefficients, constant term first- Returns:
- the polynomial's value at x
-
estimateDeltaT
ΔT (TT - UT) estimate in seconds for a Julian day, as solarpositioning'sDeltaT.estimate(LocalDate): the Espenak & Meeus polynomials with its post-2005 extrapolation, evaluated at the decimal year of the date's month. Beyond the year 3000, where that library declines to estimate, its last branch is extrapolated.- Parameters:
julianDay- the Julian day (UT)- Returns:
- ΔT in seconds
-
estimateDeltaTForYear
Estimates ΔT for a decimal year, using the same branches and coefficients as solarpositioning 3.0.- Parameters:
year- the decimal year- Returns:
- ΔT in seconds
-
sumSeries
Evaluate a VSOP87 series Σn (Σi Ai·cos(Bi + Ci·τ)) · τn with coefficients in 1e-8 of the native unit (radians or AU).- Parameters:
series- indexed[n][term][{A,B,C}].tau- time in Julian millennia from J2000.0 (JME).- Returns:
- the evaluated quantity (radians or AU).
-
equals
Two
AstronomicalCalculatorinstances are considered equal if their Earth radius, refraction, and solar radius values are identical.Two
SPACalculatorinstances are considered equal if theirisApplyDeltaT(),getDeltaTOverride(),getPressure()andgetTemperature()values are identical.- Overrides:
equalsin classAstronomicalCalculator- Parameters:
object- the reference object with which to compare- Returns:
-
hashCode
This implementation hashes the earth radius, refraction, and solar radius properties to maintain the contract with
AstronomicalCalculator.equals(Object).This implementation hashes the
applyDeltaT,deltaTOverride,pressure, andtemperatureproperties to maintain the contract withequals(Object).- Overrides:
hashCodein classAstronomicalCalculator- Returns:
-