Blinking snake

Mayalib 1.1

Constellation band

Mayalib — Mayan dates and numbers for Python

Introduction

Mayalib contains a full complement of classes, functions and a few variables suitable for performing basic arithmetic operations with Mayan dates and numbers; some support for astronomical functions is provided, but much in this area is slated for future implementation. Familiarity with the Mayan calendar is a prerequisite; see the References for resources that will help you learn about that calendar. Familiarity with Python is not a prerequisite, as this documentation offers a short section on basic programming. Again, see References for more help. Many functions and class methods pertain to the production of HTML, suitable for use in web cgi programs. These last are covered in a separate section of this document.

Mayalib and the contained classes, functions and variables were created in order to make research into the form, function and structure of the Mayan calendar as simple as possible. Python meshes with the Mayan calendar so well it is hard to believe that the language was not created with the calendar in mind, but that appears to be the case. The core implementation of the language has arbitrarily long integers built in, so very little needs to be done in order to support multi-trillion year calculations, commonplace in work with the Mayan calendar. For further information, see the paper I presented at the Seventh International Python Conference, Python Vuh: Mayan Calendrical Mathematics with Python.

Variables in mayalib

While there are a number of variables in the mayalib namespace, most of their names include a leading underscore, so as not to be visible outside the mayalib module. The remaining names were chosen for minimal collision with user variables; the preferred method for using mayalib, contrary to recommended usage for most other supplementary Python packages and libraries, is to include the line

from mayalib import *

at the beginning of your programs. Naturally, you may still prefer to simply import mayalib instead, but then you will have a lot more typing to do.

Here are the names of exposed variables in mayalib and their meanings.

MAYALIB_VERSION: 1.1
The version number for the current mayalib
center, left, right: 0, 1, 2
Used in building HTML tables; specifies the alignment in table elements
LOCATION: REMOTE
Specifies a prefix for finding glyph images; Can be one of LOCAL, RELATIVE or REMOTE. REMOTE and RELATIVE should not be changed, but LOCAL should be edited and changed to reflect DocumentRoot on your webserver, if you have one
baktun, katun, tun, uinal, kin: 144,000, 7,200, 360, 20, 1
Standard values for time periods

Astronomical, Gregorian and Julian Calendar, and Time of Day Functions

