View source for Extending/Modifying KnotTheory`

{{Manual TOC Sidebar}}

Anybody is welcome, indeed encouraged, to fix, modify or extend the package <code>KnotTheory`</code> to the benefit of everybody else. This note explains how this can be done and outlines some of the conventions used within <code>KnotTheory`</code>.

===Seeing the sources===

The source files for <tt>KnotTheory`</tt> are kept in a [http://subversion.tigris.org/ Subversion] repository whose overall directory structure is as follows:

[http://katlas.math.toronto.edu/svn/KnotTheory/ http://katlas.math.toronto.edu/svn/KnotTheory/...]
* [http://katlas.math.toronto.edu/svn/KnotTheory/trunk/ trunk/...] contains the current "working" version of the package.
** [http://katlas.math.toronto.edu/svn/KnotTheory/trunk/KnotTheory/ KnotTheory/...] is an unpacked version of the whole package, as seen by users.
** [http://katlas.math.toronto.edu/svn/KnotTheory/trunk/src/ src/...] contains the individual mathematica "modules" that are glued together to make [http://katlas.math.toronto.edu/svn/KnotTheory/trunk/KnotTheory/init.m KnotTheory/init.m], the main executable of <tt>KnotTheory`</tt>.
* [http://katlas.math.toronto.edu/svn/KnotTheory/branches/ branches/...] contains development versions of certain new features that are not yet included in the package.
* [http://katlas.math.toronto.edu/svn/KnotTheory/tags/ tags/...]
** [http://katlas.math.toronto.edu/svn/KnotTheory/tags/stable stable/...] contains the last "stable" version of the package. It is a snapshot of the trunk/ directory, at some previous moment in time. "Stable" doesn't necessarily mean any great degree of testing has gone on; it just means that the most recently introduced bugs in the trunk haven't been included. The downloadable package is generated from this directory.

===Writing Your Extension===

===Submitting Your Extension===

<code>KnotTheory`</code> is a computer program written in an unrestricted language. Meaning that a vicious programmer could use it to do harmful things to the computer running it. Therefore unlike much of the rest of the Knot Atlas, it can be modified directly only by the administrators of this site. If you aren't one, email your extension/modification to [[User:Drorbn|Dror]]. Dror will read through it quickly to confirm that it's not malicious and doesn't do anything obviously wrong and post it in the [[Setup]] section of this manual. Thanks!

===Lessons learnt from integrating LinKnot`===
In February 2006, [[User:Radmila|Radmila]], [[User:Dror|Dror]] and [[User:Scott|Scott]] spent a few days making LinKnot` and KnotTheory` play nicely together. In the end, we had at least partially achieved two of our goals:

# Allowing the concurrent usage of KnotTheory` with LinKnot`, so that users of LinKnot` can access the databases and algorithms available in KnotTheory`, while maintaining familiar notations and function names.
# Making the functionality of LinKnot` transparently available to users of KnotTheory` (with function names and data conventions consistent with KnotTheory`).

These two goals seem to be a reasonable model for integrating a pair of complementary Mathematica packages; former users of each expect not much to change, but simply to have extra functionality. It's also a reasonable 'minimal' model, in that only 'compatibility layers' are written, leaving the original packages (mostly) unchanged.

====Loading side by side====
Our first goal was simply to be able to load KnotTheory` and LinKnot` side by side. Initially, we were prevented by two different problems. Firstly, each package unintentionally introduced symbols into the Global` Mathematica context. Secondly, each package expected that the current working directory always be the home of the package; expectations unsatisfiable simultaneously!

=====Global` symbols=====
Fixing leakages from KnotTheory` wasn't too hard; just load KnotTheory` in a fresh Mathematica session, then issue the command Names["Global`*"]. There shouldn't be much there, and it's mostly a matter of tracking down where the stray symbols have been introduced. If you don't understand Mathematica's (utterly ugly) system of contexts, you'll start to get the hang of it while doing this!

Leakages from LinKnot` were much more serious, as several subpackages were loaded directly into the Global` context (the authors of K2K didn't follow the usual Mathematica package conventions).

At this point we discovered the first of several painful problems associated with symbols in contexts which aren't currently on the context path, namely that conversions to and from strings (with ToString and ToExpression) are very dangerous. These happen 'at runtime', so the context path could be quite arbitrary (that is, having been modified by other packages or users since the package was loaded), rather than at the moment the package is loaded. It is often necessary to wrap calls to ToExpression with code which temporarily resets the context path. Seaching for ToExpression in the LinKnot sources should find examples of this.

=====Current working directory=====
Unfortunately many parts of the K2K package rely on the current working directory being the LinKnot` installation directory. This causes all sorts of problems; users should be able to change the current working directory arbitrarily. Even worse, there are still some bugs in KnotTheory` where certain things don't work if the current working directory isn't set to the KnotTheory` installation directory!

We used two techniques to get around this. First, the [http://katlas.math.toronto.edu/svn/KnotTheory/trunk/src/KTtoLinKnot.m KTtoLinKnot] subpackage tries to work out the LinKnot` installation directory, using the mnemonic
<pre>
LinKnotDirectory[]=
        DirectoryName[
          File/.Flatten[
              FileInformation[ToFileName[#,"LinKnots.m"]]&/@$Path]];
</pre>

(The main KnotTheory` package does a similar thing in [http://katlas.math.toronto.edu/svn/KnotTheory/trunk/src/System.mm System.mm], using
<pre>KnotTheoryDirectory[] = (
  File /. Flatten[FileInformation[ToFileName[#,"KnotTheory"]] & /@ ($Path /. "." -> Directory[])]
)</pre>)

It then tries to wrap all calls into K2K with the expression <code>SwitchDirectories[<<do something>>]</code>, which changes the current path, and context path, before executing the wrapped code, and restores it after completion. If you're trying to make more K2K functionality available, by modifyin KTtoLinKnot, you should look carefully at what we've already done for other functions.

====Transparently calling LinKnot` from KnotTheory`====
Setting up LinKnot` for use with KnotTheory` is pretty simple. If you try using a function that relies on LinKnot`, for example converting conway notations to other notations, and don't have LinKnot` installed, you'll get a message along the lines of 

<pre>
The function "ConwayNotation" requires the LinKnot package, which is not distributed as part of KnotTheory. I couldn't seem to load it; try downloading it from http://www.mi.sanu.ac.yu/vismath/linknot/, and adding the appropriate directory to the $Path.
</pre>

And this should be all that's necessary!

At present, the compatibility layer for LinKnot` provdes Conway notation conversion programs (both directions, although it seems infeasible to calculate conway notations for knots with more than 12 crossings), knot drawing and 'by-mouse' knot input.

===Advanced SVN usage===
If you have already made some contributions to the KnotTheory` package, it's possible you have direct commit access to the Subversion server. (Please ask [[User:Dror|Dror]] or [[User:Scott|Scott]] if you think you need it too.) This part of the manual documents some advanced tasks for those with commit access; probably only Dror for now.

====Making a new stable release====
You'll need a working copy that includes both the tags/ and trunk/ directories of the SVN project. Update everything! Go to the /tags/stable directory, and do an svn merge. You need to specify the beginning and end revisions; the beginning revision should be the head of the /tags/stable, the end revision should be either the head, or a recent revision of /trunk.

Please let me know if this works or not!