Observational Islamic Lunar Calendar

After coding the astro library, the next step was to implement the astronomical calculations in the Islamic Calendar. The arithmetical Islamic Calendar had already been defined in the KCalendarSystem API, to implement the astronomical calculations, functions like dateToJulianDay() and julianDayToDate() had to be modified.

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.

virtual bool isLunisolar() const
Returns whether the calendar is lunisolar.
virtual bool isSolar() const
Returns whether the calendar is solar.

virtual bool isProleptic() const
Returns whether the calendar is proleptic, i.e, supports dates before the epoch.

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.

Astro Library

While I was programming the astronomical functions, I had to reconsider some function definitions to match the compatibility with the KCalendarSystem API. The function definitions and their functionality are mentioned in the following post:

astro.h
Astronomical functions require the geographical latitude and longitude for most of their calculations. KDECore does not have any sort of data functionality that would use the geographical latitude and longitude. The only reliable way to get this data is to ask the user to input it while defining the KDE locale (as in KStars, etc). I am yet to talk regarding the feasibility of this feature with my mentor, John Layt, and then decide upon the method to proceed further on this. Until then, I have defined a structure in the header file and would be using this structure as an argument to member functions requiring geographical latitude and longitude. The main reason of using a structure over an enum was due to the fact that I can define the data type in the structure and wouldn't require static casting of data while handling the calculations of latitude and longitude.

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.

int roundOff(double value)
Rounds off the double value to integer value

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.

double estimatePriorSolarLongitude(double longitude, double time)
This function has an important role to play in implementing astronomical solar calendars, as it determines a particular solar longitude on or before the given date. The solar longitude can correspondingly help to find the day of the New Year as per the astronomical calendar.

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.

double newMoonBefore(double time)
Returns the moment of a New Moon occurrence before the given time

double newMoonOnOrAfter(double time)
Returns the moment of a New Moon occurrence at or after the given time

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.