Open source Kālacakra and Tibetan calendar software

Traditional karaṇa calculation system

    Tibetan gnomom, thur shing

A current project for the Central University of Tibetan Studies (previously the Central Institute of Higher Tibetan Studies) in Sarnath requires the use of a calendar, based on the descriptions given in the Kālacakra Tantra and its commentary, the Vimalaprabhā, but brought up to date using modern, accurate astronomy. This calendar will use traditional calculation methods, but with epoch data calculated using modern science. To distinguish it from others, I'll refer to it here as the Kālacakra karaṇa calendar.

Part of the intention here is to allow students and others to try out directly the observational techniques that the Vimalaprabhā describes as being necessary to adjust the accuracy of the calendar and ensure that the longitude of the Sun that it uses is correct. For anybody studying the calendar as given in the tantra, to move directly to an implementation using modern mathematics as well as modern scientific astronomy (such as the Kālacakra calendar given elsewhere on this site) is a major jump. The use of a calendar based on traditional calculations but with accurate astronomy makes a useful intermediate step. For people studying the traditional calculation methods, it also makes a comparison with modern Tibetan calendars easier and more meaningful.

This calendar will be both calculated by hand and also computerised. As it will be used for teaching purposes, it makes sense that the source code for the relevant software be made open source and available to anybody interested. As with any open source project, comments, suggested changes and additions will all be welcome. Please address these to Edward Henning. In particular, if you find any errors, please report these. Computers are only human, after all.

To download the software and its source code, together with its minimalist documentation:

Click below for:
Version 1.00Original version; only one epoch, 2009
Version 1.01Some tidying up, more comments; includes original tantra epoch, 806 CE.
Version 1.02Now includes code for using the solar longitude at both the end of the solar and end of the lunar day, for planetary calculations. The lunar day method is set as default and is the method used in the Kālacakra Tantra. Also in keeping with the Tantra, rather than later Tibetan traditions, an intercalary month is identified as a repeat of the previous rather than following month. Lunar month names are now switchable between Tibetan and Sanskrit.
Version 1.03Epoch data for the calendar as described by Śākya Śrībhadra now included. See this page for further details on this.
Version 1.04New Win32 command line version to support Windows Vista and Windows 7. See the "Windows compatibility" box here for further details. This version 1.04 is otherwise functionally the same as v.1.03.

As an aid to understanding the calculations, a set of example calculations for a single day are given on this page.

Origin of the software.

As part of my work with the Kālacakra and Tibetan calendars during the last 30+ years, I have written software for performing the main, and many other, calculations described in Tibetan texts. Before the age of the PC this was done on a programmable calculator, but since 1984 in the C language on PCs. This software has been used to calculate the traditional Tibetan calendars given here on this site, but contains much other functionality – it was primarily a research tool. It can calculate for both the original karaṇa system (byed rtsis) given in the tantra and the siddhānta systems (grub rtsis) devised later in Tibet. It also handles 16 different epochs from several traditions. An open source version of this software is available on this other page. This calculates the main Tibetan calendars for the Phugpa and Tsurphu systems, as well as the historically interesting calendar of Zhonnu Pal, the "Error Correction" system.

The present karaṇa calendar software made available on this page is based on this original program, but with most of the functionality removed. It only performs the karaṇa calculations, and at present uses just three sets of epoch data. One of these is modern, for the mean new Moon on Tuesday 24 February 2009; this is at the beginning of the month of Caitra (nag pa zla ba), the month during which the mean Sun enters Aries. The data used are given in the documentation. From the second version onwards, the software also includes the epoch data from the original Kālacakra Tantra. This is useful for comparison purposes, and possibly also for anybody looking into the work of early writers such as Śākya Śrībhadra, whose epoch data has also recently been added.

