Open source software for the Tsurphu tradition of Tibetan calendar


An earlier Rumtek calendar, produced by Tsipa Gelek Dharge.
Open source software for calculating the main calendars in use in Tibet is available elsewhere on this web site. One of those is the Tsurphu calendar tradition that was developed in the Karma Kagyu school of Tibetan Buddhism. The original work on this was started by the 3rd Karmapa, Rangjung Dorje (rang byung rdo rje), in the end of the 13th and beginning of the 14th centuries. The full system as we know it today was devised by Jamyang Dondrup Wozer ('jam dbyangs don grub 'od zer) just over a hundred years later – the official date given is 1447. Unfortunately, his original writings seem to have been lost, but the Tsurphu tradition, or Tsurlug (mtshur lugs), has been well documented by: Karma Ngelek Tendzin (karma nges legs bstan 'dzin), the 14th Karmapa Thegchog Dorje (theg mchog rdo rje), Jamgon Kongtrul Lodro Thaye (kong sprul blo gros mtha' yas), and, the Jonang writer Banda Gelek ('ba' mda' dge legs).

In recent years, Tsurphu calendars have been published from Rumtek Monastery in Sikkim, the seat of the Karmapa in India. Unfortunately, the person responsible for doing this, Tsipa Gelek Dharge (rtsis pa dge legs dar rgyas), died a couple of years ago, and the smooth production of the calendar was interrupted as a result.

HH Karmapa wanted the calendar to continue publication, according to the specification given by Thegchog Dorje in his text, the gtsug lag rtsis kyi lag len gsal bar byed pa legs bshad nor bu'i phreng ba blo gsal mgrin rgyan. Software has been written to calculate this calendar, and this is made available on this page as open source. Also, the Tsurphu calendars that have been published on this web site for several years now have all been updated to be compatible with the full calendar. This entails a small change that is explained below.

The new Tsurphu calendar from Rumtek, cover design by HH Karmapa.

Download Tsurphu software

If you find any errors in this software, or have any comments, suggested changes or additions, please address these to Edward Henning. To download the software and its source code, together with basic documentation:

Click below for:
Version 1.20Original version, including all source code.
Version 1.20Original version, just the program.

This first version 1.20 of this software has been developed using Open Watcom C/C++ version 1.9. Unless any errors are found, apart from one requested feature, it is unlikely that there will be later versions. That feature would be to allow Unicode Tibetan output as well as the present Wylie transcription. The software is open source, under the terms of the MIT licence.

Structure of the program and calendar

Unlike some of the other software on this site, there is no initial need to select an epoch on starting the program. The one used by default is the 1852 epoch as given by Jamgon Kongtrul. His main siddhānta epoch data are given here.

One calculation difference between the software given here and that for main Tibetan calendars, including Tsurphu, is that, for the longitude of the Sun, the present program, instead of using the siddhānta calculations (grub rtsis), uses the original karaṇa calculations (byed rtsis) from the Kālacakra Tantra. This is specified by such writers as Thegchog Dorje and Jamgon Kongtrul. Why would they mix two systems in this way? A search for greater accuracy seems to be the answer.

When the Tibetans developed their siddhānta calculation systems, they thought that they were rediscovering a lost system that was fully accurate. The idea was that there had been a fully accurate system of calculation given in the (apparently lost, if it ever existed at all) Kālacakra Mūlatantra. Although it was not realised at the time, in fact, the new systems (Phugpa and Tsurphu) both improved slightly on the length of the lunar month, but the new figures for the length of the solar year were significantly less accurate than in the old karaṇa system. These are the two key values that underpin the calendar. Further information on the derivation of these values is available here.

On eclipses, the Sun and intercalary months: Eclipses are determined by first finding the difference between the longitude of the Sun and Rāhu at the time of full or new Moon. As the three errors in the 15th century indicated in the text to the left are close in value, it should have worked reasonably well, and no doubt eclipses were used as data points in establishing the calendar. It is interesting to note that in the middle of the 15th century, the Phugpa error in the Sun's longitude was even worse, at −20.5°; even early writers in that tradition commented on the use of the karaṇa Sun for eclipse prediction, but I have come across no comments in Phugpa writings about using the karaṇa Sun to replace the siddhānta Sun, as was done in the Tsurphu tradition.
One major problem associated with the use of the karaṇa Sun lies with intercalary months. These are determined by a simple calculation that is locked into the mean motion of the siddhānta Sun. Using the karaṇa Sun breaks this, and so the intercalary calculation – which was actually the basis for the development of the siddhānta system, and has not been changed – now gives intercalary months that disagree with an inspection of the mean longitude of the karaṇa Sun. This is a major logical inconsistency in the Tsurphu system. If the karaṇa Sun is more accurate, surely it should be used for determining intercalary months? Tsewang Namgyal clearly understood this when devising the semi-reformed Sherab Ling calendar; that uses yet another system of calculation for the longitude of the Sun, and Tsenam developed a new calculation for intercalary months that is compatible with this.
A critical event that is used by astronomers and calendar makers is an eclipse. A good example is the epoch given in the Kālacakra Tantra, mean new Moon on Monday 23 March 806. That was itself an eclipse day. From northern India, on the true new Moon day, the Tuesday, the Sun rose in partial eclipse – an excellent data point for a calendar maker! Important for an eclipse are the longitudes of the Sun (the Moon's is calculated from that of the Sun) and of the Moon's node, Rāhu (sgra gcan). In the middle of the 15th century, the error in the siddhānta Sun was −15.7° and for the karaṇa Sun −15.3°. As both systems use the same method for calculating the longitude of Rāhu, and as its error was at that time −17.1 °, no significant difference would have been observed in the accuracy of eclipse prediction using these two methods for the Sun's longitude.

However, due to different errors in the siddhānta and karaṇa calculations, the situation is now different. Currently, the error in the siddhānta Sun is −31.0°, for the karaṇa Sun −24.2°, and for Rāhu, −27.0°. Clearly, the karaṇa Sun would now be more reliable for eclipse prediction, and the trend in this direction was noticed a couple of hundred years ago. This appears to be the main reason that the karaṇa Sun replaces the siddhānta Sun in the Tsurphu calendar.

It should be pointed out that this makes no difference to the structure of the calendar – the same days are omitted or duplicated, the same months are intercalated, etc.

Jamgon Kongtrul gives a set of calculations that he calls "Combined siddhānta and karaṇa" (byed grub zung 'grel). These calculations use quite different values, and are not what is being used with the present Tsurphu calendar. However, test software that uses these calculations, together with source code, is available from this link for anybody interested in trying it out. (This has not been through particularly rigorous testing.)

The present Tsurphu program is called tcgbk.exe, and simply needs to be run from a command line prompt – it does not need to be installed. A description of how to operate the program is given in the documentation. That is available in the package containing the software, and also from this link.

In normal use, the program prints in a text file a calendar identical to those given as an archive on this web site, with a name such as tsa_2013.txt. Alternatively, the program can be started with an extra command, in which case two text files are written to disk; the second will have a name such as ts2_2013.txt. This file contains much more extensive information, and is designed for aid in printing and publishing a full calendar.

Of the two calendar files that the software can produce, the more simple one, such as tsa_2013.txt (which is taken here as an example) has the following structure:

Each file starts with a header describing the year in terms of the element and animal from Chinese symbolism:

New Year: 2013, Water-female-Snake

Each month has a header:

Tibetan Lunar Month: 1 - Wood-male-Tiger

Month: 1989;39
Anomaly: 18;45
Mean Weekday: 1;29,39,2,574
Mean Sun: 22;12,15,2,4

The first line describes the month, also with the element and animal from Chinese symbolism. The next four lines give data that are calculated for the mean new Moon at the beginning of the month, and are usually given in Tibetan almanacs. The first is the month count from the epoch together with the intercalation index. Next is the value for the (lunar) anomaly. The third figures are the value of the mean weekday at the new Moon – effectively the time of the mean new Moon. The fourth line is mean longitude of the Sun at mean new Moon.

Apart from omitted lunar dates, each lunar date has the following four, five or six lines:

1: Mon. Shatabhishaj/mon gru. Water-Earth; 11 Feb 2013
  Parigha/yongs 'joms, Vava/gdab pa, Tiger, li 1
  Solar: Earth-Monkey. Bi
  2;11,24 23;4,36 22;22,1 18;26,38 9;28,13
  From 1st to 15th, Demonstration of Miracles.
    zin phung

1: Mon. Shatabhishaj/mon gru. Water-Earth; 11 Feb 2013

The first line gives: the lunar date, the weekday, the lunar mansion (rgyu skar) at daybreak in Sanskrit/Tibetan, the element combination of the weekday and lunar mansion, and, the date in the Gregorian calendar.

Parigha/yongs 'joms, Vava/gdab pa, Tiger, li 1

The second line gives: the yoga in Sanskrit/Tibetan, the karana in Sanskrit/Tibetan (those are two of the five components of the calendar), animal, trigram and number associated with the lunar date.

Solar: Earth-Monkey. Bi

The third line gives Chinese symbolic data associated with the solar day: the element and cyclic animal, and, the lunar mansion.

2;11,24 23;4,36 22;22,1 18;26,38 9;28,13

The fourth line gives: the time of the end of the lunar day, lunar longitude at daybreak, the solar longitude and the "longitude" of the yoga. These first four lines are always present.

From 1st to 15th, Demonstration of Miracles.
  zin phung

The fifth and sixth lines give information regarding any festivals or otherwise special days; also given are the movements of some earth-lords. This information was requested by several users of the Tsurphu calendar. Those currently included are: "yan kwong", "klu bzlog", "klu thebs", "zin phung" and "nyi nag". Extensive earth-lord information is given in the calendar file intended for publication, such as ts2_2013.txt.

Finally, on the 15th and 30th dates (full and new Moon), the following information is given regarding the planets:

Mars, slow: 24;31,36,2,38 – fast: 24;2,17,3,34 North 10;20,30
Jupiter, slow: 4;38,14,1,275 – fast: 3;47,15,4,240 West 1;20,30
Saturn, slow: 14;3,24,1,4985 – fast: 14;28,26,5,4351 South 6;12,59
Mercury, slow: 5;14,21,0,1098 – fast: 24;33,41,5,7550 South 10;27,29
Venus, slow: 20;46,32,3,105 – fast: 22;19,15,4,115 North 9;27,36
Rahu, head: 15;19,10,2,14

For each planet is given the slow and fast motion longitudes. The slow motion is effectively the planet's heliocentric longitude and the fast motion, geocentric. At the end of each line is given the traditional direction of the planet – this comes from the epicycle calculation – and the geocentric longitude in terms of sign of the zodiac, degrees and minutes. On the last line is the longitude of the head of Rahu, the ascending node of the Moon's orbit, important in eclipse predictions.

Extensive daily data

The second file, ts2_2013.txt, has basically the same structure, but includes more extensive information for each date.

17 items are listed for each day; these are labelled 'a' to 'q' (the first four labels are not printed, as all four items are on the first line):

1: dga' a. zla. mon gru.
   e) chu-sa
   f) bdud rtsi
   g) stag gi 1 nas khrums stod. chu-me, gtun shing
   i) yongs 'joms
   j) 'du byed
   l) stag li 1
   m) khra drag shar du 'tshog nor rdzas mi dbyung dbul nyi
   n) mgron
   o) sa-spre'u
   p) bi'i
   No: 2;11,24 23;4,36 22;22,1 18;26,38 9;28,13

