KosherJava Zmanim Homepage
Includes a dynamic Zmanim calendar generator

net.sourceforge.zmanim.util
Class AstronomicalCalculator

java.lang.Object
  extended bynet.sourceforge.zmanim.util.AstronomicalCalculator
Direct Known Subclasses:
JSuntimeCalculator, NOAACalculator, SunTimesCalculator, ZmanimCalculator

public abstract class AstronomicalCalculator
extends Object

An abstract class that all sun time calculating classes extend. This allows the algorithm used to be changed at runtime, easily allowing comparison the results of using different algorithms.

Version:
1.1
Author:
© Eliyahu Hershfeld 2004 - 2007

Constructor Summary
AstronomicalCalculator()
           
 
Method Summary
(package private)  double adjustZenith(double zenith, double elevation)
          Adjusts the zenith to account for solar refraction, solar radius and elevation.
abstract  String getCalculatorName()
           
static AstronomicalCalculator getDefault()
          getDefault method returns the default sun times calculation engine.
(package private)  double getElevationAdjustment(double elevation)
          Method to return the adjustment to the zenith required to account for the elevation.
(package private)  double getRefraction()
          Method to get the refraction value to be used when calculating sunrise and sunset.
(package private)  double getSolarRadius()
          Method to get the sun's radius.
abstract  double getUTCSunrise(AstronomicalCalendar astronomicalCalendar, double zenith, boolean adjustForElevation)
          A method that calculates UTC sunrise as well as any time based on an angle above or below sunrise.
abstract  double getUTCSunset(AstronomicalCalendar astronomicalCalendar, double zenith, boolean adjustForElevation)
          A method that calculates UTC sunset as well as any time based on an angle above or below sunset.
 void setRefraction(double refraction)
          A method to allow overriding the default refraction of the calculator.
 void setSolarRadius(double solarRadius)
          Method to set the sun's radius.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AstronomicalCalculator

public AstronomicalCalculator()
Method Detail

getDefault

public static AstronomicalCalculator getDefault()
getDefault method returns the default sun times calculation engine.

Returns:
AstronomicalCalculator the default class for calculating sunrise and sunset. In the current implementation the default calculator returned is the SunTimesCalculator.

getCalculatorName

public abstract String getCalculatorName()
Returns:
the descriptive name of the algorithm.

getUTCSunrise

public abstract double getUTCSunrise(AstronomicalCalendar astronomicalCalendar,
                                     double zenith,
                                     boolean adjustForElevation)
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.

Parameters:
astronomicalCalendar - Used to calculate day of year.
zenith - 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 AstronomicalCalendar.getBeginNauticalTwilight() that passes AstronomicalCalendar.NAUTICAL_ZENITH to this method.
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.

getUTCSunset

public abstract double getUTCSunset(AstronomicalCalendar astronomicalCalendar,
                                    double zenith,
                                    boolean adjustForElevation)
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.

Parameters:
astronomicalCalendar - Used to calculate day of year.
zenith - 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 AstronomicalCalendar.getEndNauticalTwilight() that passes AstronomicalCalendar.NAUTICAL_ZENITH to this method.
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.

getElevationAdjustment

double getElevationAdjustment(double elevation)
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 above or below 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 algorthitm 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);
 

Parameters:
elevation - elevation in Meters.
Returns:
the adjusted zenith

adjustZenith

double adjustZenith(double zenith,
                    double elevation)
Adjusts the zenith 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 (this can be changed via the setSolarRadius(double) method , and atmospheric refraction accounts for 34 minutes or so (this can be changed via the setRefraction(double) method), 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.

Returns:
The zenith adjusted to include the sun's radius, refraction and elevation adjustment.

getRefraction

double getRefraction()
Method to get the refraction value to be used when calculating sunrise and sunset. The default value is 34 arc minutes. The Errata and Notes for Calendrical Calculations: The Millenium Eddition by Edward M. Reingold and Nachum Dershowitz lists the actual refraction value as 34.478885263888294 or approximately 34' 29". The refraction value as well as the solarRadius and elevation adjustment are added to the zenith of sunrise and sunset.

Returns:
The refraction in arc minutes.

setRefraction

public void setRefraction(double refraction)
A method to allow overriding the default refraction of the calculator.

Parameters:
refraction - The refraction in arc minutes.
See Also:
getRefraction()

getSolarRadius

double getSolarRadius()
Method to get the sun's radius. The default value is 16 arc minutes. This will probably never be changed unless someone calculates that it is different than the commonly used 16 arc minutes.

Returns:
The sun's radius in arc minutes.

setSolarRadius

public void setSolarRadius(double solarRadius)
Method to set the sun's radius. The default value is 16 arc minutes. This will probably never be changed unless someone calculates that it is different than the commonly used 16 arc minutes.

Parameters:
solarRadius - The sun's radius in arc minutes.

KosherJava Zmanim Homepage
Includes a dynamic Zmanim calendar generator

Copyright © 2004 - 2007 Eliyahu Hershfeld. All Rights Reserved.