Open source software for traditional Tibetan calendars.
600 years' worth of each of the two main systems of traditional Tibetan calendars are given elsewhere on this site. On this page, open source software to calculate these calendars is made available. These two main traditions are known as the Phugpa and Tsurphu, the former being by far the most common. In addition, the software available from this page also calculates the historically interesting calendar devised by Zhonnu Pal, the Error Correction system. These were the first calendar systems created in Tibet that used the Siddhānta calculation system (grub rtsis). These three systems were all devised within a few years of each other – starting in the 1440s – as attempts to reconstruct the accurate calculation system that the Tibetans believed had been present in the lost Kālacakra Mūlatantra. |
In this software, all three of these systems are calculated from epochs far back in time – just over 3,000 years ago for the Phugpa and Tsurphu, and just over 4,000 years ago for the Error Correction. When these calendars were being devised in the middle of the 15th century, the calendar makers calculated backwards to events in the life of the Buddha as part of their efforts to adjust (and justify) their calculations. As this software has mainly been developed as a research tool, it makes sense for it to cover all possibly relevant time periods.
As it happens, a change made (September 2013) to the New Genden calculations is due to an early comparison. In his text on that system, Yeshe Paljor discusses the fact that the last month of the year before the Kālacakra epoch should be intercalary. For that month, the value 46 is "very correct" or "highly accurate". Using his methods, for that month, starting with the mean new Moon on 22 February 806, the intercalation index certainly is 46. It would be quite wrong for the following month to be intercalary, as this would contradict the data given in the original Kālacakra material. For that month, his intercalation index is 48. He then calculates forward to his epoch year, 1747. I had not realised the importance of this comment when creating versions of this software prior to 1.06, and had not calculated Yeshe Paljor's figures back to that point. In earlier versions I used the Phugpa values of 48 and 49 to test for intercalaries; it is now clear that the necessary values are 46 and 47.
Also available in the latest versions are epoch data for reformed Phugpa calendars, developed by Lozang Chokyi Nyima (thu'u bkwan blo bzang chos kyi nyi ma) and by Sumpa Khenpo Yeshe Paljor "sum pa mkhan po ye shes dpal 'byor". The latter is used as the basis for the Mongolian traditional calendar. Other such epoch data may be made available in the future.
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:
Content of the software and possible future developments.
The main calendar in use in Tibet and by Tibetans living outside of the country is that from the Phugpa tradition. It is also the best documented with many texts describing its calculation, some in great detail. It is therefore the most fully developed in this software and, other than some elemental combinations, no further work is currently planned. However, more comments will be added to explain the calculations, and these will normally be described from the point of view of the Phugpa system.
The details for the Tsurphu calendar are taken from the text by Jamgon Kongtrul ('jam mgon kong sprul) entitled "Compendium of Practical Astronomy" (rtsis kyi bstan bcos nyer mkho bum bzang las skar rtsis kyi lag len 'jug bder bsdebs pa legs bshad kun 'dus). There is a minor difference with recent Tsurphu calendars, due to their use of a different value for the longitude of the Sun. That is implemented in the software for an extensive Tsurphu calendar that is available here.
The Error Correction calendar is based on an incomplete edition of the work by Zhonnu Pal (gzhon nu dpal) entitled "The Correction of Errors in Astronomy" (rtsis la 'khrul pa sel ba). This text gives the basic calendar and the calculations for the Sun and Moon (weekday), but not the planets. In the "The Oral Instructions of Puṇḍarika" (pad dkar zhal lung), Norzang Gyatso (nor bzang rgya mtsho) states that for the planets, Zhonnu Pal simply used the values given in the tantra, but it has not been possible to check this. Other works by Zhonnu Pal are expected to become available soon, hopefully enabling a more thorough understanding of the calculations for this calendar.
The system by Lozang Chokyi Nyima is based on his text, the "rtsis kyi bstan bcos mkhas pa'i snying nor". His epoch data are here.
The New Genden Calculations is a similar system intended to reform the Phugpa calendar and bring the calculations in line with observations. The epoch data are here.
Software documentation. The following is the brief documentation that comes with the software in a text file:
TIBETAN CALENDAR SOFTWARE. Version 1.06.
Since version 1.04, this software has been prepared as a 32-bit Windows NT command line executable, rather than as a DOS program. This is to ensure that the program is able to run on both Windows Vista and Windows 7, both of which are incompatible 16-bit DOS programs.
When the program starts, it is first necessary to select an epoch – using the number keys – for the basis of subsequent calculations. The list given is as follows:
1. Generalised Phugpa, -1000.
2. Generalised Tsurphu, -1000.
3. Generalised Error Correction, -2000.
4. mkhas pa'i snying nor, 1796.
5. New Genden Calculations, 1747 CE.
All of these are for siddhānta calculations (grub rtsis) devised in Tibet.
After making a selection, you then come to the main menu, from which selections are again made using the numeric keys. This is a change from previous versions which made use of the function keys:
TIBETAN CALENDAR SOFTWARE
Use numeric keys to select from the following:
1. Set epoch.
2. Print calendar.
3. Calendar cycle.
4. Run search test.
5. Calculate New Years.
The first selection takes you back to the first screen to select a new epoch.
The next two are the main routines in the program. "F2. Print calendar" prints calendar information to a disk file, called, eg. PL_1992.DAT (phug lugs for 1992). This does handle years before 1 CE, but it is unlikely these will ever be needed. For this function you need to enter a start and finish year. Some of the data streams across the screen (this was originally in there for debugging puposes), but the results are only viewed properly using the file on disk.
The third selection runs the main calendar cycle, printing on screen information for one day at a time. First you need to enter a three-field number as the starting date for calculations. This needs the Tibetan lunar day (tshes pa), month number and western year. For example:
3 8 1997
would start calculations for the 3rd lunar day (tshes pa) in the 3rd Tibetan month of the year starting early in 1997.
Once the daily information has been displayed, single key commands are used to display further information.
N/n – goes back to select a new start date.
E/e – returns to the main menu.
T/t – adds 1 to the Tibetan lunar day, "tshes pa".
M/m – adds 1 to the month number.
Y/y – adds 1 to the year.
R/r – prints the current information on screen to file, in REPORT.DAT.
P/p – goes to the previous lunar day.
In the block of data for any lunar date, the following information is given. The top three lines appear as follows:
1. Generalised Phugpa, -1000.
The ZLA-DAG is: 37239;48, Month = 11, Year = 2010
DATE is: 2 / 11 / 2010 - Corrected Month = -11, mgo
The first line indicates the chosen epoch. The next two lines indicate that the data is for the second lunar day (tshes pa, tithi) in the month calculated as the 11th month. In this instance the corrected month – the one used in actual calendars – has a negative value. This means that this is an intercalary month (zla lhag). There are two months numbered "eleven" that year, and the second of these is called the delayed month (zla bshol). mgo is the Tibetan name for the month.
Since version 1.06, the second and third lines have been changed to read:
True month: 37239;48, Month = 11, Year = 2010
Target date: 2 / 11 / 2010 - Corrected Month = -11, mgo
The following month we have for the month information:
The ZLA-DAG is: 37240;50, Month = 12, Year = 2010
DATE is: 2 / 12 / 2010 - Corrected Month = 11, mgo
Here, although the calculated month is 12, the actual month value is 11, this being the delayed month. So, a month later, we would have the calculated month as 1, and the corrected month as 12. The term "zla-dag" translates as true month, and is the count of lunar months (37240) since the epoch. The value 50 is the intercalation index for the month in question.
On the next line of the screen is data for the Moon's node, Rāhu, calculated for the 15th and 30th of the month – the new and full Moon days, when eclipses can occur. The "ril-cha" is the lunar anomaly.
In the next main block of four lines of data, the figures gza-bar (mean weekday) and gza-dag (true weekday) give data for the time of the end of the second lunar day in weekdays, nāḍī (chu tshod), pala (chu srang), breaths (dbugs) and fractional units. When a lunar day is omitted from the calendar there will be a gza-dag on one day such as 5;0,22,5,3 (very early in the morning) and on the next day figures such as 5;55,41,5,7 (very late, just before mean daybreak). Notice that the weekday value has not changed, and on the lower lines these will both register as the same day in the western calendar.
If a lunar day is duplicated, there will be gza-dag figures such as 6;58,38,5,11 (late, just before daybreak) and 1;2,44,4,0 (very early in the morning) on the following day. The weekday figure has increased by two (it is calculated modulo 7), and the western date will also advance by two.
The lines for nyi-bar (mean Sun) and nyi-dag (true Sun) give the mean and true longitudes of the Sun, calculated for the end of the lunar day. The decimal figures at the ends of these lines give these solar longitude values calculated in terms of degrees.
The next line has the longitude of the Moon, calculated both at the end of the lunar day and at the start of the solar day, at daybreak. Next comes the general day factors – these are fractional units used to calculate data for the very end of the solar day. This is important in most traditions (not Tsurphu) for calculating planetary data. The same is true for the "Dragkang factor" – this is used to calculate the mean solar longitude at the end of the solar day.
The next block contains planetary data for the five planets, in the format:
MARS sgos zhag = 525 - 20;12,3,2,100 - myur: 19;37,33,2,26
The planets are calculated using a count of solar days in their mean cycle from the beginning of the zodiac. The sgos zhag (particular or specific day) is this count of days. The next figures are the mean (heliocentric) longitude of the planet, and then the last figures (myur) are the apparent (geocentric) longitudes.
Below the planetary data we have the following:
SPYI ZHAG = 1099721. Julian day = 2455568. Western date = Thu, 6/1/2011
Since version 1.06, this line has been changed to read:
General day = 1099721. Julian day = 2455568. Western date = Thu, 6/1/2011
This gives the Julian date starting at noon GMT for the solar day in question, followed by the western date, in dd/mm/yyyy format. The spyi zhag (general day) is the number of solar days since the selected epoch. (This information is crucial to the planetary calculations, and is also used to determine the western date.)
The bottom line gives the following information:
Julian tithi time, mean: 2455568.077196, true: 2455567.695051
The time for the lunar day (tithi) is the time for the very end of that lunar day in Julian days of Universal Time. So, as this example is for the second lunar day, the times given are for the end of that lunar day, the first value being for the mean lunar day, and the second the true lunar day. These values are important because this is the main timescale of the set of calculations for the whole calendar. The true lunar day is the one used in the calendar. To calculate these data a longitude of 91° (that of Lhasa) has been assumed.
The next selection on the main menu, "F4. Run search test." runs a routine to search for particular values occuring in a calendar. For example, if you come across a reference to a text having been written on a certain lunar date, with a particular lunar mansion on a Wednesday, you can set this function to search for possible matches. This requires setting the search criteria in the source code – no generic search routine has been developed, and would probably not be worth the effort.
By way of an example, the software is currently set to search for the Phugpa details of the time of the Buddha's enlightenment, as given in the "The Oral Instructions of Puṇḍarika" (pad dkar zhal lung), by Norzang Gyatso (nor bzang rgya mtsho). He gives the following data:
Moon: 16;0 (true lunar day value)
If you select the Phugpa epoch, and then run the search routine, and enter as the start date:
0 1 -1000
after a few minutes the software will find the data for the date Sunday 17 March 927 BCE. The next match is in 332 BCE, which is far too late. Pressing the "E" key exits the search routine; pressing any other key continues the search.
The next selection, "F5. Calculate New Years.", calculates a set of new year dates for a range of years, and stores the results in a text file (years.dat) on disk. As with the main calendar routine, you need to enter a start and finish year.
The final selection (F9) of the main menu exits the program.
The software is split into several modules:
T1.C – the main calendar and new year routines
T2.C – the data for the different epochs and the main subroutines for the calendar
T3.C – the routines for planetary calculations
T4.C – the routines to print whole year calendars to disk
TESTS.C – a general test/search routine
BCD.C – binary coded decimal routines for very large integer arithmetic
UTILS.C – various utility routines
The source code contains a reasonable number of comments, but these will be improved over time. In particular, comments labelled "KTC" give page number references to particular algorithms in the book "Kālacakra and the Tibetan Calendar".
Please report any errors that you may discover.