A comprehensive Julia toolkit for computational knot theory: planar diagram data structures, classical invariants, polynomial invariants, Seifert theory, Reidemeister simplification, braid word interop, and import/export helpers.

Installation

From Julia REPL

using Pkg
Pkg.add("KnotTheory")

From Git (Development)

using Pkg
Pkg.add(url="https://github.com/hyperpolymath/KnotTheory.jl")

Quick Start

using KnotTheory

k = trefoil()
println(crossing_number(k))       # 3
println(alexander_polynomial(k))   # t^-1 - 1 + t
println(jones_polynomial(k))       # -t^-4 + t^-3 + t^-1

Features

Planar diagram model with oriented crossings and multi-component links.
Code representations: PD code, DT/Dowker code, signed Gauss code, JSON serialization.
Classical invariants: crossing number, writhe, linking number, signature, determinant.
Polynomial invariants: Alexander, Jones, Conway, and HOMFLY-PT.
Seifert theory: Seifert circles, Seifert matrix, braid index estimate.
Reidemeister simplification: R1, R2, R3 moves and combined simplifier.
Braid word interop: convert between planar diagrams and braid words (TANGLE compatibility).
Knot table: built-in catalogue with named knots up to standard tables.
Graph conversion: Graphs.jl integration via to_graph.
Polynomial helpers: Polynomials.jl conversion via to_polynomial.
Optional plotting: CairoMakie-based diagram rendering via package extension.

API Reference

Types

Type	Description
`EdgeOrientation`	Enum for edge direction (`Over`, `Under`)
`Crossing`	Single crossing with strand indices and orientation
`PlanarDiagram`	Full planar diagram with crossings and components
`DTCode`	Dowker-Thistlethwaite code representation
`GaussCode`	Signed Gauss code representation
`Knot`	Named knot wrapper (e.g. `trefoil()`)
`Link`	Named link wrapper for multi-component objects

Constructors

Function	Description
`unknot()`	The unknot (zero crossings)
`trefoil()`	Trefoil knot (3_1)
`figure_eight()`	Figure-eight knot (4_1)
`cinquefoil()`	Cinquefoil knot (5_1)
`knot_table()`	Return the built-in knot table
`lookup_knot(name)`	Look up knot table entry by name

Classical Invariants

Function	Description
`crossing_number(k)`	Minimum crossing number
`writhe(pd)`	Sum of crossing signs
`linking_number(pd)`	Linking number for two-component links
`signature(k)`	Knot signature (from Seifert matrix)
`determinant(k)`	Knot determinant (
det(V + V^T)	)

Polynomial Invariants

Function	Description
`alexander_polynomial(k)`	Alexander polynomial via Seifert matrix
`jones_polynomial(k)`	Jones polynomial via skein relation
`conway_polynomial(k)`	Conway polynomial (substitution from Alexander)
`homfly_polynomial(k)`	HOMFLY-PT two-variable polynomial

Seifert Theory

Function	Description
`seifert_circles(pd)`	Seifert circle decomposition
`seifert_circles_with_map(pd)`	Seifert circles with strand-to-circle mapping
`seifert_matrix(pd)`	Seifert matrix computation
`braid_index_estimate(pd)`	Lower bound on braid index from Seifert circles

Conversion & Serialization

Function	Description
`pdcode(k)`	Planar diagram code (list of crossing tuples)
`dtcode(k)`	Dowker-Thistlethwaite code
`to_pd(x)`	Canonical conversion to planar diagram
`to_dt(x)`	Convert to DT code
`from_dt(dt)`	Convert DT code to planar diagram
`to_gauss(x)`	Convert to signed Gauss code
`from_gauss(g)`	Convert signed Gauss code to planar diagram
`write_knot_json(file,` `k)`	Serialize knot data to JSON
`read_knot_json(file)`	Deserialize knot data from JSON

Simplification

Function	Description
`simplify_pd(pd)`	Apply all Reidemeister moves until stable
`r1_simplify(pd)`	Reidemeister I: remove kinks
`r2_simplify(pd)`	Reidemeister II: cancel opposing crossings
`r3_simplify(pd)`	Reidemeister III: triangle move

Braid Words (TANGLE Interop)

Function	Description
`from_braid_word(word)`	Construct a knot from braid word
`to_braid_word(k)`	Convert knot or planar diagram to braid word

Utilities

Function	Description
`to_graph(pd)`	Convert to Graphs.jl graph structure
`to_polynomial(expr)`	Convert to Polynomials.jl polynomial
`plot_pd(pd)`	Render diagram (requires CairoMakie extension)

Development

julia --project=. -e 'using Pkg; Pkg.instantiate()'
julia --project=. -e 'using Pkg; Pkg.test()'

285 tests across 25 test sets covering all exported functions, invariant consistency, and known values from knot tables.

External Integration API

For external consumers (e.g. Skein.jl), the minimal surface is:

PlanarDiagram, Crossing, DTCode, GaussCode (core representation types)
to_pd, to_dt, to_gauss, from_dt, from_gauss (pure conversions)
crossing_number, writhe, seifert_circles, seifert_matrix
alexander_polynomial, jones_polynomial, conway_polynomial, homfly_polynomial
signature, determinant
simplify_pd, r1_simplify, r2_simplify, r3_simplify

This package intentionally does not include persistence, indexing, or database logic.

Docs & Tutorials

docs/README.md for documentation drafts.
tutorials/intro.ipynb for a minimal notebook scaffold.

References & Bibliography

Textbooks

Adams, C.C. The Knot Book. American Mathematical Society, 2004.
Lickorish, W.B.R. An Introduction to Knot Theory. Springer, 1997.
Rolfsen, D. Knots and Links. AMS Chelsea Publishing, 1976/2003.
Murasugi, K. Knot Theory and Its Applications. Birkhauser, 1996.
Kauffman, L.H. Knots and Physics. 3rd ed., World Scientific, 2001.
Cromwell, P.R. Knots and Links. Cambridge University Press, 2004.

Key Papers

Fox, R.H. "Free differential calculus. I." Annals of Mathematics 57(3), 1953, pp. 547–560.
Freyd, P. et al. "A new polynomial invariant of knots and links." Bulletin of the AMS 12(2), 1985, pp. 239–246.
Seifert, H. "Uber das Geschlecht von Knoten." Mathematische Annalen 110, 1935, pp. 571–592.
Jones, V.F.R. "A polynomial invariant for knots via von Neumann algebras." Bulletin of the AMS 12(1), 1985, pp. 103–111.

License

SPDX-License-Identifier: CC-BY-SA-4.0 See LICENSE.