Saturday, April 3, 2010

Helper functions for Python

Since the new API uses C data structures, the interface is a bit unfriendly for Python. So, I added the following functions for ease of programming:


toItems: converts Python list of Items to ArrayOfItems
fromItems: converts ArrayOfItems to Python list of Items

toStrings: converts Python list of strings to ArrayOfStrings
fromStrings: converts ArrayOfStrings to Python list of strings

toMatrix: converts Python list of list of reals to Matrix (two optional arguments for row and column names)
fromMatrix: converts Matrix to a list of row names, column names, and 2D list of reals

New API

The C API has been remodeled so that it can be wrapped automatically by SWIG.
SWIG will automatically generate wrappers for Python, Perl, R, and Ruby -- so all those languages will be able to contribute plugins.

To use the new API, a programmer must be familiar with the 6 data structures listed below. All languages (C, Python, R, etc) will have the same interface and will use the same data structures. Of course, the syntax will be slightly different: in C, one would write "Matrix M = ..." whereas in Python one would write "M = ..." and in Perl, "$M = ...".

The six main data structures are:

Item: just a reference to a TinkerCell object (memory pointer)

String: exactly what the name means

ArrayOfItems: array of Items

example use:
ArrayOfItems A = newArrayOfItems(4
A.length
nthItem(A,3)
deleteArrayOfItems(&A)

ArrayOfStrings: array of Strings

example use:
ArrayOfStrings S = newArrayOfStrings(4)
S.length
nthString(S,3)
deleteArrayOfStrings(&S)

Matrix: two dimensional array of reals with row and column names. The rownames and colnames fields are ArrayOfString objects

example use:
M = newMatrix(4,3)
M.rows
M.cols
getColumnName(M,2)
setColumnName(M,2,"col2")
getRowName(M,1)
setRowName(M,1,"row1")
getValue(M,2,3)
setValue(M,2,3,0.5)
deleteMatrix(&M)

TableOfStrings: two dimensional array of Strings with row and column names. The rownames and colnames fields are ArrayOfString objects

example use:
TableOfStrings S = newTableOfStrings(4,5)
S.rows
S.cols
nthString( S.rownames, 1)
nthString( S.colnames, 2)
getString(S,2,3)
setString(S,2,3,"hello")
deleteTableOfStrings(&S)