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 {@link #setDate setDate}, {@link #getDate 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 {@link IslamicCalendar} + * and {@link ChineseCalendar}. + * + * @author Laura Werner + * @author Alan Liu + * @internal + */ +class U_I18N_API CalendarAstronomer : public UMemory { +public: + // some classes + +public: + /** + * Represents the position of an object in the sky relative to the ecliptic, + * the plane of the earth's orbit around the Sun. + * This is a spherical coordinate system in which the latitude + * specifies the position north or south of the plane of the ecliptic. + * The longitude specifies the position along the ecliptic plane + * relative to the "First Point of Aries", which is the Sun's position in the sky + * at the Vernal Equinox. + *
+ * Note that Ecliptic objects are immutable and cannot be modified + * once they are constructed. This allows them to be passed and returned by + * value without worrying about whether other code will modify them. + * + * @see CalendarAstronomer.Equatorial + * @see CalendarAstronomer.Horizon + * @internal + */ + class U_I18N_API Ecliptic : public UMemory { + public: + /** + * Constructs an Ecliptic coordinate object. + *
+ * @param lat The ecliptic latitude, measured in radians. + * @param lon The ecliptic longitude, measured in radians. + * @internal + */ + Ecliptic(double lat = 0, double lon = 0) { + latitude = lat; + longitude = lon; + } + + /** + * Setter for Ecliptic Coordinate object + * @param lat The ecliptic latitude, measured in radians. + * @param lon The ecliptic longitude, measured in radians. + * @internal + */ + void set(double lat, double lon) { + latitude = lat; + longitude = lon; + } + + /** + * Return a string representation of this object + * @internal + */ + UnicodeString toString() const; + + /** + * The ecliptic latitude, in radians. This specifies an object's + * position north or south of the plane of the ecliptic, + * with positive angles representing north. + * @internal + */ + double latitude; + + /** + * The ecliptic longitude, in radians. + * This specifies an object's position along the ecliptic plane + * relative to the "First Point of Aries", which is the Sun's position + * in the sky at the Vernal Equinox, + * with positive angles representing east. + *
+ * A bit of trivia: the first point of Aries is currently in the + * constellation Pisces, due to the precession of the earth's axis. + * @internal + */ + double longitude; + }; + + /** + * Represents the position of an + * object in the sky relative to the plane of the earth's equator. + * The Right Ascension specifies the position east or west + * along the equator, relative to the sun's position at the vernal + * equinox. The Declination is the position north or south + * of the equatorial plane. + *
+ * Note that Equatorial objects are immutable and cannot be modified + * once they are constructed. This allows them to be passed and returned by + * value without worrying about whether other code will modify them. + * + * @see CalendarAstronomer.Ecliptic + * @see CalendarAstronomer.Horizon + * @internal + */ + class U_I18N_API Equatorial : public UMemory { + public: + /** + * Constructs an Equatorial coordinate object. + *
+ * @param asc The right ascension, measured in radians. + * @param dec The declination, measured in radians. + * @internal + */ + Equatorial(double asc = 0, double dec = 0) + : ascension(asc), declination(dec) { } + + /** + * Setter + * @param asc The right ascension, measured in radians. + * @param dec The declination, measured in radians. + * @internal + */ + void set(double asc, double dec) { + ascension = asc; + declination = dec; + } + + /** + * Return a string representation of this object, with the + * angles measured in degrees. + * @internal + */ + UnicodeString toString() const; + + /** + * Return a string representation of this object with the right ascension + * measured in hours, minutes, and seconds. + * @internal + */ + //String toHmsString() { + //return radToHms(ascension) + "," + radToDms(declination); + //} + + /** + * The right ascension, in radians. + * This is the position east or west along the equator + * relative to the sun's position at the vernal equinox, + * with positive angles representing East. + * @internal + */ + double ascension; + + /** + * The declination, in radians. + * This is the position north or south of the equatorial plane, + * with positive angles representing north. + * @internal + */ + double declination; + }; + + /** + * Represents the position of an object in the sky relative to + * the local horizon. + * The Altitude represents the object's elevation above the horizon, + * with objects below the horizon having a negative altitude. + * The Azimuth is the geographic direction of the object from the + * observer's position, with 0 representing north. The azimuth increases + * clockwise from north. + *
+ * Note that Horizon objects are immutable and cannot be modified + * once they are constructed. This allows them to be passed and returned by + * value without worrying about whether other code will modify them. + * + * @see CalendarAstronomer.Ecliptic + * @see CalendarAstronomer.Equatorial + * @internal + */ + class U_I18N_API Horizon : public UMemory { + public: + /** + * Constructs a Horizon coordinate object. + *
+ * @param alt The altitude, measured in radians above the horizon.
+ * @param azim The azimuth, measured in radians clockwise from north.
+ * @internal
+ */
+ Horizon(double alt=0, double azim=0)
+ : altitude(alt), azimuth(azim) { }
+
+ /**
+ * Setter for Ecliptic Coordinate object
+ * @param alt The altitude, measured in radians above the horizon.
+ * @param azim The azimuth, measured in radians clockwise from north.
+ * @internal
+ */
+ void set(double alt, double azim) {
+ altitude = alt;
+ azimuth = azim;
+ }
+
+ /**
+ * Return a string representation of this object, with the
+ * angles measured in degrees.
+ * @internal
+ */
+ UnicodeString toString() const;
+
+ /**
+ * The object's altitude above the horizon, in radians.
+ * @internal
+ */
+ double altitude;
+
+ /**
+ * The object's direction, in radians clockwise from north.
+ * @internal
+ */
+ double azimuth;
+ };
+
+public:
+ //-------------------------------------------------------------------------
+ // Assorted private data used for conversions
+ //-------------------------------------------------------------------------
+
+ // My own copies of these so compilers are more likely to optimize them away
+ static const double PI;
+
+ /**
+ * 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 #SIDEREAL_MONTH
+ * @internal
+ * @deprecated ICU 2.4. This class may be removed or modified.
+ */
+ static const double SYNODIC_MONTH;
+
+ //-------------------------------------------------------------------------
+ // Constructors
+ //-------------------------------------------------------------------------
+
+ /**
+ * Construct a new CalendarAstronomer object that is initialized to
+ * the current date and time.
+ * @internal
+ */
+ CalendarAstronomer();
+
+ /**
+ * Construct a new CalendarAstronomer object that is initialized to
+ * the specified date and time.
+ * @internal
+ */
+ CalendarAstronomer(UDate d);
+
+ /**
+ * Construct a new CalendarAstronomer object with the given
+ * latitude and longitude. The object's time is set to the current
+ * date and time.
+ *
+ * @param longitude The desired longitude, in degrees east of
+ * the Greenwich meridian.
+ *
+ * @param latitude The desired latitude, in degrees. Positive
+ * values signify North, negative South.
+ *
+ * @see java.util.Date#getTime()
+ * @internal
+ */
+ CalendarAstronomer(double longitude, double latitude);
+
+ /**
+ * Destructor
+ * @internal
+ */
+ ~CalendarAstronomer();
+
+ //-------------------------------------------------------------------------
+ // Time and date getters and setters
+ //-------------------------------------------------------------------------
+
+ /**
+ * Set the current date and time of this CalendarAstronomer object. All
+ * astronomical calculations are performed based on this time setting.
+ *
+ * @param aTime the date and time, expressed as the number of milliseconds since
+ * 1/1/1970 0:00 GMT (Gregorian).
+ *
+ * @see #setDate
+ * @see #getTime
+ * @internal
+ */
+ void setTime(UDate aTime);
+
+
+ /**
+ * Set the current date and time of this CalendarAstronomer object. All
+ * astronomical calculations are performed based on this time setting.
+ *
+ * @param aTime the date and time, expressed as the number of milliseconds since
+ * 1/1/1970 0:00 GMT (Gregorian).
+ *
+ * @see #getTime
+ * @internal
+ */
+ void setDate(UDate aDate) { setTime(aDate); }
+
+ /**
+ * Set the current date and time of this CalendarAstronomer object. All
+ * astronomical calculations are performed based on this time setting.
+ *
+ * @param 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 #getJulianDay
+ * @see #JULIAN_EPOCH_MS
+ * @internal
+ */
+ void setJulianDay(double jdn);
+
+ /**
+ * Get the current time of this CalendarAstronomer object,
+ * represented as the number of milliseconds since
+ * 1/1/1970 AD 0:00 GMT (Gregorian).
+ *
+ * @see #setTime
+ * @see #getDate
+ * @internal
+ */
+ UDate getTime();
+
+ /**
+ * 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 #setJulianDay
+ * @see #JULIAN_EPOCH_MS
+ * @internal
+ */
+ double getJulianDay();
+
+ /**
+ * Return this object's time expressed in julian centuries:
+ * the number of centuries after 1/1/1900 AD, 12:00 GMT
+ *
+ * @see #getJulianDay
+ * @internal
+ */
+ double getJulianCentury();
+
+ /**
+ * Returns the current Greenwich sidereal time, measured in hours
+ * @internal
+ */
+ double getGreenwichSidereal();
+
+private:
+ double getSiderealOffset();
+public:
+ /**
+ * Returns the current local sidereal time, measured in hours
+ * @internal
+ */
+ double getLocalSidereal();
+
+ /**
+ * Converts local sidereal time to Universal Time.
+ *
+ * @param lst The Local Sidereal Time, in hours since sidereal midnight
+ * on this object's current date.
+ *
+ * @return The corresponding Universal Time, in milliseconds since
+ * 1 Jan 1970, GMT.
+ */
+ //private:
+ double lstToUT(double lst);
+
+ /**
+ *
+ * Convert from ecliptic to equatorial coordinates.
+ *
+ * @param ecliptic The ecliptic
+ * @param result Fillin result
+ * @return reference to result
+ */
+ Equatorial& eclipticToEquatorial(Equatorial& result, const Ecliptic& ecliptic);
+
+ /**
+ * Convert from ecliptic to equatorial coordinates.
+ *
+ * @param eclipLong The ecliptic longitude
+ * @param eclipLat The ecliptic latitude
+ *
+ * @return The corresponding point in equatorial coordinates.
+ * @internal
+ */
+ Equatorial& eclipticToEquatorial(Equatorial& result, double eclipLong, double eclipLat);
+
+ /**
+ * Convert from ecliptic longitude to equatorial coordinates.
+ *
+ * @param eclipLong The ecliptic longitude
+ *
+ * @return The corresponding point in equatorial coordinates.
+ * @internal
+ */
+ Equatorial& eclipticToEquatorial(Equatorial& result, double eclipLong) ;
+
+ /**
+ * @internal
+ */
+ Horizon& eclipticToHorizon(Horizon& result, double eclipLong) ;
+
+ //-------------------------------------------------------------------------
+ // The Sun
+ //-------------------------------------------------------------------------
+
+ /**
+ * 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.
+ * @internal
+ */
+ double getSunLongitude();
+
+ /**
+ * TODO Make this public when the entire class is package-private.
+ */
+ /*public*/ void getSunLongitude(double julianDay, double &longitude, double &meanAnomaly);
+
+ /**
+ * The position of the sun at this object's current date and time,
+ * in equatorial coordinates.
+ * @param result fillin for the result
+ * @internal
+ */
+ Equatorial& getSunPosition(Equatorial& result);
+
+public:
+ /**
+ * Constant representing the vernal equinox.
+ * For use with {@link #getSunTime getSunTime}.
+ * Note: In this case, "vernal" refers to the northern hemisphere's seasons.
+ * @internal
+ */
+// static double VERNAL_EQUINOX();
+
+ /**
+ * Constant representing the summer solstice.
+ * For use with {@link #getSunTime getSunTime}.
+ * Note: In this case, "summer" refers to the northern hemisphere's seasons.
+ * @internal
+ */
+ static double SUMMER_SOLSTICE();
+
+ /**
+ * Constant representing the autumnal equinox.
+ * For use with {@link #getSunTime getSunTime}.
+ * Note: In this case, "autumn" refers to the northern hemisphere's seasons.
+ * @internal
+ */
+// static double AUTUMN_EQUINOX();
+
+ /**
+ * Constant representing the winter solstice.
+ * For use with {@link #getSunTime getSunTime}.
+ * Note: In this case, "winter" refers to the northern hemisphere's seasons.
+ * @internal
+ */
+ static double WINTER_SOLSTICE();
+
+ /**
+ * Find the next time at which the sun's ecliptic longitude will have
+ * the desired value.
+ * @internal
+ */
+ UDate getSunTime(double desired, UBool next);
+
+ /**
+ * 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.
+ *
+ * @internal
+ */
+ UDate getSunRiseSet(UBool rise);
+
+ //-------------------------------------------------------------------------
+ // The Moon
+ //-------------------------------------------------------------------------
+
+ /**
+ * The position of the moon at the time set on this
+ * object, in equatorial coordinates.
+ * @internal
+ * @return const reference to internal field of calendar astronomer. Do not use outside of the lifetime of this astronomer.
+ */
+ const Equatorial& getMoonPosition();
+
+ /**
+ * 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 #getMoonPhase
+ * @internal
+ */
+ double getMoonAge();
+
+ /**
+ * Calculate the phase of the moon at the time set in this object.
+ * The returned phase is a double in the range
+ * 0 <= phase < 1, interpreted as follows:
+ *
+ * @param desired The desired longitude. + * @param next true if the next occurrance of the phase + * is desired, false for the previous occurrance. + * @internal + */ + UDate getMoonTime(double desired, UBool next); + UDate getMoonTime(const MoonAge& desired, UBool next); + + /** + * Returns the time (GMT) of sunrise or sunset on the local date to which + * this calendar is currently set. + * @internal + */ + UDate getMoonRiseSet(UBool rise); + + //------------------------------------------------------------------------- + // Interpolation methods for finding the time at which a given event occurs + //------------------------------------------------------------------------- + + // private + class AngleFunc : public UMemory { + public: + virtual double eval(CalendarAstronomer&) = 0; + virtual ~AngleFunc(); + }; + friend class AngleFunc; + + UDate timeOfAngle(AngleFunc& func, double desired, + double periodDays, double epsilon, UBool next); + + class CoordFunc : public UMemory { + public: + virtual void eval(Equatorial& result, CalendarAstronomer&) = 0; + virtual ~CoordFunc(); + }; + friend class CoordFunc; + + double riseOrSet(CoordFunc& func, UBool rise, + double diameter, double refraction, + double epsilon); + + //------------------------------------------------------------------------- + // Other utility methods + //------------------------------------------------------------------------- +private: + + /** + * 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. + * + * @return the obliquity of the ecliptic relative to the equator, + * measured in radians. + */ + double eclipticObliquity(); + + //------------------------------------------------------------------------- + // Private data + //------------------------------------------------------------------------- +private: + /** + * Current time in milliseconds since 1/1/1970 AD + * @see java.util.Date#getTime + */ + UDate fTime; + + /* These aren't used yet, but they'll be needed for sunset calculations + * and equatorial to horizon coordinate conversions + */ + double fLongitude; + double fLatitude; + double fGmtOffset; + + // + // The following fields are used to cache calculated results for improved + // performance. These values all depend on the current time setting + // of this object, so the clearCache method is provided. + // + + double julianDay; + double julianCentury; + double sunLongitude; + double meanAnomalySun; + double moonLongitude; + double moonEclipLong; + double meanAnomalyMoon; + double eclipObliquity; + double siderealT0; + double siderealTime; + + void clearCache(); + + Equatorial moonPosition; + UBool moonPositionSet; + + /** + * @internal + */ +// UDate local(UDate localMillis); +}; + +U_NAMESPACE_END + +struct UHashtable; + +U_NAMESPACE_BEGIN + +/** + * Cache of month -> julian day + * @internal + */ +class CalendarCache : public UMemory { +public: + static int32_t get(CalendarCache** cache, int32_t key, UErrorCode &status); + static void put(CalendarCache** cache, int32_t key, int32_t value, UErrorCode &status); + virtual ~CalendarCache(); +private: + CalendarCache(int32_t size, UErrorCode& status); + static void createCache(CalendarCache** cache, UErrorCode& status); + /** + * not implemented + */ + CalendarCache(); + UHashtable *fTable; +}; + +U_NAMESPACE_END + +#endif +#endif