a) The lunar date.

b) One of five pairs of characteristics associated with the lunar day from the Svarodaya (dbyangs 'char) symbolic system. The first word is one of the five characteristics, or groups, of the lunar days: joy, excellence, victory, emptiness and fullness (nandā dga' ba, bhadrā bzang po, jayā rgyal ba, riktā stong pa, and, pūrṇā rdzogs pa); these are well known from Vedic astrology, and are here called the Svarodaya emblems (mtshan ma). This is followed by a vowel (svarodaya means "arising of vowels").

c) The weekday.

d) The lunar mansion.

e) The element combination ('byung 'phrod) of the weekday and lunar mansion.

f) One of 27 "great conjunctions" ('phrod chen) that are derived from the weekday and lunar mansion.

g) If the lunar mansion changes during the day, this item lists the time of that change, the new element combination and the new great conjunction. The time of lunar mansion change is given in terms of the nāḍī (chu tshod) in the double-hour at which the change occurs. There are five nāḍī in each double-hour; the double-hour is identified by its cyclic animal.

h) If relevant, this item lists other yogas and daily characteristics (thun mong dang thun min gyi 'phrod) that arise from the combination of weekday and lunar mansion.

i) The yoga (sbyor ba), one of the five components (yan lag lnga) of the calendar.

