Class CalendarAstronomer

java.lang.Object
com.ibm.icu.impl.CalendarAstronomer

public class CalendarAstronomer extends Object
CalendarAstronomer is a class that can perform the calculations to determine the positions of the sun and moon, the time of sunrise and sunset, and other astronomy-related data. The calculations it performs are in some cases quite complicated, and this utility class saves you the trouble of worrying about them.

The measurement of time is a very important part of astronomy. Because astronomical bodies are constantly in motion, observations are only valid at a given moment in time. Accordingly, each CalendarAstronomer object has a time property that determines the date and time for which its calculations are performed. You can set and retrieve this property with setDate, getDate and related methods.

Almost all of the calculations performed by this class, or by any astronomer, are approximations to various degrees of accuracy. The calculations in this class are mostly modelled after those described in the book Practical Astronomy With Your Calculator, by Peter J. Duffett-Smith, Cambridge University Press, 1990. This is an excellent book, and if you want a greater understanding of how these calculations are performed it a very good, readable starting point.

WARNING: This class is very early in its development, and it is highly likely that its API will change to some degree in the future. At the moment, it basically does just enough to support IslamicCalendar and ChineseCalendar.

  • Field Details

    • SIDEREAL_DAY

      public static final double SIDEREAL_DAY
      The number of standard hours in one sidereal day. Approximately 24.93.
      See Also:
    • SOLAR_DAY

      public static final double SOLAR_DAY
      The number of sidereal hours in one mean solar day. Approximately 24.07.
      See Also:
    • SYNODIC_MONTH

      public static final double SYNODIC_MONTH
      The average number of solar days from one new moon to the next. This is the time it takes for the moon to return the same ecliptic longitude as the sun. It is longer than the sidereal month because the sun's longitude increases during the year due to the revolution of the earth around the sun. Approximately 29.53.
      See Also:
    • SIDEREAL_MONTH

      public static final double SIDEREAL_MONTH
      The average number of days it takes for the moon to return to the same ecliptic longitude relative to the stellar background. This is referred to as the sidereal month. It is shorter than the synodic month due to the revolution of the earth around the sun. Approximately 27.32.
      See Also:
    • TROPICAL_YEAR

      public static final double TROPICAL_YEAR
      The average number number of days between successive vernal equinoxes. Due to the precession of the earth's axis, this is not precisely the same as the sidereal year. Approximately 365.24
      See Also:
    • SIDEREAL_YEAR

      public static final double SIDEREAL_YEAR
      The average number of days it takes for the sun to return to the same position against the fixed stellar background. This is the duration of one orbit of the earth about the sun as it would appear to an outside observer. Due to the precession of the earth's axis, this is not precisely the same as the tropical year. Approximately 365.25.
      See Also:
    • SECOND_MS

      public static final int SECOND_MS
      The number of milliseconds in one second.
      See Also:
    • MINUTE_MS

      public static final int MINUTE_MS
      The number of milliseconds in one minute.
      See Also:
    • HOUR_MS

      public static final int HOUR_MS
      The number of milliseconds in one hour.
      See Also:
    • DAY_MS

      public static final long DAY_MS
      The number of milliseconds in one day.
      See Also:
    • JULIAN_EPOCH_MS

      public static final long JULIAN_EPOCH_MS
      The start of the julian day numbering scheme used by astronomers, which is 1/1/4713 BC (Julian), 12:00 GMT. This is given as the number of milliseconds since 1/1/1970 AD (Gregorian), a negative number. Note that julian day numbers and the Julian calendar are not the same thing. Also note that julian days start at noon, not midnight.
      See Also:
    • EPOCH_2000_MS

      static final long EPOCH_2000_MS
      Milliseconds value for 0.0 January 2000 AD.
      See Also:
    • PI

      private static final double PI
      See Also:
    • PI2

      private static final double PI2
      See Also:
    • RAD_HOUR

      private static final double RAD_HOUR
      See Also:
    • DEG_RAD

      private static final double DEG_RAD
      See Also:
    • RAD_DEG

      private static final double RAD_DEG
      See Also:
    • JD_EPOCH

      static final double JD_EPOCH
      See Also:
    • SUN_ETA_G

      static final double SUN_ETA_G
      See Also:
    • SUN_OMEGA_G

      static final double SUN_OMEGA_G
      See Also:
    • SUN_E

      static final double SUN_E
      See Also:
    • VERNAL_EQUINOX

      public static final CalendarAstronomer.SolarLongitude VERNAL_EQUINOX
      Constant representing the vernal equinox. For use with getSunTime. Note: In this case, "vernal" refers to the northern hemisphere's seasons.
    • SUMMER_SOLSTICE

      public static final CalendarAstronomer.SolarLongitude SUMMER_SOLSTICE
      Constant representing the summer solstice. For use with getSunTime. Note: In this case, "summer" refers to the northern hemisphere's seasons.
    • AUTUMN_EQUINOX

      public static final CalendarAstronomer.SolarLongitude AUTUMN_EQUINOX
      Constant representing the autumnal equinox. For use with getSunTime. Note: In this case, "autumn" refers to the northern hemisphere's seasons.
    • WINTER_SOLSTICE

      public static final CalendarAstronomer.SolarLongitude WINTER_SOLSTICE
      Constant representing the winter solstice. For use with getSunTime. Note: In this case, "winter" refers to the northern hemisphere's seasons.
    • moonL0

      static final double moonL0
      See Also:
    • moonP0

      static final double moonP0
      See Also:
    • moonN0

      static final double moonN0
      See Also:
    • moonI

      static final double moonI
      See Also:
    • moonE

      static final double moonE
      See Also:
    • moonA

      static final double moonA
      See Also:
    • moonT0

      static final double moonT0
      See Also:
    • moonPi

      static final double moonPi
      See Also:
    • NEW_MOON

      public static final CalendarAstronomer.MoonAge NEW_MOON
      Constant representing a new moon. For use with getMoonTime
    • FIRST_QUARTER

      public static final CalendarAstronomer.MoonAge FIRST_QUARTER
      Constant representing the moon's first quarter. For use with getMoonTime
    • FULL_MOON

      public static final CalendarAstronomer.MoonAge FULL_MOON
      Constant representing a full moon. For use with getMoonTime
    • LAST_QUARTER

      public static final CalendarAstronomer.MoonAge LAST_QUARTER
      Constant representing the moon's last quarter. For use with getMoonTime
    • time

      private long time
      Current time in milliseconds since 1/1/1970 AD
      See Also:
    • fLongitude

      private double fLongitude
    • fLatitude

      private double fLatitude
    • fGmtOffset

      private long fGmtOffset
    • INVALID

      private static final double INVALID
      See Also:
    • julianDay

      private transient double julianDay
    • julianCentury

      private transient double julianCentury
    • sunLongitude

      private transient double sunLongitude
    • meanAnomalySun

      private transient double meanAnomalySun
    • moonLongitude

      private transient double moonLongitude
    • moonEclipLong

      private transient double moonEclipLong
    • eclipObliquity

      private transient double eclipObliquity
    • siderealT0

      private transient double siderealT0
    • siderealTime

      private transient double siderealTime
    • moonPosition

      private transient CalendarAstronomer.Equatorial moonPosition
  • Constructor Details

    • CalendarAstronomer

      public CalendarAstronomer()
      Construct a new CalendarAstronomer object that is initialized to the current date and time.
    • CalendarAstronomer

      public CalendarAstronomer(Date d)
      Construct a new CalendarAstronomer object that is initialized to the specified date and time.
    • CalendarAstronomer

      public CalendarAstronomer(long aTime)
      Construct a new CalendarAstronomer object that is initialized to the specified time. The time is expressed as a number of milliseconds since January 1, 1970 AD (Gregorian).
      See Also:
    • CalendarAstronomer

      public CalendarAstronomer(double longitude, double latitude)
      Construct a new CalendarAstronomer object with the given latitude and longitude. The object's time is set to the current date and time.

      Parameters:
      longitude - The desired longitude, in degrees east of the Greenwich meridian.
      latitude - The desired latitude, in degrees. Positive values signify North, negative South.
      See Also:
  • Method Details

    • setTime

      public void setTime(long aTime)
      Set the current date and time of this CalendarAstronomer object. All astronomical calculations are performed based on this time setting.
      Parameters:
      aTime - the date and time, expressed as the number of milliseconds since 1/1/1970 0:00 GMT (Gregorian).
      See Also:
    • setDate

      public void setDate(Date date)
      Set the current date and time of this CalendarAstronomer object. All astronomical calculations are performed based on this time setting.
      Parameters:
      date - the time and date, expressed as a Date object.
      See Also:
    • setJulianDay

      public void setJulianDay(double jdn)
      Set the current date and time of this CalendarAstronomer object. All astronomical calculations are performed based on this time setting.
      Parameters:
      jdn - the desired time, expressed as a "julian day number", which is the number of elapsed days since 1/1/4713 BC (Julian), 12:00 GMT. Note that julian day numbers start at noon. To get the jdn for the corresponding midnight, subtract 0.5.
      See Also:
    • getTime

      public long getTime()
      Get the current time of this CalendarAstronomer object, represented as the number of milliseconds since 1/1/1970 AD 0:00 GMT (Gregorian).
      See Also:
    • getDate

      public Date getDate()
      Get the current time of this CalendarAstronomer object, represented as a Date object.
      See Also:
    • getJulianDay

      public double getJulianDay()
      Get the current time of this CalendarAstronomer object, expressed as a "julian day number", which is the number of elapsed days since 1/1/4713 BC (Julian), 12:00 GMT.
      See Also:
    • getJulianCentury

      public double getJulianCentury()
      Return this object's time expressed in julian centuries: the number of centuries after 1/1/1900 AD, 12:00 GMT
      See Also:
    • getGreenwichSidereal

      public double getGreenwichSidereal()
      Returns the current Greenwich sidereal time, measured in hours
    • getSiderealOffset

      private double getSiderealOffset()
    • getLocalSidereal

      public double getLocalSidereal()
      Returns the current local sidereal time, measured in hours
    • lstToUT

      private long lstToUT(double lst)
      Converts local sidereal time to Universal Time.
      Parameters:
      lst - The Local Sidereal Time, in hours since sidereal midnight on this object's current date.
      Returns:
      The corresponding Universal Time, in milliseconds since 1 Jan 1970, GMT.
    • eclipticToEquatorial

      public final CalendarAstronomer.Equatorial eclipticToEquatorial(CalendarAstronomer.Ecliptic ecliptic)
      Convert from ecliptic to equatorial coordinates.
      Parameters:
      ecliptic - A point in the sky in ecliptic coordinates.
      Returns:
      The corresponding point in equatorial coordinates.
    • eclipticToEquatorial

      public final CalendarAstronomer.Equatorial eclipticToEquatorial(double eclipLong, double eclipLat)
      Convert from ecliptic to equatorial coordinates.
      Parameters:
      eclipLong - The ecliptic longitude
      eclipLat - The ecliptic latitude
      Returns:
      The corresponding point in equatorial coordinates.
    • eclipticToEquatorial

      public final CalendarAstronomer.Equatorial eclipticToEquatorial(double eclipLong)
      Convert from ecliptic longitude to equatorial coordinates.
      Parameters:
      eclipLong - The ecliptic longitude
      Returns:
      The corresponding point in equatorial coordinates.
    • eclipticToHorizon

      public CalendarAstronomer.Horizon eclipticToHorizon(double eclipLong)
    • getSunLongitude

      public double getSunLongitude()
      The longitude of the sun at the time specified by this object. The longitude is measured in radians along the ecliptic from the "first point of Aries," the point at which the ecliptic crosses the earth's equatorial plane at the vernal equinox.

      Currently, this method uses an approximation of the two-body Kepler's equation for the earth and the sun. It does not take into account the perturbations caused by the other planets, the moon, etc.

    • getSunLongitude

      double[] getSunLongitude(double julian)
      TODO Make this public when the entire class is package-private.
    • getSunPosition

      public CalendarAstronomer.Equatorial getSunPosition()
      The position of the sun at this object's current date and time, in equatorial coordinates.
    • getSunTime

      public long getSunTime(double desired, boolean next)
      Find the next time at which the sun's ecliptic longitude will have the desired value.
    • getSunTime

      public long getSunTime(CalendarAstronomer.SolarLongitude desired, boolean next)
      Find the next time at which the sun's ecliptic longitude will have the desired value.
    • getSunRiseSet

      public long getSunRiseSet(boolean rise)
      Returns the time (GMT) of sunrise or sunset on the local date to which this calendar is currently set. NOTE: This method only works well if this object is set to a time near local noon. Because of variations between the local official time zone and the geographic longitude, the computation can flop over into an adjacent day if this object is set to a time near local midnight.
    • getMoonPosition

      public CalendarAstronomer.Equatorial getMoonPosition()
      The position of the moon at the time set on this object, in equatorial coordinates.
    • getMoonAge

      public double getMoonAge()
      The "age" of the moon at the time specified in this object. This is really the angle between the current ecliptic longitudes of the sun and the moon, measured in radians.
      See Also:
    • getMoonPhase

      public double getMoonPhase()
      Calculate the phase of the moon at the time set in this object. The returned phase is a double in the range 0 invalid input: '<'= phase invalid input: '<' 1, interpreted as follows:
      • 0.00: New moon
      • 0.25: First quarter
      • 0.50: Full moon
      • 0.75: Last quarter
      See Also:
    • getMoonTime

      public long getMoonTime(double desired, boolean next)
      Find the next or previous time at which the Moon's ecliptic longitude will have the desired value.

      Parameters:
      desired - The desired longitude.
      next - true if the next occurrance of the phase is desired, false for the previous occurrance.
    • getMoonTime

      public long getMoonTime(CalendarAstronomer.MoonAge desired, boolean next)
      Find the next or previous time at which the moon will be in the desired phase.

      Parameters:
      desired - The desired phase of the moon.
      next - true if the next occurrance of the phase is desired, false for the previous occurrance.
    • getMoonRiseSet

      public long getMoonRiseSet(boolean rise)
      Returns the time (GMT) of sunrise or sunset on the local date to which this calendar is currently set.
    • timeOfAngle

      private long timeOfAngle(CalendarAstronomer.AngleFunc func, double desired, double periodDays, long epsilon, boolean next)
    • riseOrSet

      private long riseOrSet(CalendarAstronomer.CoordFunc func, boolean rise, double diameter, double refraction, long epsilon)
    • normalize

      private static final double normalize(double value, double range)
      Given 'value', add or subtract 'range' until 0 invalid input: '<'= 'value' invalid input: '<' range. The modulus operator.
    • norm2PI

      private static final double norm2PI(double angle)
      Normalize an angle so that it's in the range 0 - 2pi. For positive angles this is just (angle % 2pi), but the Java mod operator doesn't work that way for negative numbers....
    • normPI

      private static final double normPI(double angle)
      Normalize an angle into the range -PI - PI
    • trueAnomaly

      private double trueAnomaly(double meanAnomaly, double eccentricity)
      Find the "true anomaly" (longitude) of an object from its mean anomaly and the eccentricity of its orbit. This uses an iterative solution to Kepler's equation.
      Parameters:
      meanAnomaly - The object's longitude calculated as if it were in a regular, circular orbit, measured in radians from the point of perigee.
      eccentricity - The eccentricity of the orbit
      Returns:
      The true anomaly (longitude) measured in radians
    • eclipticObliquity

      private double eclipticObliquity()
      Return the obliquity of the ecliptic (the angle between the ecliptic and the earth's equator) at the current time. This varies due to the precession of the earth's axis.
      Returns:
      the obliquity of the ecliptic relative to the equator, measured in radians.
    • clearCache

      private void clearCache()
    • local

      public String local(long localMillis)
    • radToHms

      private static String radToHms(double angle)
    • radToDms

      private static String radToDms(double angle)