Jump to content

KDE Core/Astronomical Calendars

From KDE Community Wiki

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:

KCalendarSystem

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.

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

Calendar Systems

Retrieved from "https://community.kde.org/index.php?title=KDE_Core/Astronomical_Calendars&oldid=12123"