import { DateTime } from 'luxon';
import { GeoLocation } from './GeoLocation';
/**
* 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.
* TODO: Consider methods that would allow atmospheric modeling. This can currently be adjusted by {@link
* #setRefraction(double) setting the refraction}.
*
* @author © Eliyahu Hershfeld 2004 - 2020
*/
export declare abstract class AstronomicalCalculator {
/**
* The commonly used average solar refraction. Calendrical Calculations lists a more accurate global average of 34.478885263888294
*
* @see #getRefraction()
*/
private refraction;
/**
* The commonly used average solar radius in minutes of a degree.
*
* @see #getSolarRadius()
*/
private solarRadius;
/**
* The commonly used average earth radius in KM. At this time, this only affects elevation adjustment and not the
* sunrise and sunset calculations. The value currently defaults to 6356.9 KM.
*
* @see #getEarthRadius()
* @see #setEarthRadius(double)
*/
private earthRadius;
/**
* Default constructor using the default {@link #refraction refraction}, {@link #solarRadius solar radius} and
* {@link #earthRadius earth radius}.
*/
AstronomicalCalculator(): void;
/**
* A method that returns the earth radius in KM. The value currently defaults to 6356.9 KM if not set.
*
* @return the earthRadius the earth radius in KM.
*/
getEarthRadius(): number;
/**
* A method that allows setting the earth's radius.
*
* @param earthRadius
* the earthRadius to set in KM
*/
setEarthRadius(earthRadius: number): void;
/**
* The zenith of astronomical sunrise and sunset. The sun is 90° from the vertical 0°
*/
private static readonly GEOMETRIC_ZENITH;
/**
* Returns the default class for calculating sunrise and sunset. This is currently the more accurate
* {@link NOAACalculator}, but this may change in the future.
*
* @return AstronomicalCalculator the default class for calculating sunrise and sunset. In the current
* implementation the default calculator returned is the more accurate {@link NOAACalculator}.
* @deprecated This depends on a circular dependency. Use new NOAACalculator()
instead
*/
static getDefault(): void;
/**
* Returns the name of the algorithm.
*
* @return the descriptive name of the algorithm.
*/
abstract getCalculatorName(): string;
/**
* 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.
*
* @param calendar
* Used to calculate day of year.
* @param geoLocation
* The location information used for astronomical calculating sun times.
* @param zenith
* the azimuth below the vertical zenith of 90 degrees. for sunrise typically the {@link #adjustZenith
* zenith} used for the calculation uses geometric zenith of 90° and {@link #adjustZenith adjusts}
* this slightly to account for solar refraction and the sun's radius. Another example would be
* {@link AstronomicalCalendar#getBeginNauticalTwilight()} that passes
* {@link AstronomicalCalendar#NAUTICAL_ZENITH} to this method.
* @param adjustForElevation
* Should the time be adjusted for elevation
* @return 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,
* {@link java.lang.Double#NaN} will be returned.
* @see #getElevationAdjustment(double)
*/
abstract getUTCSunrise(date: DateTime, geoLocation: GeoLocation, zenith: number, adjustForElevation: boolean): number;
/**
* 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.
*
* @param calendar
* Used to calculate day of year.
* @param geoLocation
* The location information used for astronomical calculating sun times.
* @param zenith
* the azimuth below the vertical zenith of 90°. For sunset typically the {@link #adjustZenith
* zenith} used for the calculation uses geometric zenith of 90° and {@link #adjustZenith adjusts}
* this slightly to account for solar refraction and the sun's radius. Another example would be
* {@link AstronomicalCalendar#getEndNauticalTwilight()} that passes
* {@link AstronomicalCalendar#NAUTICAL_ZENITH} to this method.
* @param adjustForElevation
* Should the time be adjusted for elevation
* @return 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,
* {@link java.lang.Double#NaN} will be returned.
* @see #getElevationAdjustment(double)
*/
abstract getUTCSunset(date: DateTime, geoLocation: GeoLocation, zenith: number, adjustForElevation: boolean): number;
/**
* Return solar noon (UTC) for the given day at the
* given location on earth. The {@link com.kosherjava.zmanim.util.NOAACalculator} implementation calculates
* true solar noon, while the {@link com.kosherjava.zmanim.util.SunTimesCalculator} approximates it, calculating
* the time as halfway between sunrise and sunset.
*
* @param date
* Used to calculate day of year.
* @param geoLocation
* The location information used for astronomical calculating sun times.
*
* @return the time in minutes from zero UTC
*/
abstract getUTCNoon(date: DateTime, geoLocation: GeoLocation): number;
/**
* Return solar midnight (UTC) for the given day at the
* given location on earth. The the {@link com.kosherjava.zmanim.util.NOAACalculator} implementation calculates
* true solar midnight, while the {@link com.kosherjava.zmanim.util.SunTimesCalculator} approximates it, calculating
* the time as 12 hours after halfway between sunrise and sunset.
*
* @param calendar
* Used to calculate day of year.
* @param geoLocation
* The location information used for astronomical calculating sun times.
*
* @return the time in minutes from zero UTC
*/
abstract getUTCMidnight(date: DateTime, geoLocation: GeoLocation): number;
/**
* 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
* {@link AstronomicalCalendar#getBeginNauticalTwilight() 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 be made if the zenith == 90° {@link #adjustZenith 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 similar (but
* not completely accurate) result found in Ma'aglay Tzedek by Moishe Kosower and other sources is:
*
*
* elevationAdjustment = 0.0347 * Math.sqrt(elevationMeters);
*
*
* @param elevation
* elevation in Meters.
* @return the adjusted zenith
*/
getElevationAdjustment(elevation: number): number;
/**
* 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 (this can be changed via the {@link #setSolarRadius(double)} method , and atmospheric refraction
* accounts for 34 minutes or so (this can be changed via the {@link #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 below 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 {@link AstronomicalCalendar#ASTRONOMICAL_ZENITH 108°
* below the zenith}. This is traditionally calculated with none of the above mentioned adjustments. The same goes
* for various tzais and alos times such as the
* {@link ZmanimCalendar#ZENITH_16_POINT_1 16.1°} dip used in
* {@link ComplexZmanimCalendar#getAlos16Point1Degrees()}.
*
* @param zenith
* the azimuth below the vertical zenith of 90°. For sunset typically the {@link #adjustZenith
* zenith} used for the calculation uses geometric zenith of 90° and {@link #adjustZenith adjusts}
* this slightly to account for solar refraction and the sun's radius. Another example would be
* {@link AstronomicalCalendar#getEndNauticalTwilight()} that passes
* {@link AstronomicalCalendar#NAUTICAL_ZENITH} to this method.
* @param elevation
* elevation in Meters.
* @return The zenith adjusted to include the {@link #getSolarRadius sun's radius}, {@link #getRefraction
* refraction} and {@link #getElevationAdjustment elevation} adjustment. This will only be adjusted for
* sunrise and sunset (if the zenith == 90°)
* @see #getElevationAdjustment(double)
*/
adjustZenith(zenith: number, elevation: number): number;
/**
* Method to get the refraction value to be used when calculating sunrise and sunset. The default value is 34
* arcminutes. The Errata and Notes
* for Calendrical Calculations: The Millennium Edition by Edward M. Reingold and Nachum Dershowitz lists the
* actual average 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 used to calculate sunrise and sunset.
*
* @return The refraction in arcminutes.
*/
getRefraction(): number;
/**
* A method to allow overriding the default refraction of the calculator.
* @todo At some point in the future, an AtmosphericModel or Refraction object that models the atmosphere of different
* locations might be used for increased accuracy.
*
* @param refraction
* The refraction in arcminutes.
* @see #getRefraction()
*/
setRefraction(refraction: number): void;
/**
* Method to get the sun's radius. The default value is 16 arcminutes. The sun's radius as it appears from earth is
* almost universally given as 16 arcminutes but in fact it differs by the time of the year. At the perihelion it has an apparent radius of 16.293, while at the
* aphelion it has an apparent radius of 15.755. There is little
* affect for most location, but at high and low latitudes the difference becomes more apparent. My Calculations for
* the difference at the location of the Royal Observatory, Greenwich
* shows only a 4.494-second difference between the perihelion and aphelion radii, but moving into the arctic circle the
* difference becomes more noticeable. Tests for Tromso, Norway (latitude 69.672312, longitude 19.049787) show that
* on May 17, the rise of the midnight sun, a 2 minute 23 second difference is observed between the perihelion and
* aphelion radii using the USNO algorithm, but only 1 minute and 6 seconds difference using the NOAA algorithm.
* Areas farther north show an even greater difference. Note that these test are not real valid test cases because
* they show the extreme difference on days that are not the perihelion or aphelion, but are shown for illustrative
* purposes only.
*
* @return The sun's radius in arcminutes.
*/
getSolarRadius(): number;
/**
* Method to set the sun's radius.
*
* @param solarRadius
* The sun's radius in arcminutes.
* @see #getSolarRadius()
*/
setSolarRadius(solarRadius: number): void;
/**
* @see java.lang.Object#clone()
* @since 1.1
*/
clone(): AstronomicalCalculator;
equals(object: object): boolean;
}