Extending/Modifying KnotTheory`

KnotTheory`/Navigation  The Mathematica Package KnotTheory` Acknowledgement Setup Naming and Enumeration Presentations Planar Diagrams Some further details Gauss Codes DT (Dowker-Thistlethwaite) Codes Braid Representatives MorseLink Presentations Arc Presentations Conway Notation Graphical Input Graphical Output Drawing Planar Diagrams How does it work? Drawing MorseLink Presentations Drawing Braids Structure and Operations Invariants Invariants from Braid Theory Three Dimensional Invariants The Alexander-Conway Polynomial The Multivariable Alexander Polynomial The Determinant and the Signature The Jones Polynomial How is the Jones polynomial computed? The Coloured Jones Polynomials The A2 Invariant Quantum knot invariants The HOMFLY-PT Polynomial The Kauffman Polynomial Finite Type (Vassiliev) Invariants Khovanov Homology Heegaard Floer Knot Homology R-Matrix Invariants Extras Included with KnotTheory` Drawing with TubePlot Standalone_TubePlot Using the LinKnot package WikiLink QuantumGroups` Lightly Documented Features A Sample KnotTheory` Session Further Usage Example Prime Links with a Non-Prime Component "Rubberband" Brunnian Links Identifying Knots within a List Cabling Burau's Theorem Further Knot Theory Software KnotPlot Knotscape Xknots Extending/Modifying KnotTheory` Bugs How to Edit this Manual...

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

Seeing the sources

The source files for KnotTheory` are kept in a Subversion repository whose overall directory structure is as follows:

http://katlas.math.toronto.edu/svn/KnotTheory/...

• trunk/... contains the current "working" version of the package.
  • KnotTheory/... is an unpacked version of the whole package, as seen by users.
  • src/... contains the individual mathematica "modules" that are glued together to make KnotTheory/init.m, the main executable of KnotTheory`.
• branches/... contains development versions of certain new features that are not yet included in the package.
• tags/...
  • 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.

Submitting Your Extension

KnotTheory` 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 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, Radmila, Dror and 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:

1. 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.
2. 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 KTtoLinKnot subpackage tries to work out the LinKnot` installation directory, using the mnemonic

LinKnotDirectory[]=
        DirectoryName[
          File/.Flatten[
              FileInformation[ToFileName[#,"LinKnots.m"]]&/@$Path]];

(The main KnotTheory` package does a similar thing in System.mm, using

KnotTheoryDirectory[] = (
  File /. Flatten[FileInformation[ToFileName[#,"KnotTheory"]] & /@ ($Path /. "." -> Directory[])]
)

)

It then tries to wrap all calls into K2K with the expression SwitchDirectories[<<do something>>], 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

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.

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 Dror or 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!