cppkh

cppkh is a standalone C++14 port of the integer JavaKh Khovanov homology computation path.

Quick Start

Python package:

pip install cppkh-interface

import cppkh_interface

pd_code = [[1, 5, 2, 4], [3, 1, 4, 6], [5, 3, 6, 2]]

print(cppkh_interface.solve_khovanov(pd_code))
print(cppkh_interface.solve_many_khovanov([pd_code, pd_code]))

The Python package has no runtime Python-package dependencies. It ships the canonical cppkh C++ source, compiles it with a local C++14 compiler on first use, and caches the resulting executable. Set CPPKH_INTERFACE_CXX or CXX to choose a specific compiler.

Build the fastest executable that the current machine can support:

python build.py

Run one PD code:

dist\windows\cppkh.exe --pd-code "PD[X[1,5,2,4],X[3,1,4,6],X[5,3,6,2]]"

On Linux the default output is dist/linux/cppkh; on macOS it is dist/macos/cppkh.

Run a file or directory:

dist\windows\cppkh.exe --pd-file path\to\codes.txt
dist\windows\cppkh.exe --pd-dir path\to\pdcode_directory

R1-move removal and then nugatory-crossing removal are enabled by default.

Performance Snapshot

On the full 8397-case benchmark, cppkh and the patched bundled JavaKh matched every result. cppkh finished in 64.185s, cppkh-interface batch API finished in 65.406s after its executable was already cached, and the patched bundled JavaKh native multiline runner finished in 298.453s. The PyPI javakh-interface package was checked on a deterministic random 100-case sample and averaged 0.586s per PD code.

Peak RSS on the same prepared full input was 26.05 MiB for cppkh, 60.23 MiB for cppkh-interface as a Python batch API call, and 491.55 MiB for patched JavaKh. The previous PyPI javakh-interface 50-case memory sample peaked at 161.19 MiB.

Shared Library

Build a shared library instead of an executable:

python build.py --shared --name cppkh

This produces cppkh.dll, libcppkh.so, or libcppkh.dylib, depending on the platform. Any non-system runtime libraries found by build.py are copied beside it.

Documentation

• Build and packaging options
• Command-line options
• Algorithm notes
• Python ctypes interface
• cppkh-interface Python package
• Testing against JavaKh
• Bundled JavaKh reference
• Benchmark results

Tests

Run the orientation and JavaKh comparison suite:

python tools/test_pd_orientation.py

Run the dependency-free Python interface regression directly from a fresh checkout. The script adds the included python_project/cppkh-interface source tree itself, so installing the package first is not required:

python tools/test_cppkh_interface_standalone.py --force-compile

See Testing against JavaKh for the full consistency datasets, tool requirements, and benchmark-oriented tests.

References

• Knot Atlas: Planar Diagrams
• Knot Atlas: Khovanov Homology

Original JavaKh

cppkh follows the integer JavaKh computation path. The original JavaKh-v2 project is available at geometer/JavaKh-v2.

Citation

If you use cppkh in academic work, please cite this repository:

@software{cppkh_2026,
  author = {{GGN\_2015}},
  title   = {{cppkh}: A C++ implementation of the JavaKh Khovanov homology computation path},
  year    = {2026},
  url     = {https://github.com/TopologicalKnotIndexer/cppkh},
  version = {0.1.3}
}