KDE Core/Astronomical Calendars/Islamic
Introduction
The Islamic calendar (or Hijri calendar) is a lunar calendar. It contains 12 months that are based on the synodic motion of the moon, which makes an Islamic year to have 12 x 29.53=354.36 days, the Islamic calendar is consistently shorter (11 Days) than a solar year, and therefore it shifts with respect to the Gregorian calendar. There has been a reference in the Quran about the number of months in an Islamic year: "Surely the number of months with Allah is twelve months in Allah's ordinance since the day when He created the heavens and the earth."
Months
The 12 months of the Islamic calendar are:
- Muharram
- Safar
- Rabi' al-awwal (Rabi I)
- Rabi' al-thani (Rabi II)
- Jumada al-awwal (Jumada I)
- Jumada al-thani (Jumada II)
- Rajab
- Sha'bad
- Ramadan
- Shawal
- Dhu al-Qi'dah
- Dhu al-Hijjah
The month starts when the lunar crescent is first seen after the new moon. This sighting is, however, subjective and depends on factors such as weather, the optical properties of the atmosphere, and the location of the observer. Furthermore, some Muslims depend on a local sighting of the moon, whereas others depend on a sighting by authorities somewhere in the Muslim world. Both are valid Islamic practices, but they may lead to different starting days for the months.
Year
The Era for the Islamic calendar begins on the evening of the Prophet Mohammad's flight from Mecca to Medina. It is believed that the migration occurred at the time of the first visible crescent of the New Moon, on the first day of the month of Muharram, or 16 July 622 AD (Julian Calendar). The word "flight" in Arabic is the Hijra, so the Era of the Moslem calendar is called that of the Hijra or, in English, the Hegira which defines the epoch of the Islamic calendar in terms of "AH," the Anno Hegirae.
Criteria for Lunar Crescent Visibility
The main area of concern regarding the implementation of the Islamic Calendar is the Lunar Crescent Visibility or Hilal. This has been the topic of various debates and there hasn't been a commonly agreed global consensus regarding the accurate sighting of the Hilal across the globe. S.K. Shaukat defined certain criteria for the lunar crescent visibility, which are:
- Lunar altitude > 4.1 degrees
- Arc of light, i.e., the elongation of the Moon from the Sun or the apparent angular distance > 10.6 degrees
- Age of the moon should be between New Moon and First Quarter
This criterion has been used in a lot of astronomical functions and have made calculations approximate at best for many reasons.
MABIMS have defined another criteria for lunar crescent visibility in Brunei, Indonesia, Malaysia and Singapore; which is:
- Lunar altitude > 2 degrees
- Arc of light > 3 degrees
- Age of the moon > 8 hours
MUIS further improvised on this criteria for Singapore and modified the values as:
- Lunar altitude > 6 degrees
- Arc of light > 7 degrees
- Age of the moon > 16 hours
Apart from the aforementioned lunar criteria, the subject of the crescent visibility has led to the concept of the International Lunar Date Line(ILDL). The ILDL is a curved line on a world map which separates areas (west of the line) where the crescent is likely to be seen at the start of the lunar month from areas (east of the line) where the crescent is unlikely to be seen. The position of the ILDL moves from month to month.
Research Sources
The research has been documented from the following sources, namely:
- Calendrical Calculations: Third Edition - Nachum Dershowitz and Edward M. Reingold
- Notes and Errata on Calendrical Calculations: Third Edition - 25th May 2011
- Astronomical Algorithms: First Edition - Jean Meeus
- Practical Astronomy with your Calculator: Third Edition - Peter Duffet-Smith
- How to compute planetary positions - Paul Schlyter
The amount of calculations required for the complete implementation of the calendar are highly extensive, and require very high precision. Without the astronomical calculations, the Islamic Calendar lacks accuracy by 1-2 days and therefore it becomes difficult to predict future dates in the Islamic Calendar. The astronomical calculations are so precisely timed that such an ambiguity in the prediction of dates of the Islamic Calendar is reduced to 1 day in 2500 years.
Astro Library
astro.h
This header file would contain the general functions for astronomical calculations. The functions perform calculations for converting time between different formats, for calculating Julian centuries and the ephemeris correction, for calculating significant moments of the day that have astronomical significance and polar-coordinate conversion. The following member functions would be implemented:
static double zoneFromLongitude(struct AstroLocale locale)
Calculates the time zone from a given locale (latitude and longitude) and returns it in degrees.
double universalFromLocal(double localTime, struct AstroLocale locale)
Returns the Universal Time from the Local time by at the given locale.
double localFromUniversal(double universalTime, struct AstroLocale locale)
Returns the Local Time from Universal Time.
double standardFromUniversal(double universalTime)
Returns the Standard Time from Universal Time.
double universalFromStandard(double standardTime)
Returns the Universal Time from Standard Time.
double standardFromLocal(double localTime, struct AstroLocale locale)
Returns Standard Time from Local Time.
double localFromStandard(double standardTime, struct AstroLocale locale)
Returns Local Time from Standard Time.
double ephemerisCorrection(double time)
Returns the corrections based on the astronomical ephemeris, which computes the secondary realizations based on lunar observations and the Cesium atomic clock.
double dynamicalFromUniversal(double time)
Returns the Dynamical(or Ephemeris) Time from Universal Time by applying the Ephemeris Correction to it.
double universalFromDynamical(double time)
Returns Universal Time from Dynamical Time.
double julianCenturies(double time)
Returns the Julian Centuries since January 1, 2000 12:00PM.
double obliquity(double time)
Computes the obliquity of the ecliptic.
double equationOfTime(double time)
Calculates the difference between the apparent solar time and the mean solar time. The equation of time results from the two superposed astronomical causes of the obliquity of the ecliptic and the eccentricity of Earth's orbit which causes a non-uniformity in the apparent daily motion of the Sun relative to the stars.
double apparentFromLocal(double localTime, struct AstroLocale locale)
Returns Apparent Time(calculation of time based on the position of the sun) from Local Time.
double localFromApparent(double apparentTime, struct AstroLocale locale)
Returns Local Time from Apparent Time.
double siderealFromMoment(double time)
Returns the sidereal time from the current moment considering the precession of equinoxes.
double declination(double time, double eclipticLatitude, double eclipticLongitude)
double rightAscension(double time, double eclipticLatitude, double eclipticLongitude)
These functions compute the polar coordinates, in degrees, from equatorial coordinates.
astrosolar.h
Contains functions based on the astronomy of the Sun. As of now, the features required for implementing the Islamic Calendar have been specified in this header file. Other functions/features would be appended later on as per the need of other calendars.
double aberration(double time)
Returns the value in degrees considering the effect of the movement of the Sun to about 20.47 seconds of the arc during the time its light is en route to the Earth.
double nutation(double time)
Returns the value in degrees, compensates for the small irregularity due to the precession of equinoxes.
double solarLongitude(double time)
Returns the equatorial longitude of the Sun.
double solarAnomaly(double time)
Computes solar anomaly observed in the celestial sphere.
double sineOffset(double time, struct AstroLocale locale, double angleDepression)
Computes the offset of the sine of the angle of depression of the Sun at the time of twilight.
double approxTimeOfTwilight(double time, struct AstroLocale locale, double angleDepression, bool early)
Returns an approximate time at which twilight would occur.
double timeOfTwilight(double approxTime, struct AstroLocale locale, double angleDepression, bool early)
Returns the precise time (precision of up to 30seconds) at which the twilight would occur.
double dawn(int time, struct AstroLocale locale, double angleDepression)
Returns the time at which dawn is observed.
double dusk(int time, struct AstroLocale locale, double angleDepression)
Returns the time at which dusk is observed.
astrolunar.h
Contains functions based on the astronomy of the Moon. The Islamic Calendar is a lunar calendar which is based on the sightings of the crescent and observations of the moon. The lunar crescent visibility criteria defined by S.K. Shaukat has been used to derive the astronomical implementation of the calendar.
double nthNewMoon(int n)
Returns the date on which the nth new moon would be observed.
double meanLunarLongitude(double time)
Computes the mean lunar longitude (without considering the effects contributed by the other heavenly bodies in the Celestial Sphere); it returns the value in degrees. The moon is assumed to revolve around the Earth in a circle while calculating the mean lunar longitude.
double lunarElongation(double time)
Returns lunar elongation, i.e., the angular distance of the moon, east of the sun.
double lunarAnomaly(double time)
Computes lunar anomaly.
double moonNode(double time)
Computes the angle of orbital nodes of the moon, i.e. the points where the orbit of the moon crosses the ecliptic.
double lunarLongitude(double time)
Calculates the lunar longitude considering the effects of the Sun, Jupiter, Venus, precession of equinoxes, flattening of the Earth at the poles and the corrections imposed on the mean lunar longitude to make it compatible with the elliptical orbit of the Moon around the earth.
double lunarLatitude(double time)
Calculates the latitude of the moon, considering the effects of Jupiter, flattening of Earth near the poles, and a few other complex factors as derived from Cassini's Law.
double lunarPhase(double time)
Returns the phase of the moon in degrees.
double lunarDistance(double time)
Returns the distance of the moon from the Earth at a given time.
double lunarParallax(double time, struct AstroLocale locale)
Calculates the lunar parallax at a given time as seen from a locale.
double lunarAltitude(double time, struct AstroLocale locale)
Calculates the geocentric lunar altitude in degrees, at a given time as seen from a locale.
double lunarAltitudeTopocentric(double time, struct AstroLocale locale)
Calculates the topocentric lunar altitude at a given time as seen from a locale.
bool lunarCrescentVisibility(int time, struct AstroLocale locale)
Returns whether the lunar crescent is visible from the locale at a given time.
int visibleCrescentBefore(int time, struct AstroLocale locale)
Calculates the date of the same month on which the crescent was visible before the given time, it, therefore, returns the date on which the lunar crescent had just met its visibility criteria.
The astronomical functions have been translated/derived from the publicly available Lisp Code of Calendrical Calculations by Edward M. Reingold on the Illinois Institute of Technology website.
The Islamic Calendar
The header file for defining the observational Islamic Lunar calendar is kcalendarsystemislamiclunar.h. It defines two classes:
KCalendarSystemIslamicLunar
Class definition in the public domain, publicly inherited from KCalendarSystem. It re-implements the virtual functions defined in the KCalendarSystem class. The re-implemented functions are defined in the public domain of the class.
virtual QString calendarType() const
Returns the calendar system type.
virtual QDate epoch() const
Returns a QDate holding the epoch of the calendar system. Islamic epoch is defined on 16th July 622 AD, which is Julian Day 1949440.
virtual QDate earliestValidDate() const
Returns the earliest date valid in this calendar system implementation, i.e. the epoch of the calendar system as the Islamic calendar is not proleptic.
virtual QDate latestValidDate() const
Returns the latest date valid in this calendar system implementation, i.e. 29th December 9999.
virtual bool isValid(int year, int month, int day) const
Returns whether a given date is valid in this calendar system.
virtual bool isValid(const QDate &date) const
Returns whether a given date is valid in this calendar system.
virtual bool isLeapYear(int year) const
Returns whether a given year is a leap year.
virtual bool isLeapYear(const QDate &date) const
Returns whether a given year(taken from the QDate) is a leap year.
virtual QString monthName(int month, int year, MonthNameFormat format = LongName) const
Gets specific calendar type month name for a given month number If an invalid month is specified, QString() is returned.
virtual QString monthName(const QDate &date, MonthNameFormat format = LongName) const
Gets specific calendar type month name for a given date.
virtual QString weekDayName(int weekDay, WeekDayNameFormat format = LongDayName) const
Gets specific calendar type week day name. If an invalid week day is specified, QString() is returned.
virtual QString weekDayName(const QDate &date, WeekDayNameFormat format = LongDayName) const
Gets specific calendar type week day name.
virtual int weekDayOfPray() const
Returns the weekday of pray for this calendar system, i.e. Friday.
virtual bool isLunar() const
Returns whether the calendar is lunar. (True)
virtual bool isLunisolar() const
Returns whether the calendar is lunisolar. (False)
virtual bool isSolar() const
Returns whether the calendar is solar. (False)
virtual bool isProleptic() const
Returns whether the calendar is proleptic, i.e, supports dates before the epoch. (False)
KCalendarSystemIslamicLunarPrivate
Class definition in the private domain, publicy inherited from KCalendarSystemPrivate. It re-implements the virtual functions defined in the KCalendarSystem class. The re-implemented functions are defined in the public domain of the class.
virtual KLocale::CalendarSystem calendarSystem() const
Returns the calendar type.
virtual void loadDefaultEraList()
Loads the era supported by this calendar system.
virtual int monthsInYear(int year) const
Returns the number of months in the year used by this calendar system.
virtual int daysInMonth(int year, int month) const
Returns the number of days in a month used by this calendar system.
virtual int daysInYear(int year) const
Returns the number of days in a year used by this calendar system.
virtual int daysInWeek() const
Returns the number of days in a week used by this calendar system.
virtual bool isLeapYear(int year) const
Checks whether a year is a leap year or not.
virtual bool hasLeapMonths() const
Returns true is this calendar system has leap months. The Islamic calendar doesn't have leap months.
virtual bool hasYearZero() const
Returns true is this calendar system uses year 0. The Islamic calendar doesn't have a year 0.
virtual int maxDaysInWeek() const
Returns the maximum number of days in a week in this calendar system, i.e, 7.
virtual int maxMonthsInYear() const
Returns the maximum number of months in a year in this calendar system, i.e. 12.
virtual int earliestValidYear() const
Returns the earliest valid year in this calendar system, i.e., year 1.
virtual int latestValidYear() const
Returns the latest valid year in this calendar system, i.e., year 9999.
virtual QString monthName(int month, int year, Locale::DateTimeComponentFormat format, bool possessive) const
Gets specific calendar type month name for a given month number If an invalid month is specified, QString() is returned.
virtual QString weekDayName(int weekDay, KLocale::DateTimeComponentFormat format) const
Gets specific calendar type weekday name for a given month number If an invalid weekday is specified, QString() is returned.
Astronomical Implementation
Re-implementations of the functions dateToJulianDay() and julianDayToDate() using the functions defined in the Astro Library.
bool julianDayToDate(int jd, int &year, int &month, int &day) const
Gets the date in this calendar system from the Julian day. The astro library function visibleCrescentBefore() is used to get the Julian day when the visible crescent was observed on or before the jd. The number of months elapsed since the Islamic epoch are then calculated and are used to get the year and month:
- Year = elapsedMonths/12 + 1
- Month = elapsedMonths%12 + 1
- Day = jd - day returned by visiblecrescentbefore() +1
The function returns false if it encounters an invalid date at any point during the calculations, otherwise it returns true.
bool dateToJulianDay(int &jd, int year, int month, int day) const
Gets the Julian day number corresponding to a given date in this calendar system. The astro library function visibleCrescentBefore() is used to get the Julian day when the visible crescent was observed on or before a particular date. The date passed as an argument to the visibleCrescentBefore() function is calculated as:
- Islamic epoch + the number of days elapsed since the start of the calendar to median of the current month
The Julian day is then calculated by adding to the value returned by the visibleCrescentBefore() function with the aforementioned argument.
The function returns false if it encounters an invalid date at any point during the calculations, otherwise it returns true.
The calculations for implementing the Islamic Lunar Calendar have been derived from the public domain Lisp code/Mathematical functions of Calendrical Calculations by Edward M. Reingold on the Illinois Institute of Technology website.