KDE Core/Astronomical Calendars

GSoC Project: Support for astronomical calendar systems

Brief explanation: Add support for astronomical calendar systems. KDE is unique in the Linux eco-system for providing support for alternative calendar systems, such as the Hebrew, Islamic Civil, and Japanese calendar systems. Support for such calendar systems is standard in the Windows and Mac worlds. However, KDE does not as yet support calendar systems that require astronomical calculations, such as the Chinese and Islamic Lunar calendars, This project would fill this gap.

Expected results: Documentation, design and production of Chinese, Indian, Islamic and Jalali/Persian calendar systems and their numerous derivatives. The documentation to be of a high enough standard to submit to various standardization bodies. Production of an astronomical library for calculating sunrise, sunset and moon phase (and any other useful calculations) for shared use between the calendar systems and other KDE libraries and applications such as KHolidays, KStars and Marble.

Knowledge Prerequisite: C++, especially an understanding of Binary Compatibility rules and good API design. Some knowledge of Celestial Mechanics and good mathematical literacy. Any experience with regular cultural use of astronomical calendars would be highly useful.

Required KDE Reading

Background knowledge you need about KDE and kdelibs:

• http://techbase.kde.org/Policies/Library_Code_Policy
• http://doc.trolltech.com/qq/qq13-apis.html
• http://techbase.kde.org/Policies/Kdelibs_Coding_Style
• http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C++

KCalendarSystem

• http://api.kde.org/4.x-api/kdelibs-apidocs/kdecore/html/classKCalendarSystem.html

KCalendarSystem was created in KDE2 as QDateTime does not provide calendar system localisation, and still doesn't in Qt4. It is hoped in Qt5 to merge the KDE code into QDateTime so KDE no longer has to provide separate date/time functions.

KCalendarSystem was originally a virtual base class providing common implementations for many functions. Specific calendars could derive from the class and override the base functions where required. The Private class (d-ptr) was only used for some common utility functions and data. This arrangement was good as it allowed 3rd parties to derive their own calendar class. Unfortunately a mistake in the 4.0 release meant no extra virtual slots were reserved for the base class and binary compatibility rules prevent new virtual slots from being added to the virtual table. Instead a virtual Private class had to be implemented with the calendar specific overloads for any new functions now being in the d-ptr instead of the derived classes. This unfortunately prevents any external calendar implementations, but this will be fixed up in KDE5.

All the calendar implementations, such as KCalendarSystemGregorian are private classes, the api only ever exposes the common base class api and apps only ever use the KClaendarSystem class. Instead a static factory function returns the correct derived implementation when requested. While this is good for ensuring apps never have to think about what calendar they are using or what class to use, it restricts us from directly having any functions in a calendar that are not common to all calendars. A way around this when special variables are required for just one calendar is to set the variables in the locale config file which the appropriate calendar will read and use, but these features can never be directly manipulated via the api.

Standards

The POSIX standard does not define any alternative calendar systems and POSIX implementations only work with Gregorian. For example, all the Linux/Unix command line commands and Gnome only support Gregorian as a result.

The Unicode CLDR standard defines support for alternative calendar systems and defines names (some inaccurately) for supported calendar systems, but does not actually define how to calculate those calendars. The ICU implementation of Unicode CLDR does implement the Unicode defined calendar systems, but these are poorly documented and in some cases appear to be incorrect.

The iCalendar standard defines a variable to hold the calendar system type but has never actually defined any alternative calendars or how they should work.

Apple supports alternative calendar systems and appears to use the Unicode CLDR and ICU standard implementations including their inaccuracies.

Microsoft supports alternative calendar systems, initially using their own inaccurate implementations, but now apparently using the Unicode CLDR or ICU implementations.

Available Resources

Books

I have copies I can lend if needed.

"Calendrical Calculations" 3rd Edition by Nachum Dershowitz and Edward M. Reingold. Note no code, formulas or data can be used from this book due to licensing conditions, but provides a good general background. I have doubts about the accuracy in sections of the book.

"Mapping Time" by E G Richards. A good general reader on calendars.

"Astronomical Algorithms" 2nd edition by Jean Meeus. The book on astronomical calculations, basis for libnova. http://www.willbell.com/math/mc1.HTM

"Explanatory Supplement to the Astronomical Almanac" revised edition 2006, edited by P. Kenneth Seidelmann. A handy reference. Google Books copy.

"The Amateur Astronomers Introduction to the Celestial Sphere" by William Millar. Good general introduction to celestial mechanics, but any similar book will do.

Code

• The libnova project is a full implementation of the Meeus book.
• The ICU Unicode CLDR implementation includes all the required astro functions and calendar calculations for the Chinese and Islamic calendars.
• KDE Stars has a lot of astronomical code.
• The KDE Marble Virtual Globe has various astronomical functions in the main libmarble code and in the Satellite plugin and Stars plugins.
• The Plasma Time Dataengine includes various astronomical functions for sunrise and sunset.
• The KHolidays library has some basic astronomical code for lunar phases and astro seasons.
• http://www.srrb.noaa.gov/highlights/sunrise/calcdetails.html

Calendar Systems

• Islamic
• Hindu
• Chinese