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.

Student Proposal

http://www.google-melange.com/gsoc/proposal/review/google/gsoc2011/yuvrajtomar/1

Schedule

Due to delays starting due to student exams and mentor job change the schedule is subject to some change. It will also be flexible based on the research into the required astro code, if the requirements are more complex than expected then the expected deliverables will be reduced to only 2 calendar systems.

Broad plan:

Work in 3 week mini-sprints to implement each calendar, then merge results at end into a stand-alone astro library. This ensures we have clear deliverables with tangible usable results, and will make appraisal easier.

• Implement Islamic Calendar
  • Research Islamic calendar, determine features required, determine astro calculations required, document on Islamic Calendar page
  • Implement required astro functions and test cases for Islamic calendar in kdelibs/kdecore/date/astro
  • Implement Islamic calendar class and test cases

• Implement Chinese Calendar
  • Research Chinese calendar, determine features required, determine astro calculations required, document on Chinese Calendar page
  • Implement required astro functions and test cases for Chinese calendar in kdelibs/kdecore/date/astro
  • Implement Chinese calendar class and test cases

• Implement Hindu Calendar
  • Research Hindu calendar, determine features required, determine astro calculations required, document on Hindu Calendar page
  • Implement required astro functions and test cases for Hindu calendar in kdelibs/kdecore/date/astro
  • Implement Hindu calendar class and test cases

• Implement Astro library
  • Review implemented astro functions and decide how to transform into stand-alone Qt library.
  • Review functions required by other KDE apps and see if library meets these
  • Performance improvements
  • Fast vs accurate versions of routines

Week 1 (May 24) – Exams, some research and prep

Week 2 (May 30) – Exams, some research and prep

Week 3 (June 6) – Research Islamic

Week 4 (June 13) – Implement Islamic Astro

Week 5 (June 20) – Implement Islamic Calendar

Week 6 (June 27) – Research Chinese

Week 7 (July 4) – Implement Chinese Astro

Week 8 (July 11) – Implement Chinese Calendar

Mid Term Evaluation (July 15) – Expect Islamic to be completed, Chinese to be completed if no complications, otherwise sufficiently advanced.

Week 9 (July 18) – Research Hindu

Week 10 (July 25) – Implement Hindu Astro

Week 11 (August 1) – Implement Hindu Calendar

Week 12 (August 8) – Implement Astro library

If possible 1-2 extra weeks for Astro Library, Documentation and clean-up.

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.

Astronomical Library

One goal of the project is choosing or producing a common astronomical library for KDE libraries and applications to use for basic needs. There are several places in KDE that do simple astronomical calculations and duplicate the required code. If kdelibs is implementing or requiring astronomical code then it makes sense to share that code with the other apps.

The first priority will be determining what astronomical functions the various calendars will require which will set the benchmark for the minimal requirements of a library.

Once the requirements are set, then analysis can begin on existing code/library options. Research will be undertaken to locate and identify all options both in KDE and outside. All code considered must conform to the kdelibs licensing policy or be able to be relicensed to LGPL2.1+. Options will be considered depending on size, accuracy, speed, quality and maintenance.

If an external library is found to meet all requirements then this will be chosen and a Qt-style api wrapper created.

If no suitable external option is found then a KDE library will be developed, reusing existing code from KDE where suitable. While initially developed as private classes inside kdelibs/kdecore/dates/astro, this code will eventually be moved to kdesupport as a standalone library. As a consequence, all code should be pure Qt.

Possible external options are

• libnova - quality library with all required code for everyone, but probably too large at 3.5MB
• libicu - so-so library with all required code for calendars only, but 17.8MB including all other ICU functions is just too big
• AA+ has an unacceptable license

This suggests that there is no suitable library at this time.

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

It is perfectly acceptable to copy code form other projects and modify it to suit our requirements. The only requirement is that the source code have an acceptable license per the kdelibs licensing policy (although LGPL is preferred) and the copyright is properly acknowledged. Consequently existing KDE code should be given preference, although a request may be needed to relicense it from GPL to LGPL.

If looking to use KStars code then I strongly recommend getting in touch with the maintainers Victor Carbune ([email protected]) and Akarsh Simha ([email protected]) as they have expressed interest in working together on it.

• 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
• http://aa.usno.navy.mil/software/novas/novas_info.php

Islamic code implementations:

• http://www.ojuba.org/wiki/hijra/%D8%A7%D9%84%D8%B5%D9%81%D8%AD%D8%A9_%D8%A7%D9%84%D8%A3%D9%88%D9%84%D9%89
• http://projects.arabeyes.org/project.php?proj=ITL
• http://kde-apps.org/content/show.php/Prayer+Times+Plasmoid?content=141407
• http://kde-apps.org/content/show.php/Mawakit?content=128606
• http://kprayertime.sourceforge.net/
• http://code.google.com/p/salatinoid/

Calendar Systems

• Islamic
• Hindu
• Chinese