One feature in this calendar that would have been absent from a real Kālacakra calendar is the inclusion of Chinese symbolic information when a full year calendar is printed to disk. This is included because the main reason for producing this is comparison with Tibetan calendars, most of which include Chinese data. Perhaps a switch will be included later enabling this to be turned off. Another difference worth pointing out concerns the calculation of planetary positions. The longitude of the Sun is needed for this, and most Tibetan calendars take the mean longitude at the end of the solar day; the original Kālacakra method uses the mean longitude at the end of the lunar day. Presently, this software uses the lunar day method, but a switch will be added later to enable both systems. This is particularly important as some Tibetan systems also use the lunar day solar longitude, even though the method of calculation is incompatible with the method of calculating the mean planetary posistions (multiplying by a count of solar days).

The first versions of this software were developed using the Open Watcom C/C++ compiler version 1.8. The most recent version 1.04 has been developed using Open Watcom C/C++ version 1.9.

(Please note that both these open source programs have been adapted from the main software mentioned above, that was written and tested over many years. Hacking and cutting and pasting such code to produce new programs inevitably will introduce some errors, such as an old routine accidentally incorporated which was removed towards the end of December 2009. Much testing is going on, and hopefully the code will settle down very soon. The main results produced are all correct – it is hopefully only unusual conditions that might produce errors.)

Differences between the "modern karaṇa" and Tibetan calendars.

There is a strong case for claiming that the modern karaṇa calendar is what modern Tibetan calendars should be. There are three key differences between this calendar and a current Tibetan calendar. In this present calendar:

1. The months are corrected.
2. The basic astronomy is accurate.
3. The calculations follow the karaṇa rather than the artificial siddhānta system.

1. The months are corrected.

The main creators of Tibetan calendars considered that the winter solstice is observed in Tibet between two and three weeks (depending on the tradition) before it is in India. This caused them to set the longitude of the Sun wrongly, and consequently the definitions of the months. The month of Caitra is counted as the third Tibetan month, but in this calendar it is the second. This was also the case with the calendar produced by Zhonnu Pal – see some more information about this here. He did not accept the different timing of the solstice, and followed exactly the method given in the Kālacakra literature for correcting the longitude of the Sun. He numbered Caitra as the second month, as it should be.

2. The basic astronomy is accurate.

All such calendar systems use mean data for solar, lunar and planetary positions for a specific moment in time, known as an epoch. This is usually – I have only a couple of times seen it done any other way – the time of mean new Moon at the beginning of the month of Caitra in a particular year.

To calculate details for a calendar some period later, mean motions are first used to derive mean positions at later times, and then stepping methods are used to account for the eccentricity of the movements of the bodies concerned. The accuracy of the calendar that you calculate at any time therefore depends on two things: the accuracy of the initial mean data for the epoch and the accuracy of the calculations used to determine later positions.

The main Tibetan calendar systems are the Phugpa and Tsurphu systems, and these had their basic epoch data set in the 15th century. These data also included erroneous longitudes for the Sun due to the belief that the solstice appeared earlier in Tibet than India. The calculation systems are also not perfect, and therefore further errors have accumulated over time – although many later epochs have been used by writers, their raw data have never been adjusted, and you could take the earliest available epoch data for these systems and calculate forward to modern times. This is in fact what they did; texts published in, say, the last century used epoch data that were simply calculated forwards from some earlier text. There was no correction on the basis of observation, whatsoever. Consequently, the solar longitude in the Phugpa system started out with an error of about 23° and is now out by about 36°!

The present calendar uses a very recent epoch – February 2009 – and the epoch data have been calculated to a high level of accuracy, using modern techniques. The calculation system used is the traditional one given in the Kālacakra literature, that the Tibetans call karaṇa-calculation (byed rtsis). This has a significantly more accurate value for the mean monthly change in solar longitude than the siddhānta-systems (grub rtsis) used in modern Tibetan calendars, and a very slightly less accurate measure for the length of the lunar month. More on this in the next section.

3. The calculations follow the karaṇa rather than the artificial siddhānta system.