j) The link - one of the 12 links of dependent origination (rten 'brel).

k) Viṣṭi, one of the 11 karaṇas, described briefly in the Kālacakra Tantra and refered to by Banda Gelek as "the Rāhu that arises through the lunar days".

l) The cyclic animal, trigram and number associated with the lunar day.

m) Details of any earth-lord (sa bdag) movements.

n) One of ten "sky door" (gnam sgo) of the lunar day.

o) Element and cyclic animal associated with the solar day.

p) Chinese lunar mansion associated with the solar day. As these names are not well known, a full list is given below.

q) If relevant, the earth-lord "ba dan".

Finally, there are two further lines. The first of these gives: the time of the end of the lunar day, the lunar longitude at daybreak, the solar longitude, the "longitude" of the yoga, and, the solar longitude in terms of signs, degrees and minutes. The final line gives the Gregorian date.

Chinese names of the lunar mansions

The following table lists the Chinese names for the lunar mansions. The first column gives a Wylie representation of the Tibetan transcription of the Chinese names as given by Jamgon Kongtrul in his text rtsis kyi bstan bcos nyer mkho bum bzang las skar rtsis kyi lag len 'jug bder bsdebs pa legs bshad kun 'dus; it is these names that are used in the software. The next two columns give the Chinese: first the pinyin representation and then the character. The fourth column gives the English equivalents as given by Joseph Needham, in Science and Civilisation in China, vol 3, pp. 235-237. The last two columns give the Sanskrit and Tibetan equivalents. In most Sanskrit and Tibetan texts, any list of the lunar mansions starts with Aśvinī, but this table follows the Chinese convention and starts with Citrā.

gyojiǎoHornCitrānag pa
khangkàngNeckSvātīsa ri
tisRootViśākhāsa ga
sbufángRoomAnurādhālha mtshams
kyīWinnowing-basketPūrvāṣāḍhāchu stod
dǒuSouthern DipperUttarāṣāḍhāchu smad
nyi'uniúOxŚravaṇagro bzhin
gnyosGirlAbhijitbyi bzhin
shu'iEmptinessDhaniṣṭhāmon gre
wuwēiRooftopŚatabhiṣajmon gru
zhishìHousePūrvabhādrapādakhrums stod
dbi'iWallUttarabhādrapādakhrums smad
kho'ikuíLegsRevatīnam gru
lóuBondAśvinītha skar
dbu'iwèiStomachBharaṇībra nye
ma'umǎoPleiadesKṛittikāsmin drug
bi'iNet (Hyades)Rohiṇī snar ma
kīncānGroup of 3 starsĀrdrālag
tsingjǐngWellPunarvasunabs so
tswangzhāngExtended netPūrvaphalgunīgre
cingzhěnChariot platformHastāme bzhi

    E. Henning.
    Last updated 18 May 2013.
    Return to calendar introduction.