Knotting Tools
Knotting Tools
This page provides software described in the paper Using the HOMFLY-PT polynomial to compute knot types by Eric Rawdon and Rob Scharein published in the book Knotted Fields. The software is open-source and in the Public Domain.
This page has the following sections.
The process for taking one knot coordinate file and converting it to a list of knot types (with crossing number 16 or smaller, or crossing number 12 or smaller, depending on some user choices) with matching HOMFLY-PT polynomial goes as follows:
knot coordinates → EGCs → Simplified EGCs → HOMFLY-PTs → matching knot types
The EGCs are extended Gauss codes, and are a way to encode the crossings in a knot/link projection. See the paper for details.
Users can drop in at any of the stages. The software used to handle the steps are:
First, a user needs to install libhomfly. The code is available from repositories for all major flavors of Linux. For example, in Fedora Linux, one can use the command:
$ sudo dnf install libhomfly
to install the libhomfly library. Note that dnf is the package handler for Fedora and other Red Hat-ish distributions. Other flavours of Linux have other package handlers, so the command will be slightly different. One can also download the libhomfly packagage from GitHub.
If the user has any difficulties building the program, we have also included a version
of jhomfly that
does not use libhomfly.
To make this version enter:
make -f Makefile-standalone
in place of the instructions below when compiling jhomfly.
The .tar.gz files from the downloads section are compressed. We will created directories for each, expand them, compile each of the programs, and then install them in the user's local bin directory. For advanced users, each of packages has a makefile, and make should be enough to compile each program.
Here's a step by step set of commands to turn the .tar.gz files into the needed executables. We assume here that the user is in a directory that contains the .tar.gz for coords2egc, xinger, jhomfly, and jidknot. We use * below in case new versions of the code are uploaded at a different time.
We assume that the user has a bin/ directory in their home directory, and that the bin/ directory is in their PATH.
Note that jidknot takes a long time to compile (from a few minutes up to an hour). Just be patient.
$ tar -xf coords2egc*.tar.gz
$ cd COORDS2EGC
$ make
$ mv coords2egc ~/bin/
$ cd ../
$ tar -xf xinger*.tar.gz
$ cd XINGER
$ make
$ mv xinger ~/bin/
$ cd ../
$ tar -xf jhomfly*.tar.gz
$ cd JHOMFLY
$ make
$ mv jhomfly ~/bin/
$ cd ../
$ tar -xf jidknot*.tar.gz
$ cd JIDKNOT
$ make
$ mv jidknot ~/bin/
$ cd ../
$ gunzip jidhomflytable.txt.gz
$ mv jidhomflytable.txt.gz ~/bin/
The file jidhomflytable.txt.gz can be downloaded as described in the download section.
These are both Python scripts and can be downloaded as described in the download section. Once these are downloaded, we will change the permissions to make the scripts executable and move them into the bin/ directory.
$ chmod ugo+rx jidknot_grep.py
$ chmod ugo+rx jidknot_table16.py
$ mv jidknot_grep.py ~/bin/
$ mv jidknot_table16.py ~/bin/
These are available in the downloads section above. They are the ones listed as optional. These are described in the section on helper scripts. Like in the last section, we will change the permissions to make the scripts executable and move them into the bin/ directory.
$ chmod ugo+rx coords2knottype.py
$ chmod ugo+rx batch_coords2egc.py
$ chmod ugo+rx batch_coords2knottypes.py
$ chmod ugo+rx egc2knottypes.py
$ mv coords2knottype.py ~/bin/
$ mv batch_coords2egc.py ~/bin/
$ mv batch_coords2knottypes.py ~/bin/
$ mv egc2knottypes.py ~/bin/
Please download the following files
The following shows what to enter (the line with the $ prompt) and what should be printed to the terminal (i.e., STDOUT). Users can include a file name as a second argument and the information will be sent to that file.
$ coords2egc 3.1.txt
a1+b2+a3+b4+b5-b1+a6+a7-a2+a5-a4+b3+b7-b6+
$ xinger +r threefiles.egc
a1+b2+a3+b1+a2+b3+
a1+b2+a3-b4+a5+a6-b7-b5+b8-b3-a9-b10+a11+a12+a2+b1+b12+a8-a4+a13-a10+b11+b6-a7-b13-b9-
a1-a2-a3+a4-b5-b3+b6-b7+b8+b9-b10-a11-b2-a12+a13-a10-a14-a8+b15-a6-b11-b1-b12+b16+b4-a5-a16+b17+a9-b14-a7+a15-a17+b13-
$ jhomfly threefiles.egc
- L^-4 - 2L^-2 + M^2L^-2
L^-2 + 3 + L^2 - M^2L^-2 - 3M^2 - M^2L^2 + M^4
2L^4 - L^8 + M^2L^2 - 2M^2L^4 + M^2L^6
There are three programs that convert HOMFLY-PT polynomials to matching knot types. They are desribed in more detail in the sections jidknot, jidknot_grep.py and jidknot_table16.py. The corresponding commands are:
$ jidknot -k threefiles.hf
p3.1
a6.3
m7.4
$ jidknot_grep.py threefiles.hf
p3.1
a6.3
m7.4
$ jidknot_table16.py threefiles.hf
p3.1
a6.3
m7.4
$ coords2egc 7.4.txt | xinger +r -- | jhomfly -- | jidknot -k --
m7.4
This string of commands inputs the coordinate file 7.4.txt and outputs its knot type. The -- tells the programs to accept input from STDIN instead of a file.
We have created some helper scripts, described in the next section, to help with some popular tasks. These scripts are not fancy, essentially handling the piping internally so that the user does not need to remember all of the commands.
These scripts are all written in Python and are intended to perform popular tasks without the user having to remember the syntax of each of the programs.
$ coords2knottype.py 7.4.txt
m7.4
This is the same as the piping done in the section on POSIX pipes.
The full usage is
$ coords2knottype.py [-n] [-f tablefile|j] coordinate-file
coords2knottype.py converts one coordinate file to the list of knot types with matching HOMFLY-PT polynomial. By default, the program uses coords2egc, xinger, jhomfly, the code base for jidknot_grep.py, and the file jhomflytable.txt. The program returns unknown if the HOMFLY-PT polynomial does not match anything in the given conversion table. By default, the HOMFLY-PT is matched versus all knot types through 16 crossings using jhomflytable.txt. This changes if one invokes the optional -j or -f tablefile flags.
The optional flags are:
$ batch_coords2egc.py threefiles.txt
a1+b2+a3+b4+b5-b1+a6+a7-a2+a5-a4+b3+b7-b6+
a1+b2+a3-b4+a5+a6-b7-b8+b9-b5+b10-b11+b12-b3-a13-b14+a8+a7-a15+a10-a11+a16+a2+a17-a18+b1+b16+a12-a4+a19-a14+b15+b6-a9-b19-b13-b17-b18+
b1+b2-a3-a4+b5-b6+b7+a8-b9-a10+a11-a7+b12-a13-a14-a15+a2-a1+a16-b3-b15+b17-b10+b18+b8-b19-a20-b14-a21+a5-a6+a12-a19-a9-a18+b11-a17-b20-b13-b21+b4+b16-
To save the information to a file, use:
$ batch_coords2egc.py threefiles.txt < threefiles.egc
The full usage is:
$ batch_coords2egc.py file-of-coordinate-file-names
The file file-of-coordinate-file-names should list the names of the coordinate files, one per line, whose EGCs are desired. This program repeatedly calls coords2egc and outputs to the terminal.
$ batch_coords2knottypes.py threefiles.txt
p3.1
a4.1
m7.4
To save the information to a file, use:
$ batch_coords2knottypes.py threefiles.txt < threefiles.knottypes
The full usage is:
$ batch_coords2knottypes.py [-n] [-j|-f tablefile] file-of-coordinate-file-names
batch_coords2knottype.py converts a file of file names of coordinate file to a list of knot types with matching HOMFLY-PT polynomials. By default, the program uses coords2egc, xinger, jhomfly, the code base for jidknot_table16.py, and the file jhomflytable.txt. The file file-of-coordinate-file-names should list the names of the coordinate files, one per line, whose EGCs are desired.
The optional flags are:
$ egc2knottypes.py threefiles.egc
p3.1
a4.1
m7.4
The full usage is:
$ egc2knottypes.py [-n] [-j|-f tablefile] file-of-egcs
egc2knottypes.py converts a file EGCs to a list of knot types with matching HOMFLY-PT polynomials. By default, the program uses xinger, jhomfly, the code base for jidknot_table16.py, and the file jhomflytable.txt. The file file-of-egcs should list the EGCs, one per line.
The optional flags are:
coords2egc is a simple tool that reads a plain text file containing the x, y, and z coordinates of a closed polygon and outputs an EGC. The usage is:
$ coords2egc coordinate-file [file-containing-egc]
The coordinate-file should list the x, y, and z coordinates for each vertex, one per line. The second argument is optional. If a second file is not included, then the output is printed to the terminal.
For example, the following
-3 -4 5
2 -3 8
4 -1 6
2 0 -2
-8 -5 -1
-3 -7 0
0 5 1
0 5 7
2 -5 4
7 1 4
-3 4 1
-4 4 -2
-4 -4 -3
forms a 13-gon whose knot type is 63.
For links, different components are separated with a blank line, as in
0.10 -3.29 -0.49
1.11 0.69 0.13
-1.64 -0.27 0.26
0.01 2.30 0.44
-0.07 2.10 -0.87
0.48 -1.55 0.53
which has two-components, both of which have three edges, and
represents the Hopf Link 221.
Note that coords2egc takes a single file with knot coordinates and outputs a single EGC. The Python scripts batch_coords2egc.py and batch_coords2knottypes.py convert a number of coordinate files to EGCs and knot types, respectively.
xinger converts a file of EGCs (see threefiles.egc for an example), one per line, and returns a list of EGC codes which have been simplified (to the extent possible) using Reidemeister I and II moves. Since the HOMFLY-PT computation is (in theory) exponential on the number of crossings in a given projection, this step can save a lot of computation time. The use of xinger is optional. The usage to simplify a file of EGCs is:
$ xinger +r file-of-egcs [file-of-simplified-egcs]
If a second file is not included, then the output is printed to the terminal.
jhomfly converts a file of EGCs (see threefiles.egc for an example), one per line, and returns a list of HOMFLY-PT polynomials.
The tool jhomfly is a wrapper around the code written by Bob Jenkins in 1990, improved by him in 2010, and then modified by Marco Miguel to be a shared library libhomfly. Miguel made several improvements to the software and released it on GitHub. Because the original code was placed in the Public Domain by Jenkins, Miguel maintained this classification as do we.
$ jhomfly file-of-egcs [file-o-HOMFLYPTs]
If a second file is not included, then the output is printed to the terminal.
We provide the tool jhomfly that is a wrapper around the code written by Bob Jenkins in 1990, improved by him in 2010, and then modified by Marco Miguel to be a shared library libhomfly. Miguel made several improvements to the software and released it on GitHub. Because the original code was placed in the Public Domain by Jenkins, Miguel maintained this classification as do we.
There are three different versions of a tool that converts a file of HOMFLY-PT polynomials to a list of lists of knot/link types with matching HOMFLY-PT polynomials. The program jidknot has a different lookup table than jidknot_grep.py and jidknot_table16.py. The lookup table for jidknot contains all of the knot types through crossing number 12, plus the links in the Rolfsen tables. The lookup tables for jidknot_grep.py and jidknot_table16.py are jhomflytable.txt by default, which contains all knot types through crossing number 16. The programs will output unknown if the a HOMFLY-PT polynomial is not in the given programs lookup table, but this means different things depending on which program is being used.
jidknot converts a file of HOMFLY-PT polynomials output by jhomfly (see threefiles.hf for an example), one per line, and returns a list of knots types who share the given HOMFLY-PT polynomial. jidknot contains all of the knot types through crossing number 12, plus the links in the Rolfsen tables. This is the quickest of the three options.
The full usage is:
$ jidknot -k file-of-HOMFLYPTs [file-of-matching-knot-types]
If a second file is not included, then the output is printed to the terminal.
jidknot_grep.py converts a file of HOMFLY-PT polynomials output by jhomfly (see threefiles.hf for an example), one per line, and returns a list of knots types who share the given HOMFLY-PT polynomial. The default lookup table for jidknot_grep.py contains all of the knot types through crossing number 16.
The full usage is:
$ jidknot_grep.py [-f tablefile] file-of-HOMFLYPTs
The output is printed to the terminal. The lookup table file defaults to jhomflytable.txt, although it can be set to some other table using the optional flag -f tablefile. This program uses the system command grep and is best for situations where there are not too many EGCs (like less than 100), but the EGCs form knot types with crossings numbers greater than 12.
jidknot_table16.py converts a file of HOMFLY-PT polynomials output by jhomfly (see threefiles.hf for an example), one per line, and returns a list of knots types who share the given HOMFLY-PT polynomial. The default lookup table for jidknot_table16.py contains all of the knot types through crossing number 16. This program creates a Python dictionary file from table file. As such, the startup for the program takes a couple of seconds, which is why jidknot_grep.py might be a better choice for small numbers of knots.
The full usage is:
$ jidknot_table16.py [-f tablefile] file-of-HOMFLYPTs
The output is printed to the terminal. The lookup table file defaults to jhomflytable.txt, although it can be set to some other table using the optional flag -f tablefile.
A table of HOMFLY-PT polynomials for prime and composite knots to 16 crossings was compiled by Eric Rawdon. The download information is in the section on download and the installation information is in the section on installation.
The following description of the file comes from the paper.
The file jhomflytable.txt contains the translation from jhomfly output to knot types matching the HOMFLY-PT polynomial. The file is comma-delimited, with the first slot containing the HOMFLY-PT output from jhomfly. This is followed by a comma-separated list of knot types (prime and composite through crossing number 16) matching the given HOMFLY-PT polynomial.
The prime knot types have a prefix of "p", "m", "h", or "a". The prefix "a" means that the knot type is achiral. The prefix "h" means that the knot type is chiral, but both chiralities (i.e., a configuration realizing the knot type and its mirror image) share the same HOMFLY-PT polynomial. If the knot type is chiral and the HOMFLY-PT polynomial differs between the two chiralities, then one of the chiralities has been assigned "p" (denoting ``plus'') and the other had been assigned "m" (denoting ``minus'') using the process described in the next paragraph. Note that the "p" versus "m" designations were assigned by author Rawdon. They are not ``the standard'', yet anybody performing such a designation is likely to agree with these for most of the knot types. If one disagrees with the designations, just know that the "p" versus "m" versions of a knot type are mirror images.
To designate a "p" versus "m" for a chiral knot type whose mirror images have different HOMFLY-PT polynomials, we started by computing the planar writhe of a minimum-crossing diagram representative of the knot type. If the value was positive, then the knot type was assigned a "p", and its mirror image "m". If the value was negative, then the knot type was assigned an "m", and its mirror image "p". If the writhe of the diagram was zero, then we performed knot energy minimization in KnotPlot on a configuration forming the given knot type. The assignment of "p" versus "m" was then based on the sign of the spatial writhe of the minimizing configuration. Note that some of these spatial writhes were very close to zero, and this is where our designations could disagree from other strategies.
For prime knot types through crossing number 10, we use Alexander-Briggs-Conway notation. For prime knot types from crossing number 11 through 16, we use a slight variation of Dowker-Thistlethwaite notation. For example, the knot type -11a99 is denoted m11.99a and the knot type +11n27 is denoted p11.27n.
For composite knot types, the prime factor knots are ordered by crossing number and factor knot types are separated by #, which denotes the connected sum (i.e., knot composition). If there are two chiralities of the same knot type appearing as factors, then the "p" factor(s) appear before the "m" factor(s). For example, p3.1#m3.1 appears, not m3.1#p3.1.
As of 6 May 2023, KnotPlot has a version of jhomfly and jidknot included with the KnotPlot distribution. The KnotPlot command is homfly-pt (with the alternate commands names homflypt, homfly and flypmoth if you prefer one of those spellings).
Users can directly ID the currently loaded knot or link using the id command.
KnotPlot can also be configured to using your choice of one of the above versions of jhomfly or jidknot instead of its somewhat more limited built-in versions. Details on how to do this are forthcoming.
We would like to thank Xin Liu, Renzo Ricca, and Beijing University of Technology for hosting the conference on Knotted Fields and for their enthusiasm in this endeavour. RGS would like to thank Chris Soteros at the University of Saskatchewan for support in developing recent versions of jhomfly and jidknot as well as Mariel Vazquez at the University of California Davis for support during the original development of those tools, as well as xinger. This material is based upon work supported by the National Science Foundation under Grant No. 1720342 to EJR. EJR also wishes to thank Addie McCurdy, whose work was critical in creating the tables which were used to count chiral knot types. EJR also thanks the University of St. Thomas’s Center for Applied Mathematics, which has supported several student projects related to this work.