The basic calculations given in the Kālacakra Tantra and the Vimalaprabhā are the karaṇa system, but many Tibetans came to the surprising view that there had been another more accurate system of calculation given in the missing Kālacakra Mūlatantra. However, the key values that they ended up using in the siddhānta system that they subsequently created are readily available in the normal tantra, and one of them is clearly an approximation.

A lunisolar calendar, such as the Kālacakra or Tibetan calendars, depends on the relationship between three basic quantities:

a. The length of the solar, or natural, day.
b. The relative motion of the Sun and Moon; ie., the length of the synodic month (new Moon to new Moon) and lunar days (there are 30 lunar days in one lunar month).
c. The motion of the Sun, typically described by the length of the year.

If you have the relationship between any two pairs of these three, the third relationship can easily be calculated. The basic relationships used in the Kālacakra and Tibetan calendars are the length of the synodic month in terms of solar days (a&b) and the mean motion of the Sun in one synodic month (b&c).

In verse 27 of the first chapter of the Kālacakra Tantra a method is given for calculating the true month (zla dag). The number of years since the epoch is multiplied by 12 and then the number of extra months (since Caitra) in the year is added. You then convert to lunar months by multiplying by 1 265. This converts a count of solar months to a count of (shorter) lunar months, using the relationship that 67 mean lunar months = 65 mean solar months. When the fractional part carries over, this indicates an intercalary month, one during which the Sun does not change sign. This is simply a useful and easily calculated approximation, which, given accurate epoch data, remains reliable for determining intercalary months for a little over 40 years.

This approximate relationship has been taken by the creators of the siddhānta calculation systems as being exact, and from it can easily be calculated the mean motion of the Sun per lunar month as used in that system. This was a very unfortunate mistake by the Tibetan calendar makers, although of course they were in no position to be able to judge which of these relationships was the most accurate. The numbers are easily derived:

On units: Angular measure, such as the longitude of the Sun, is described in terms of 27 lunar mansions around the ecliptic, each of 13 13°. Time is measured in terms of solar days, expressed by a count of weekdays: Saturday, Sunday, Monday, etc. Saturday is represented by 0, Sunday by 1, etc. Similarly to western degrees, minutes and seconds, or hours, minutes and seconds, these main units are subdivided.

Each lunar mansion or solar day is divided into 60 nāḍī (chu tshod), and each of these is further divided into 60 pala (chu srang). As a measure of time, the nāḍī is a little less than half an hour in length at 24 minutes, and the pala is 24 seconds. Each pala is further divided into 6 breaths (dbugs, svasa), each of four seconds duration. The term breath is used as it is considered to be the length of time for a cycle of inhalation and exhalation in a mature person, free from illness, and breathing naturally. For both angular measure and time, each breath is divided into further sub-units, but these are variable in number depending on the context.

To represent mixed-radix values such as these in a western language, I follow the example of modern writers such as O. Neugebauer when he represents ancient Babylonian sexagesimal values. The integer part of the value is separated from the fractional parts by a semicolon, and the fractional parts are themselves separated by commas. One necessary extension to Neugebauer's method is this: where the values of the fractional units (denominators or base numbers) are not clear (for example, the final unit mentioned above was said to depend on context), they will follow in brackets. So, a value of: 3;10,49,2,347 (60,60,6,707) will represent a Tuesday, at 10 nāḍī, 49 pala, etc. after mean daybreak. Usually it is only the last fractional unit that should be uncertain, and so that value will normally simply be written: 3;10,49,2,347 (707).
The month calculation is based on: 67 lunar months = 65 solar months

∴ 67 × 12 = 804 lunar months = 65 solar years

In one lunar month, the Sun moves: 65 × 27 ÷ 804 lunar mansions =>

1755 ÷ 804 = 2 rem. 147
147 × 60 = 8820 ÷ 804 = 10 rem. 780
780 × 60 = 46800 ÷ 804 = 58 rem. 168
168 × 6 = 1008 ÷ 804 = 1 rem. 204
204 × 67 = 13668 ÷ 804 = 17 rem. 0

