Usage » Getting Started

Compiling kht++ from source

1. You will need a C++ compiler supporting the C++17 standard, such as clang++ or g++. We also recommend that you install the version control system git. On ubuntu 20.04, you can install these prerequisites by running the following command:

   sudo apt update
   sudo apt install build-essential clang git
   

2. kht++ depends on the C++ Standard Template Library and the Eigen Template Library. The former will probably be installed on your system already, once you have installed a compiler. To install the latter, download the tar/zip file from the Eigen Website and decompress it into some folder. Since Eigen is a pure template library, this is all you need to do with it.

3. Next, you need the kht++ source files. They are available from the kht++ github repository. If you have a github account, you clone the repository in the usual way:

   git clone git@github.com:cbz20/khtpp.git        # via ssh, or
   git clone https://github.com/cbz20/khtpp.git    # via https
   

   If you do not have a github account, you can clone the repository with the following command

   git clone https://github.com/cbz20/khtpp.git
   

   You can also download the source files directly, but this is not recommended.

4. Navigate to the folder khtpp

   cd khtpp
   

   and open the file makefile in a text editor. The first line should read as follows:

   PATH_EIGEN = ../libraries/Eigen
   

   Replace the path ../libraries/Eigen as appropriate, such that it points to the folder containing the Eigen Template Library. (This is the folder containing various subfolders and files such as 'bench', 'cmake', 'INSTALL', 'README.md', etc.) If you want to compile using g++ instead of clang++, you also need to comment/uncomment the relevant lines in the makefile setting the variable CXX. Then run

   make
   

   This creates a number of binary files, of which kht++ is the main one. If you did not encounter any error message or warning, you are now ready to use the program. If you are eager to see kht++ in action, skip to the Basic Examples.

Binaries

If you prefer to use precompiled binaries, you can download them here. They are currently only available for ubuntu 20.04.

Compiling the documentation

For the documentation, you need Doxygen (version ≥ 1.9.1) and m.css. The latter should either be installed into the directory docs, or you need to modify the path in the makefile appropriately. Then run

make docs

The main page of the documentation is docs/html/index.html.

A first example

Let us compute the Bar-Natan homology of a trefoil knot. For this, run

./kht++ examples/tests/3_1.kht

The output should look similar to the following:

>>>
>>> Computation for 'examples/tests/3_1':
>>>
1 r1    ↑  ↷ 
| y0     ⤫  ↓ 
| y0     ⤫  ↓ 
| y0     ⤫  ↓ 
5 u1    ↑   ͝
>>> computations for -c2:
Computed cobordism complex with 3 generators in 0.002s.
The complex is already loop-type.
1) h^0 q^2 δ^1 ⬮
2) h^2 q^6 δ^1 ⬮——H—>⬮

You can also view this output in your browser by either opening the file examples/tests/3_1.html directly or typing

./kht++ examples/tests/3_1.kht -w

For more details on the parameter -w, see Recompile and open output in browser.

A second example

Let us compute the immersed curve invariant for the (2,-3)-pretzel tangle:

For this, run

./kht++ examples/tests/PT2m3.kht

The output should look similar to the following:

>>>
>>> Computation for 'examples/tests/PT2m3':
>>>
1 l1    ↑  ↶ 
| x2    ↑ ↓  ⤬ 
| y0     ⤫  ↑ ↑ 
| x2    ↓ ↑  ⤬ 
5 y0     ⤫  ↑ ↑ 
| x2    ↑ ↓  ⤬ 
7 u1    ↑   ͝
>>> computations for -c2:
Computed cobordism complex with 9 generators in 0.008s.
Cleaned-up complex in 10 iterations and 0.001s.
1) h^-2 q^-7 δ^-3/2 ⬮<—D——⬮<~⬯<—⬯~>⬮—>⬮~>⬮—>⬮~>⬯
Cleaned-up complex in 10 iterations and 0.004s.
1) h^-5 q^-11 δ^-1/2 ⬯~~S~>⬮—>⬮~>⬮<—⬮<~⬯<—     r(1/2) q^-26/3 δ|^-1
2) h^-6 q^-13 δ^-1/2 ⬯~~S~>⬮—>⬮~>⬮—>⬮~>⬯—>⬯<~⬮<—⬮<~⬮<—⬮<~⬯<—     s4(0) q^-8 δ|^-1

Again, you can view a nicely formatted output by rerunning the previous command with the option -w:

./kht++ examples/tests/PT2m3.kht -w

Further Reading

You might be wondering now what the above outputs mean and how to do computations for your own knots, links, and tangles. These questions are answered on the following pages:

• Input
• Output
• Options