Difference between revisions of "VasCalc Documentation  User's Guide"
Line 11:  Line 11:  
===Installation===  ===Installation===  
If you have an uptodate copy of the [http://katlas.math.toronto.edu/svn/VasCalc/ repository], skip ahead. If not, download [http://katlas.math.toronto.edu/svn/VasCalc/trunk/ChordsMod4T.tar.gz ChordsMod4T.tar.gz] and extract it to a directory of your choice.  If you have an uptodate copy of the [http://katlas.math.toronto.edu/svn/VasCalc/ repository], skip ahead. If not, download [http://katlas.math.toronto.edu/svn/VasCalc/trunk/ChordsMod4T.tar.gz ChordsMod4T.tar.gz] and extract it to a directory of your choice.  
+  
===Usage===  ===Usage===  
Line 30:  Line 31:  
{{InOutn=4in = <nowiki>GetDimension[A]</nowiki>out=19}}  {{InOutn=4in = <nowiki>GetDimension[A]</nowiki>out=19}}  
−  as  +  Note: Our convention for representing a chord diagram in Mathematica is through a <code>CD</code> object containing <code>Line</code> and <code>Circle</code> expressions as per the skeleton. To construct such a representation, 
+  * Number the chords on the diagram.  
+  * For each line on the skeleton, put within the brackets of its <code>Line</code> expression the numbers of the chords that have their endpoints on that line, starting from the bottom and working up. For each circle, do the same, but one can choose an arbitrary starting point and count around. If there are no chords on a given line or circle, leave the brackets empty, as in <code>Line[]</code>.  
+  Naturally, there are many representations for a given diagram.  
+  One can obtain a basis for a chord diagram space (modulo 4T), expressed as a list of chord diagrams:  
{{InOutn=5 in=<nowiki>GetCDBasis[A] </nowiki>  {{InOutn=5 in=<nowiki>GetCDBasis[A] </nowiki>  
−  out=<nowiki>{CD[Line[  +  out=<nowiki>{CD[Line[1, 1], Circle[2, 2, 3, 3]], CD[Line[1, 1], Circle[2, 3, 2, 3]], 
−  CD[Line[  +  CD[Line[1], Circle[1, 2, 3, 2, 3]], CD[Line[1], Circle[1, 2, 3, 3, 2]], 
−  CD[Line[], Circle[  +  CD[Line[], Circle[1, 1, 2, 3, 3, 2]], CD[Line[1, 2, 1, 2], Circle[3, 3]], 
−  CD[Line[], Circle[  +  CD[Line[], Circle[1, 2, 1, 3, 2, 3]], CD[Line[1, 2], Circle[1, 3, 3, 2]], 
−  CD[Line[  +  CD[Line[1, 2, 2, 1], Circle[3, 3]], CD[Line[1, 2, 2], Circle[1, 3, 3]], 
−  CD[Line[], Circle[3,  +  CD[Line[], Circle[1, 2, 3, 1, 2, 3]], CD[Line[1, 2, 3], Circle[1, 3, 2]], 
−  CD[Line[3,  +  CD[Line[1, 2, 3, 2, 1, 3], Circle[]], CD[Line[1, 2, 3, 2], Circle[1, 3]], 
−  CD[Line[  +  CD[Line[1, 2, 3, 3], Circle[1, 2]], CD[Line[1, 2, 3, 2, 3, 1], Circle[]], 
−  CD[Line[3,  +  CD[Line[1, 2, 3, 2, 3], Circle[1]], CD[Line[1, 2, 3, 3, 2, 1], Circle[]], 
−  +  CD[Line[1, 2, 3, 3, 2], Circle[1]]} </nowiki> }}  
+  
+  The command <code>ReduceCD[ Diagrams, CDSpace]</code> will take a linear combination of chord diagrams, and return another linear combination that is equivalent to the first up to the relations defined. One also needs to pass on the chord diagram space in which the action takes place. For example:  
+  {{Inn=6in=<nowiki>cd = 4 CD[Line[1, 2, 2, 1, 3], Circle[3]] + CD[Line[1, 2, 2, 3, 3, 1], Circle[]];</nowiki> }}  
+  {{InOutn=7in=<nowiki>ReduceCD[cd,A]</nowiki>out=<nowiki>4 CD[Line[1, 2, 3, 3, 2], Circle[1]] + CD[Line[1, 2, 3, 3, 2, 1], Circle[]]</nowiki>}}  
===Performance Issues===  ===Performance Issues=== 
Revision as of 13:12, 9 July 2006
This page documents the ChordsMod4T component of the VasCalc project. This page is also under construction.
Contents 
Overview
This package provides a Mathematica interface to work with the space generated by chord diagrams on a fixed skeleton of lines and circles, modulo the 4T relation. See Dror BarNatan's Survey of Finite Type Invariants for further details.
Requirements
The software requirements of this package are Mathematica 4.1 and Java 1.4 (or greater, in both cases). However, note that default installations of Mathematica 4.1 and up include a Java runtime binary, and require no further configuration for this package to work.
While there are no specific hardware requirements, the computations involved are rather resourceintensive. Users of lowend machines will see a smaller range of parameters for which the computation is practicable. We'll have an expected performance profile once work on this package is done.
Installation
If you have an uptodate copy of the repository, skip ahead. If not, download ChordsMod4T.tar.gz and extract it to a directory of your choice.
Usage
In a Mathematica session, load the definitions by typing:
In[1]:=

<</path_to_install_folder/CDinterface.m

where "path_to_install_folder" is either the "trunk" folder of the repository, or the folder in which the above archive, if downloaded, was unpacked.
You must also issue the following command, to inform Mathematica of the location of the required Java objects:
In[2]:=

SetVasCalcPath["/path_to_install_folder"];

Use the command CreateCDSpace[ lines, circles, chords], to generate the space of chord diagrams with the given parameters, modulo the 4T relations. For example, we construct the space of diagrams with 3 chords on a skeleton of 1 line and 1 circle:
In[3]:=

A = CreateCDSpace[1,1,3];

One can then find the dimension of the resultant space:
In[4]:=

GetDimension[A]

Out[4]=

19

Note: Our convention for representing a chord diagram in Mathematica is through a CD
object containing Line
and Circle
expressions as per the skeleton. To construct such a representation,
 Number the chords on the diagram.
 For each line on the skeleton, put within the brackets of its
Line
expression the numbers of the chords that have their endpoints on that line, starting from the bottom and working up. For each circle, do the same, but one can choose an arbitrary starting point and count around. If there are no chords on a given line or circle, leave the brackets empty, as inLine[]
.
Naturally, there are many representations for a given diagram.
One can obtain a basis for a chord diagram space (modulo 4T), expressed as a list of chord diagrams:
In[5]:=

GetCDBasis[A]

Out[5]=

{CD[Line[1, 1], Circle[2, 2, 3, 3]], CD[Line[1, 1], Circle[2, 3, 2, 3]],
CD[Line[1], Circle[1, 2, 3, 2, 3]], CD[Line[1], Circle[1, 2, 3, 3, 2]],
CD[Line[], Circle[1, 1, 2, 3, 3, 2]], CD[Line[1, 2, 1, 2], Circle[3, 3]],
CD[Line[], Circle[1, 2, 1, 3, 2, 3]], CD[Line[1, 2], Circle[1, 3, 3, 2]],
CD[Line[1, 2, 2, 1], Circle[3, 3]], CD[Line[1, 2, 2], Circle[1, 3, 3]],
CD[Line[], Circle[1, 2, 3, 1, 2, 3]], CD[Line[1, 2, 3], Circle[1, 3, 2]],
CD[Line[1, 2, 3, 2, 1, 3], Circle[]], CD[Line[1, 2, 3, 2], Circle[1, 3]],
CD[Line[1, 2, 3, 3], Circle[1, 2]], CD[Line[1, 2, 3, 2, 3, 1], Circle[]],
CD[Line[1, 2, 3, 2, 3], Circle[1]], CD[Line[1, 2, 3, 3, 2, 1], Circle[]],
CD[Line[1, 2, 3, 3, 2], Circle[1]]}

The command ReduceCD[ Diagrams, CDSpace]
will take a linear combination of chord diagrams, and return another linear combination that is equivalent to the first up to the relations defined. One also needs to pass on the chord diagram space in which the action takes place. For example:
In[6]:=

cd = 4 CD[Line[1, 2, 2, 1, 3], Circle[3]] + CD[Line[1, 2, 2, 3, 3, 1], Circle[]];

In[7]:=

ReduceCD[cd,A]

Out[7]=

4 CD[Line[1, 2, 3, 3, 2], Circle[1]] + CD[Line[1, 2, 3, 3, 2, 1], Circle[]]

Performance Issues
We are currently working to improve the performance of this program. For larger computations, it would likely help to increase the maximum heap size available to Java. To do this, type the following into Mathematica before loading the CDinterface.m definitions (step 1 above):
In[1]:=

Needs["JLink`"];

In[2]:=

InstallJava[CommandLine > "/path_to_java_runtime/java Xmx128M"]

This allows Java to use up to 128 megabytes of memory; you may change the number "128" in the parameter "Xmx128M" to suit your needs. Note that the first line needs to be entered exactly as shown  the funny apostrophe is located next to the "1" key on many keyboards.