-> 2;10,58,1,17 (67)

This is the mean monthly figure for the motion of the Sun used in the Tibetan siddhānta calculations. (The karaṇa value is: 2;10,58,2,10 (13))

The Tibetan calendar makers fared better with verse 40 of the first chapter. This gives a method for converting a count of lunar days into one of solar days using the relationship that 11,312 mean lunar days = 11,135 solar days. This is actually expressed as multiplication by the fraction: 1 - (164 + 164x707)

The main calculations given in the Tantra use the relationship that 10,800 mean lunar days = 10,361 mean solar days. This is almost certainly based on the standard cycle of 30 lunar years in the Islamic calendar. The origin of the relationship in verse 40 is not clear, but the Tibetans used this for their siddhānta calculation system, and it gave a small improvement in the length of the synodic month – by just less than three seconds. Again, the derivation is easy:

11312 lunar days = 11135 solar days.

∴ 11312 lunar months = 11135 × 30 solar days = 334050 solar days

5656 lunar months = 167025 solar days

1 lunar month =>

167025 ÷ 5656 = 29 rem. 3001
3001 × 60 = 180060 ÷ 5656 = 31 rem. 4724
4724 × 60 = 283440 ÷ 5656 = 50 rem. 640
640 × 6 = 3840 ÷ 5656 = 0 rem. 3840
3840 × 707 = 2714880 ÷ 5656 = 480 rem. 0

-> 1;31,50,0,480 (707)

This is the mean figure for the monthly change in weekday used in the Tibetan siddhānta calculations. As the first figure represents weekdays, the value 29 derived on the top line is reduced modulo 7 and becomes 1. The "just less than three seconds" improvement that this represents over the karaṇa value lies in the 480 fractional part. This is 480707 of a "breath"; one breath being four seconds in length.

Accuracy of the traditional calculations

It is interesting to compare the mixed-radix calculations of traditional Tibetan calendars with modern methods. The key factors are the longitudes of the Sun and Moon, and in the Kālacakra calendar given elsewhere on this site, the calculation methods used are highly accurate. Those for the Sun are based on the VSOP87 solution, devised by P. Bretagnon and G. Francou. Those for the Moon are based on the modern ELP/MPP02 solution. These calculations have been exhaustively tested and the calendar, which is perhaps best refered to here as the "algebraic" calendar, can be considered reliable.

So, how does the calendar presented here using traditional calculation methods compare? Its epoch data for February 2009 are calculated to high precision, and so any deviation from the algebraic calendar must be a direct result of the traditional calculation methods. The present traditional calendar is calculated for the longitude of Sarnath, and so an algebraic calendar was produced for the same longitude for 2010. A critical feature of Tibetan calendars is that some lunar dates are omitted and some duplicated. A comparison of these for the year starting in early 2010 between the traditional and algebraic calendars is shown in the following table.

217228, 172,24
43 2, 1518
56, 28235, 2921
72, 24201, 2718
86, 2894, 2911
1026 27
12141015, 248, 28

The lunar dates on which both calendars agree are shown in bold, and there are only four of them. This is not a good result from the point of view of the traditional calculations, particularly as these omitted and duplicated days are such a central feature in determining the structure of the calendar. It appears that the traditional calculations are simply not up to the task.

I thought that the reason for this inaccuracy might lie in the fact that the step values used to adjust for the eccentricity of the Sun are not particularly accurate (see Kālacakra and the Tibetan Calendar, p. 37). However, although substituting more accurate values caused different lunar dates to be omitted or duplicated, there were still only four that agreed with the algebraic calendar. If further investigation pinpoints a particular feature of the traditional calculations that causes this inaccuracy (or, of course, any programming error), this will be described on this web page at a later date.

    E. Henning.
    Last updated 25 July 2013.
    Return to calendar introduction.