Difference between revisions of "VasCalc Documentation - User's Guide"

From Drorbn
Jump to: navigation, search
Line 1: Line 1:
 
This page documents the ChordsMod4T component of the [[VasCalc]] project. This page is also under construction.
 
This page documents the ChordsMod4T component of the [[VasCalc]] project. This page is also under construction.
  
===Overview===
+
==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 4-T relation. See Dror Bar-Natan's [[Survey of Finite Type Invariants]] for further details.  
 
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 4-T relation. See Dror Bar-Natan's [[Survey of Finite Type Invariants]] for further details.  
  
===Requirements===
+
==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.  
 
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 resource-intensive. Users of low-end 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.
 
While there are no specific hardware requirements, the computations involved are rather resource-intensive. Users of low-end 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===
+
==Installation==
 
If you have an up-to-date 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 up-to-date 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.
  
 
You must also ensure that there is a directory named "CM4TData" under the installation directory, creating it if neccessary. This is for save/load functionality to work properly.
 
You must also ensure that there is a directory named "CM4TData" under the installation directory, creating it if neccessary. This is for save/load functionality to work properly.
===Usage===
+
 
 +
==Usage==
 +
====Initialization====
 
In a Mathematica session, load the definitions by typing:
 
In a Mathematica session, load the definitions by typing:
  
Line 23: Line 25:
 
{{In|n=2|in=<nowiki> SetVasCalcPath["/path_to_install_folder"]; </nowiki>}}
 
{{In|n=2|in=<nowiki> SetVasCalcPath["/path_to_install_folder"]; </nowiki>}}
  
 +
====Representing Chord Diagrams====
 +
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.
 +
This package also allows for formal linear combinations of <code>CD</code> objects.
 +
 +
====Computing chord diagram spaces modulo 4T relations====
 
The object <code>CDSpace[l,m,n]</code> represents the rational vector space generated by chord diagrams with <code>n</code> chords on a skeleton with <code>l</code> lines and <code>m</code> circles, modulo the 4-T relation. The first time a space is encountered in a session, a check is made to see if there is data for the required space on disc (under the path_to_install_folder/CM4TData directory). If no such entry exists, the space is computed, and by default the results are saved on disc for future use - this computation may be substantial, depending on the values of the parameters. One can prevent the saving of data by using the command <code>CDSpace[l,m,n, WriteToDisc -> False] </code>.
 
The object <code>CDSpace[l,m,n]</code> represents the rational vector space generated by chord diagrams with <code>n</code> chords on a skeleton with <code>l</code> lines and <code>m</code> circles, modulo the 4-T relation. The first time a space is encountered in a session, a check is made to see if there is data for the required space on disc (under the path_to_install_folder/CM4TData directory). If no such entry exists, the space is computed, and by default the results are saved on disc for future use - this computation may be substantial, depending on the values of the parameters. One can prevent the saving of data by using the command <code>CDSpace[l,m,n, WriteToDisc -> False] </code>.
  
Line 29: Line 39:
 
{{InOut|n=3|in = <nowiki>GetDimension[CDSpace[1,1,3]]</nowiki>|out=19}}
 
{{InOut|n=3|in = <nowiki>GetDimension[CDSpace[1,1,3]]</nowiki>|out=19}}
  
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:
+
One can also obtain a basis for a chord diagram space (modulo 4T), expressed as a list of chord diagrams:
 
{{InOut|n=4| in=<nowiki>GetCDBasis[ CDSpace[1,1,3] ]</nowiki>|
 
{{InOut|n=4| in=<nowiki>GetCDBasis[ CDSpace[1,1,3] ]</nowiki>|
 
out=<nowiki>{CD[Line[1, 1], Circle[2, 2, 3, 3]], CD[Line[1, 1], Circle[2, 3, 2, 3]],  
 
out=<nowiki>{CD[Line[1, 1], Circle[2, 2, 3, 3]], CD[Line[1, 1], Circle[2, 3, 2, 3]],  
Line 47: Line 53:
 
   CD[Line[1, 2, 3, 3, 2], Circle[1]]} </nowiki> }}
 
   CD[Line[1, 2, 3, 3, 2], Circle[1]]} </nowiki> }}
  
The command <code>ReduceCD[ Diagrams]</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. The relevant spaces will be computed automatically. For example:
+
====Using <code>ASeries</code> objects====
{{In|n=5|in=<nowiki>cd = 4 CD[Line[1, 2, 2, 1, 3], Circle[3]] + CD[Line[1, 2, 2, 3, 3, 1], Circle[]];</nowiki> }}
+
Because operations on chord diagrams (such as multiplication and reduction) can often be resource-intensive, it is desirable to work with representations in Java to the greatest extent possible. The <code>ASeries</code> object is meant to facilitate this. One can create an
{{InOut|n=6|in=<nowiki>ReduceCD[cd]</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==
  
 
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 <i>before</i> loading the CDinterface.m definitions (step 1 above):
 
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 <i>before</i> loading the CDinterface.m definitions (step 1 above):

Revision as of 19:21, 27 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 4-T relation. See Dror Bar-Natan'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 resource-intensive. Users of low-end 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 up-to-date copy of the repository, skip ahead. If not, download ChordsMod4T.tar.gz and extract it to a directory of your choice.

You must also ensure that there is a directory named "CM4TData" under the installation directory, creating it if neccessary. This is for save/load functionality to work properly.

Usage

Initialization

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"];

Representing Chord Diagrams

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 in Line[].

Naturally, there are many representations for a given diagram. This package also allows for formal linear combinations of CD objects.

Computing chord diagram spaces modulo 4T relations

The object CDSpace[l,m,n] represents the rational vector space generated by chord diagrams with n chords on a skeleton with l lines and m circles, modulo the 4-T relation. The first time a space is encountered in a session, a check is made to see if there is data for the required space on disc (under the path_to_install_folder/CM4TData directory). If no such entry exists, the space is computed, and by default the results are saved on disc for future use - this computation may be substantial, depending on the values of the parameters. One can prevent the saving of data by using the command CDSpace[l,m,n, WriteToDisc -> False] .

One can obtain the dimension of a chord diagram space, as follows:

In[3]:= GetDimension[CDSpace[1,1,3]]
Out[3]= 19


One can also obtain a basis for a chord diagram space (modulo 4T), expressed as a list of chord diagrams:

In[4]:= GetCDBasis[ CDSpace[1,1,3] ]
Out[4]= {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]]}

Using ASeries objects

Because operations on chord diagrams (such as multiplication and reduction) can often be resource-intensive, it is desirable to work with representations in Java to the greatest extent possible. The ASeries object is meant to facilitate this. One can create an

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.