ToDecimal(time)
Argument: time is a tuple: (hour, minute, second).
Return value: decimal hours (i.e., the tuple (1, 23, 23) converts to 1.38972222222 hours)
ToDecimalDay(time)
Argument: time is a tuple: (hour, minute, second).
Return value: decimal part of a day (i.e., the tuple (1, 23, 23) converts to 0.0579050925926 day)
ToHoursMinutesSeconds(hourd)
Argument: hourd is decimal hours.
Return value: tuple: (hour, minute, second)
AdjustTo360(n)
Argument: n is a float.
Return value: n adjusted to the range 0 <= n < 360.0
Radians(x)
Argument: x is a float.
Return value: x (degrees) converted to radians
Degrees(x)
Argument: x is a float.
Return value: x (radians) converted to degrees
R2(E, ecc)
Arguments: E and ecc are both floats, where E is the eccentric anomaly of an orbit, in radians, and ecc is the eccentricity of the orbit.
Return value: finds a solution iteratively for Kepler’s equation, E - e sin E = M, where e is less than or equal to 0.1. The value returned is the true anomaly.
julday(month, day, year, dayofweek, percentofday=0.0)
julday_gregorian(month, day, year, dayofweek, percentofday=0.0)
Arguments: month, day, year and dayofweek are all integers, and are expected to be in the Gregorian calendar; percentofday is a float, and is optional.
Return value: tuple (Julian day #.#, day of week)
julday_mixed(month, day, year, dayofweek, percentofday=0.0)
Argments: same as julday(), but input dates are expected to be in the Gregorian calendar after 14 October, 1582 and the Julian calendar before that date.
Return value: tuple (Julian day #.#, day of week)
julday_julian(month, day, year, dayofweek, percentofday=0.0)
Arguments: same as julday() but input dates are expected to be in the Julian calendar.
Return value: tuple (Julian day #.#, day of week)
calday(jday)
Arguments: jday is a float as returned from julday()
Return value: month, day, year and day of week as integers, in the Gregorian calendar only.
isleap(year)
Arguments: year is an integer
Return value: calculates whether or not year is a leap year in the Gregorian calendar only; returns 1 if year is leap, 0 if not.
todaytime()
Arguments: none
Return value: a float representing the local time of day as a percent of the day (calls ToDecimalDay())
todaytimeutc()
Arguments: none
Return value: a float representing the UTC time of day as a percent of the day (calls ToDecimalDay())
todayj()
Arguments: none
Return value: tuple (Julian day #.#, day of week) representing the Julian day number plus the local time (calls julday())
todayjutc()
Arguments: none
Return value: tuple (Julian day #.#, day of week) representing the Julian day number plus the UTC time (calls julday())

Utility Functions

isnumber(s)
Argument: string
Return value: 1 if s contains only digits 0-9, 0 otherwise
issignednumber(s)
Argument: string
Return value: 1 if s contains only digits 0-9 and signs, 0 otherwise
hasvalue(d, m)
Arguments: dictionary, any
Return value: returns the key for value m if it can be found in dictionary d, otherwise None
exgcd(u, v, pr = 0)
Arguments: u, v are integers
Return value: calculates the greatest common divisor of u and v using an algoritm called ‘The Pulverizer’ as described in Knuth’s The Art of Computer Programming, Volume 2, Section 4.5.2. If pr is not 0, prints the steps it takes to calculate the gcd. Returns a tuple (gcd, mn1, mn2), where mn1 and mn2 are magic numbers useful in other calculations.

Class Mayanum

Class mayanum provides full-function Mayan dates and Mayan numbers, and has built in facilities for addition, subtraction, multiplication and other useful mathematical operations. One of the key features is the ability to treat a mayanum as either a calendar number or an ordinary (uniform base 20) number. Creating a mayanum is a simple process. The simplest is

x = mayanum()

which creates a mayanum for day 0 of the Mayan calendar, or 0.0.0.0.0. Since mayanums have no idea whether they will be used as dates or as ordinary numbers, creating a mayanum builds only the Long Count coeffecient component. The Calendar Round and other cycles must be separately added, by using a method called calculate():

x = mayanum()
x.calculate()

Applying this method, as shown above, calculates the correct Calendar Round (4 ’Ahaw 8 Kumk’u), the correct Lord of the Night (G9), the 819-day count position (3), and various other cycles. Creating mayanums for other dates is almost as simple; you merely need to provide Long Count coeffecients for the date you wish:

x = mayanum([12, 19, 5, 14, 8])
x.calculate()

which manufactures a Mayan date for 12.19.5.14.8 1 Lamat 1 K’ank’in, or December 25 1998 (using the standard 584285 correlation; a means to change the correlation date is described in the next section, Non-Class Mayan Functions).

Mathematics with mayanums can be very easy. They can be added, subtracted, multiplied (with care), changed to a different style (date style to number style and back again), converted to the Gregorian calendar and compared. As an example, here’s how to add and multiply:

x = mayanum()
x.calculate()
z = (x + “1.0.0.0.0”) * 13 # Add one bak’tun and multiply by 13
z.calculate ( )
print x, z
print x.gregorian()
print z.gregorian()

The above steps will print the starting day and the day 13 bak’tuns later when some consider that the Mayan calendar will end. Many other operations are documented below. Note that methods in the style “__repr__” (these are called “special class methods”) are not usually called that way, but by performing some other operation. For example, the __repr__ is called by typing print x, and the __add__ method is called whenever you type x = x + y when x and y are both mayanums.

mayanum(lc=[0,0,0,0,0], t=-1, v=-1, hd=-1, hm=-1, g=-1)
This is the constructor for class mayanum. All arguments are optional. The arguments, if used, are described below:

lc:
A Long Count list, which may be any length (i.e., the date from Coba causes no problems whatsoever). Refer to the Python documentation for the definition of list.
t:
The trecena, an integer in the range 1-13.
v:
The veintena, an integer in the range 0-19, representing the named days ’Ahaw to Kawak.
hd:
The haab day, an integer in the range 0-19.
hm:
The haab month, an integer in the range 0-18, representing the named months Pohp to Wayeb.
g:
The G glyph, an integer in the range 0-8, representing the Lord of the Night; 0 is G9, 8 is G8.

Most of the time, it is easiest to simply create a mayanum with the default arguments and later add or subtract to arrive at the particular date you’re interested in. All the methods built into mayanum are described below. Note, however, that undocumented methods are undocumented for a reason, and should not be used.

alautun()
Arguments: none
Return value: the alautun Long Count coeffecient lc[8].
kinchiltun()
Arguments: none
Return value: the kinchiltun Long Count coeffecient lc[7].
calabtun()
Arguments: none
Return value: the calabtun Long Count coeffecient lc[6].
pictun()
Arguments: none
Return value: the pictun Long Count coeffecient lc[5].
baktun()
Arguments: none
Return value: the baktun Long Count coeffecient lc[4].
katun()
Arguments: none
Return value: the katun Long Count coeffecient lc[3].
tun()
Arguments: none
Return value: the tun Long Count coeffecient lc[2].
uinal()
Arguments: none
Return value: the uinal Long Count coeffecient lc[1].
kin()
Arguments: none
Return value: the kin Long Count coeffecient lc[0].

For the above coeffecient operations, if a coeffecient does not exist the number is enlarged and the correct place is initialized with 0. For numbers that contain places higher than alautun, the coeffecient may easily be retrieved by simply indexing the number. I.e., the next place above alautun is obtained with

x = mayanum()
x = x + “13.13.13.13.13.13.13.13.13.13.13.13.0.0.0.0”
print x[9]

However, when indexing a number, the indexed place must already exist; see the methods grow() and shrink(), described later.

__repr__()
Arguments: none
This is the method called whenever a mayanum is printed or turned into a string. It knows whether a date has been calculated or not, and adjusts the conversion process accordingly; observe the difference between the results of the following two print statements:

x = mayanum()
print x
x.calculate()
s = ‘x‘
print s

f819()
Arguments: none
Return value: calculates the 819-day count position using the Long Count coeffecients, inserts the result into the mayanum and returns the calculated position, an integer ranging from 0 to 818.
get819list()
Arguments: none
Return value: calculates the Calendar Round of the previous 819-day station and returns it as a string.

x = mayanum()
x.calculate()
print x
s = x.get819list()
print s

list_color_direction_text()
Arguments: none
Return value: a list containing the color, a space, and the direction; for example, appying this method to day 0 returns this list: ['Kan', ' ', 'Nohol']. This is useful in building larger lists of dates with their colors.
list_color()
Arguments: none
Return value: a string suitable for use in an HTML document which will retrieve an image of the correct color glyph. For day 0, this string <img alt="Kan, yellow" title="Kan, yellow" src=“/Gif/Kan_1c.png”> results in this glyph: Kan, yellow
list_direction()
Arguments: none
Return value: a string suitable for use in an HTML document which will retrieve an image of the correct direction glyph. For day 0, this string <img alt="South, Nohol" title="South, Nohol" src=“/Gif/nohol_1.png”> results in this glyph: South, Nohol
list_color_direction()
Arguments: none
Return value: a list containing strings suitable for use in an HTML document which will retrieve images of the correct color and direction glyphs. For day 0, this list is
['<img alt="South, Nohol" title="South, Nohol" src=“/Gif/Kan_1c.png”>', ' ', '<img alt="South, Nohol" title="South, Nohol" src=“/Gif/nohol_1.png”>'],
which returns the images ['Kan, yellow', ' ', 'South, Nohol']
print_color_direction()
Arguments: none
Return value: none. Prints the text for the color and direction:

>>> x.print_color_direction()
Kan Nohol
>>>

gregorian()
Arguments: none
Return value: converts the Mayan date to a date in the Gregorian calendar and returns the string representing the date.
date()
Arguments: none
Return value: converts the Mayan date to a date in the Gregorian calendar and returns a tuple representing the date. For day 0, this tuple is (7, 13, -3113, 2), or (August, 13, 3114BCE, Wednesday).
getlist(adds=0)
Arguments: adds, either 0 or 1 (optional)
Return value: a list representing the Mayan date. For day 0, this is [0, 0, 0, 0, 0, ' ', 4, “’Ahaw”, ' ', 8, “Kumk’u”, ' ', 'G9']. If adds is not 0, then the Gregorian date is added to the list: [0, 0, 0, 0, 0, ' ', 4, “’Ahaw”, ' ', 8, “Kumk’u”, ' ', 'G9', ' ', 'Wed, 13 Aug, -3113']
getdnimagelist()
Arguments: none
Return value: a list containing strings suitable for use in an HTML document that will retrieve images; this function assumes that the mayanum is a Distance Number, so the image list will come back in Distance Number format. For a Distance Number counting backward 6.13.0, the following list will be returned: ['ZeroKin', '13Winal', '6Tun']
grow(n=5)
Arguments: integer n
Return value: none. Expands, if necessary, the mayanum to comprise n places in the Long Count list. The added places are initialized to 0, and n can be any positive integer.
shrink(n=2)
Arguments: integer n
Return value: none. Shrinks, if necessary, the mayanum to comprise n places in the Long Count list. N can be any positive integer.
getimagelist(adds=0, nb=1)
Arguments: integer adds, nb
Return value: A list containing strings representing a (calculated) date; adds indicates that padding spaces should be added to the end of the list in order to make it line up with another list, while nb indicates whether or not the time period glyphs (baktun, katun, etc.) should be included in the list. Here are the possible combinations as returned for -6.13.0 (a negative Long Count, marked by the Ring Number glyph at the beginning):
adds=0, nb=0: ['Ring number, negative', '6', '13', 'Zero', ' ', '2', 'Ahaw', ' ', '18', 'Xul', ' ', 'G1']

adds=0, nb=1: ['Ring number, negative', '6Tun', '13Winal', 'ZeroKin', ' ', '2', 'Ahaw', ' ', '18', 'Xul', ' ', 'G1']

adds=1, nb=0: ['Ring number, negative', '6', '13', 'Zero', ' ', '2', 'Ahaw', ' ', '18', 'Xul', ' ', 'G1', ' ', ' ']

adds=1, nb=1: ['Ring number, negative', '6Tun', '13Winal', 'ZeroKin', ' ', '2', 'Ahaw', ' ', '18', 'Xul', ' ', 'G1', ' ', ' ']
printHTML()
Arguments: none
Return value: none. Prints the date in a format suitable for use in an HTML table on a web page, as in the following example:

     
__getitem__(key)
Arguments: integer key
This is the special class method that allows you to retrieve Long Count coeffecients by their indices; for a date 12.19.5.14.8, date[0] is 8, and date[4] is 12.
__getitem__(key, value)
Arguments: integer key, value
Special class method that lets you set Long Count coeffecients by their indices; if date is 12.19.5.14.8, then date[4] = 13 results in the date being changed to 13.19.5.14.8.
__cmp__(other)
Arguments: mayanum other
Special class method allowing comparisons, such that if three dates x, y and z are -6.13.0, 0.0.0.0.0 and 6.13.0 respectively, then the relation x < y $lt; z holds.
__neg__()
Arguments: none
Special class method; changes the sign on the number. For example if x is 12.19.5.14.8 1 Lamat 1 K’ank’in, then -x is -12.19.5.14.8 7 ’Eb 10 Sots. Performing the operation again on the result, -(-x), recovers the original number, x.
__pos__()
Arguments: none
Special class method; this is not a sign-changing operation, but the identity operation. I.e., +x gives you x, and +(-x) gives you -x.
__abs__()
Arguments: none
This special class method is called whenever abs() is called with a mayanum as the argument. Such values that result technically have no sign, but abs(-x) and -(-x) have the same effect.
__coerce__(other)
Arguments: other
This method is called whenever a mayanum is included within an expression with some other type, such as x + 13 or x - “13.0.0.0.0”. The types that are useful in such expressions include:
  • mayanum
  • integer
  • long
  • string
  • list, although only lists such as [1,0,0,0,0], composed entirely of numbers, can be dealt with.
__sub__(minus)
Arguments: mayanum minus
Special class method that is called (after the __coerce__ method, if required) whenever a mayanum is used in an expression involving subtraction and the mayanum is on the left of such an expression. Performs accurate signed arithmetic. If x is -0.13, then x = x - 13 will result in -0.1.6.
__rsub__(minus)
Arguments: mayanum minus
Same as __sub__(), but called only when the mayanum is on the right side of an expression. If x is -0.13, then x = 13 - x will give 0.1.6.
__add__(plus)
Arguments: mayanum plus
Special class method that is called (after the __coerce__ method, if required) whenever a mayanum is used in an expression involving addition and the mayanum is on the left of such an expression. Performs accurate signed arithmetic. If x is -0.13, then x = x + 13 will result in 0.0.
__radd__(plus)
Arguments: mayanum plus
Same as __sub__(), but called only when the mayanum is on the right side of an expression. If x is -0.13, then x = -13 + x will give -0.1.6.
__mul__(multiplier)
Arguments: mayanum multiplier
Multiplication of a mayanum can only be done by single integers, not by a full-fledged mayanum. This is because multiplication of two mixed-radix numbers cannot be performed—think of multiplying pounds, shillings and pence times another amount in pounds, shillings and pence; it doesn’t make sense. Thus, 2.5.19 · 20 works, but 2.5.19 · 1.0 doesn’t. Signed multiplication by one small integer is correctly supported, however.
__lshift__(n)
Arguments: int n
This method is called for the shift operator, <<. Shifts mayanum left by n places, re-evaluating the value of each place if necessary. For a pure radix-20 mayanum, only the shift is performed. For a normal, date, mayanum, re-evaluation is necessary. For example, if mayanum is 0.19, then the result of mayanum << 1 is 1.1.0, and the result of mayanum << 2 is 19.0.0. The reasons for this behaviour are left for the reader to discover.
mulmaya(mul)
Arguments: mayanum mul
This is a standard method, which converts both mayanums to Python longs before performing multiplication. The resulting Python long is converted to a mayanum and returned. For example, if x is 19.0.0 and mul is 2.4.19, then the result of x.mulmaya(mul) is 1.18.18.1.0.0. The difference between this and the special class method __mul__ is that mulmaya always converts its operands to Python longs, whereas __mul__ only converts the multiplier to an integer. mulmaya can also only be used when both operands are mayanums.
divmaya(div)
Arguments: mayanum div
This is exactly similar to mulmaya, in that both operands are converted to Python longs from mayanums, and the result of the division is turned into a mayanum.
modmaya(mod)
Arguments: mayanum mod
This method is exactly like divmaya except that it returns the remainder from the division as a mayanum.
divmodmaya(div)
Arguments: mayanum div
This method is a combination of divmaya and modmaya, and returns both the quotient and the remainder (in that order) as a tuple.
B20()
Arguments: none
Converts mayanum to a pure base 20 Mayan number; if the number is already base 20, it does nothing.
B18()
Arguments: none
Converts mayanum to a normal base 18 Mayan date; if the number is already base 18, it does nothing.
b20()
Arguments: none
Converts mayanum to a pure base 20 Mayan number by converting to a Python long and then back to a mayanum. Deprecated.
b18()
Arguments: none
Converts mayanum to a normal base 18 Mayan date by converting to a Python long and then back to a mayanum. Deprecated.
submaya(minus)
Arguments: mayanum minus
Performs a subtraction of minus from mayanum by first converting both operands to Python longs. Deprecated.
__long__()
Arguments: none
This method is called when it is required to convert a mayanum to a Python long, as in x = long(mayanum).
__int__()
Arguments: none
This method is called when it is required to convert a mayanum to a Python int, as in x = int(mayanum).
__float__()
Arguments: none
This method is called when it is required to convert a mayanum to a Python float, as in x = float(mayanum). However, be warned that this returns the float equivalent of the Julian Period day number, so that the result depends upon the value of the Correlation constant.
calculated()
Arguments: none
Returns 1 if fields other than the Long Count coeffecients have been calculated. If 1 is returned, all components of the class have been calculated, and if 0 is returned, only the Long Count coeffecients can be relied upon.
longtomaya(n)
Arguments: long n
Converts the n into a list of Long Count coeffecients, and then replaces the existing mayanum list.
mayatolong()
Arguments: none
Converts the Long Count coeffecients into the Python long equivalent, which is returned.
calculate()
Arguments: none
Evaluates the Long Count coeffecients, then determines and stores the following items:
trecena
veintena
haab month
haab day
haab position
tzolk’in position
number of whole haabs since day 0
position in the Calendar Round
Lord of the Night position
position in the 819-day count
Y Glyph
sign
Note that until the calculate() method is called, no members contained in the mayanum are valid except for the Long Count coeffecients.
reset()
Arguments: none
Sets all members of the mayanum to invalid values.
__len__()
Arguments: none
Determines the length of the mayanum based solely on the number of places in the Long Count coeffecient list. For example, if x is 1.0.0.0.0.0.0.0, then l = len(x) is 8.
stringtomaya(s)
Arguments: string s
You usually don’t need to call this directly, as it is called by the __coerce__ method as needed. If x is 1.0.0, then x = x + “1.0.0” is 2.0.0.
maxdays(n)
Arguments: integer or list n
Returns the maximum possible number of days for a Long Count. If lc is a list (a Long Count), then maxdays will return the maximum days possible without regard to the actual coeffecients. That is, if n has 5 places, then maxdays will return 2,880,000. If n is an integer, it returns the maximum possible number of days for a Long Count of length n. That is, if n is 5, then maxdays will return 2,880,000.
lineardistributionofn(ind, n, cycle = 365, spl = 20, sd = 348)
Arguments: integer ind, n, cycle, spl, sd
Return value: number of days of hunk ind contained within a period of time n (in days) where the hunk size is spl and the starting day of the cycle is sd. This method was originally set up to calculate how many days of haab month ind were contained within n days of the Long Count starting at day 0, but I soon realized that it could be generalized. As it is, if you want to determine how many days of month Kumk’u are contained in the first four katuns since day 0, the syntax would be
t = x.lineardistributionofn(17, 28800, 365, 20, 348)
and the answer is 1572.
distributionofn(day, n, cycle = 13, sd = 4)
Arguments: integer day, n, cycle, spl, sd
Similar to lineardistributionofn(), except that it works only for modular cycles such as the trecena or the Calendar Round. For example, if you wish to know how many days ’Ahaw there were in the first four katuns, then enter x.distributionofn(0,28800,13,4) into the interpreter (assuming that x is a mayanum). The answer is 2215.

Copyright & Disclaimer

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee or royalty is hereby granted, provided that the below copyright notice appear in all copies and that both the copyright notice and this permission notice appear in supporting documentation or portions thereof, including modifications, that you make.

THE AUTHOR IVAN VAN LANINGHAM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE!

Previous Page
Table of Contents
Next Page

Main web site:  http://www.pauahtun.org

Valid HTML 4.01 Transitional