View source for 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 by the Mentor the schedule is subject to some change.  It will also be flexible based on the research into the required astro code.

Broad plan:

* Implement Islamic Calendar
** Research Islamic calendar, determine features required, determine astro calculations required, document on [[/Islamic|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|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|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) –

Week 2 (May 30) – Research Islamic

Week 3 (June 6) – Implement Islamic Astro

Week 4 (June 13) – Implement Islamic Calendar

Week 5 (June 20) – Research Chinese

Week 6 (June 27) – Implement Chinese Astro

Week 7 (July 4) – Implement Chinese Astro

Week 8 (July 11) – Implement Chinese Calendar

Mid Term Evaluation (July 15) – Expect Islamic and Chinese to be completed

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

== 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.

== 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.  [http://books.google.co.uk/books?id=uJ4JhGJANb4C&printsec=frontcover&dq=Explanatory+Supplement+to+the+Astronomical+Almanac%22+revised+edition+2006,+edited+by+P.+Kenneth+Seidelmann&source=bl&ots=zMUKKb8Vx3&sig=f2xDaMaXSGdDgjBfD9bL_EB2AQc&hl=en&ei=Cp-4TdiaJ4iz8QPh6aw2&sa=X&oi=book_result&ct=result&resnum=4&ved=0CDgQ6AEwAw#v=onepage&q&f=false 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 [http://libnova.sourceforge.net/ libnova project] is a full implementation of the Meeus book.
* The [http://bugs.icu-project.org/trac/browser/icu/trunk/source/i18n ICU Unicode CLDR implementation] includes all the required astro functions and calendar calculations for the Chinese and Islamic calendars.
* [https://projects.kde.org/projects/kde/kdeedu/kstars KDE Stars] has a lot of astronomical code.
* The KDE Marble Virtual Globe has various astronomical functions in the main [https://projects.kde.org/projects/kde/kdeedu/marble/repository/revisions/master/show/src/lib libmarble code] and in the [https://projects.kde.org/projects/kde/kdeedu/marble/repository/revisions/master/show/src/plugins/render/satellites Satellite plugin] and [https://projects.kde.org/projects/kde/kdeedu/marble/repository/revisions/master/show/src/plugins/render/stars Stars plugins].
* The [https://projects.kde.org/projects/kde/kdebase/kde-workspace/repository/revisions/master/show/plasma/generic/dataengines/time Plasma Time Dataengine] includes various astronomical functions for sunrise and sunset.
* The [https://projects.kde.org/projects/kde/kdepimlibs/repository/revisions/master/show/kholidays 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|Islamic]]
* [[/Hindu|Hindu]]
* [[/Chinese|Chinese]]