Release Manager · Release Manager · commit e48fde667e3f · 2025-08-25T19:36:24.000+02:00
gh-40081: Integration of a new optional package for Khovanov homology       Sage has a native implementation of Khovanov homology. Unfortunately, it's not very performant. For knots and links with more than six crossings, the calculation takes more than a second on a ThinkPad with an i7 (i7-1165G7 @ 2.80GHz) processor (running Ubuntu under WSL2). For a knot with nine crossings, it takes more than a minute, and for 10 crossings, the calculation breaks (after about an hour) with a `Pari stack overflow`: ``` sage: K7 = Knots().from_table(7,1) ....: K8 = Knots().from_table(8,1) ....: K9 = Knots().from_table(9,1) ....: K10 = Knots().from_table(10,1) sage: %time K7.khovanov_homology() CPU times: user 679 ms, sys: 0 ns, total: 679 ms Wall time: 679 ms {-21: {-7: Z}, -19: {-7: 0, -6: C2}, -17: {-7: 0, -6: Z, -5: Z}, -15: {-7: 0, -6: 0, -5: 0, -4: C2}, -13: {-7: 0, -6: 0, -5: 0, -4: Z, -3: Z}, -11: {-7: 0, -6: 0, -5: 0, -4: 0, -3: 0, -2: C2}, -9: {-7: 0, -6: 0, -5: 0, -4: 0, -3: 0, -2: Z, -1: 0, 0: 0}, -7: {-7: 0, -6: 0, -5: 0, -4: 0, -3: 0, -2: 0, -1: 0, 0: Z}, -5: {0: Z}} sage: %time K8.khovanov_homology() CPU times: user 22.9 s, sys: 74.1 ms, total: 23 s Wall time: 23 s {-13: {-6: Z}, -11: {-6: 0, -5: C2, -4: 0, -3: 0}, -9: {-6: 0, -5: Z, -4: Z, -3: 0, -2: 0, -1: 0}, -7: {-6: 0, -5: 0, -4: 0, -3: Z x C2, -2: 0, -1: 0, 0: 0, 1: 0}, -5: {-6: 0, -5: 0, -4: 0, -3: Z, -2: Z x C2, -1: 0, 0: 0, 1: 0, 2: 0}, -3: {-6: 0, -5: 0, -4: 0, -3: 0, -2: Z, -1: Z x C2, 0: 0, 1: 0, 2: 0, 3: 0}, -1: {-4: 0, -3: 0, -2: 0, -1: Z, 0: Z x C2, 1: 0, 2: 0, 3: 0, 4: 0}, 1: {-3: 0, -2: 0, -1: 0, 0: Z x Z, 1: Z, 2: 0, 3: 0, 4: 0}, 3: {-1: 0, 0: 0, 1: 0, 2: C2, 3: 0, 4: 0}, 5: {1: 0, 2: Z, 3: 0, 4: 0}} sage: %time K9.khovanov_homology() CPU times: user 1min 23s, sys: 260 ms, total: 1min 23s Wall time: 1min 23s {-27: {-9: Z}, -25: {-9: 0, -8: C2}, -23: {-9: 0, -8: Z, -7: Z}, -21: {-9: 0, -8: 0, -7: 0, -6: C2}, -19: {-9: 0, -8: 0, -7: 0, -6: Z, -5: Z}, -17: {-9: 0, -8: 0, -7: 0, -6: 0, -5: 0, -4: C2}, -15: {-9: 0, -8: 0, -7: 0, -6: 0, -5: 0, -4: Z, -3: Z}, -13: {-9: 0, -8: 0, -7: 0, -6: 0, -5: 0, -4: 0, -3: 0, -2: C2}, -11: {-9: 0, -8: 0, -7: 0, -6: 0, -5: 0, -4: 0, -3: 0, -2: Z, -1: 0, 0: 0}, -9: {-9: 0, -8: 0, -7: 0, -6: 0, -5: 0, -4: 0, -3: 0, -2: 0, -1: 0, 0: Z}, -7: {0: Z}} sage: %time K10.khovanov_homology() Traceback (most recent call last): ... PariError: the PARI stack overflows (current size: 1073741824; maximum size: 1073741824) You can use pari.allocatemem() to change the stack size and try again ``` If we do the same with the optional package `Khoca` implemented in this PR, we get the following: The knot with 9 crossings takes less than half a second and the example with 10 crossings terminates after less than two seconds: ``` sage: %time K9.khovanov_homology(implementation='Khoca') CPU times: user 268 ms, sys: 44.7 ms, total: 313 ms Wall time: 293 ms {-27: {-9: Z}, -25: {-9: 0, -8: C2}, -23: {-9: 0, -8: Z, -7: Z}, -21: {-8: 0, -7: 0, -6: C2}, -19: {-7: 0, -6: Z, -5: Z}, -17: {-6: 0, -5: 0, -4: C2}, -15: {-5: 0, -4: Z, -3: Z}, -13: {-4: 0, -3: 0, -2: C2}, -11: {-3: 0, -2: Z}, -9: {0: Z}, -7: {0: Z}} sage: %time K10.khovanov_homology(implementation='Khoca') CPU times: user 1.55 s, sys: 123 ms, total: 1.68 s Wall time: 1.65 s {-17: {-8: Z}, -15: {-8: 0, -7: C2}, -13: {-8: 0, -7: Z, -6: Z}, -11: {-7: 0, -6: 0, -5: Z x C2}, -9: {-6: 0, -5: Z, -4: Z x C2}, -7: {-5: 0, -4: Z, -3: Z x C2}, -5: {-4: 0, -3: Z, -2: Z x C2}, -3: {-3: 0, -2: Z, -1: Z x C2}, -1: {-2: 0, -1: Z, 0: Z x C2}, 1: {-1: 0, 0: Z x Z, 1: Z}, 3: {0: 0, 1: 0, 2: C2}, 5: {1: 0, 2: Z}} ``` Even knots with 13 crossing only need a few seconds: ``` sage: K13 = KnotInfo.K13a_1.link() sage: %time K13.khovanov_homology(implementation='Khoca') CPU times: user 2.28 s, sys: 578 ms, total: 2.86 s Wall time: 2.6 s {-17: {-8: Z}, -15: {-8: 0, -7: Z x Z x Z x C2}, -13: {-8: 0, -7: Z, -6: Z^7 x C2 x C2 x C2}, -11: {-7: 0, -6: Z x Z x Z, -5: Z^13 x C2^7}, -9: {-6: 0, -5: Z^7, -4: Z^19 x C2^13}, -7: {-5: 0, -4: Z^13, -3: Z^24 x C2^19}, -5: {-4: 0, -3: Z^19, -2: Z^27 x C2^24}, -3: {-3: 0, -2: Z^24, -1: Z^25 x C2^27}, -1: {-2: 0, -1: Z^27, 0: Z^22 x C2^25}, 1: {-1: 0, 0: Z^26, 1: Z^16 x C2^21}, 3: {0: 0, 1: Z^21, 2: Z^9 x C2^16}, 5: {1: 0, 2: Z^16, 3: Z x Z x Z x Z x C2^9}, 7: {2: 0, 3: Z^9, 4: Z x C2 x C2 x C2 x C2}, 9: {3: 0, 4: Z x Z x Z x Z, 5: C2}, 11: {4: 0, 5: Z}} ``` The software behind the optional package is [Khoca](http://lewark.de/lukas/khoca.html). It was written in C++ by [Lukas Lewark](https://people.math.ethz.ch/~llewark/index.php). I packaged it on [PyPI](https://pypi.org/project/khoca/) for integration into Sage (see LLewark/khoca#3). Currently, there is still an issue with the PyPI package regarding integration with Sage, as both use the Pari library (see LLewark/khoca#3 (comment)). This occurs sporadically and triggers a system error that occurs at `cypari2/stack.pyx`. The error disappears when the last action is re- executed. I'm leaving this PR as a draft until the issue is resolved. ### 📝 Checklist  - [x] The title is concise and informative. - [x] The description explains in detail what this PR is about. - [x] I have linked a relevant issue or discussion. - [x] I have created tests covering the changes. - [x] I have updated the documentation and checked the documentation preview. ### ⌛ Dependencies    URL: #40081 Reported by: Sebastian Oehms Reviewer(s): Sebastian Oehms, Travis Scrimshaw
diff --git a/build/pkgs/khoca/SPKG.rst b/build/pkgs/khoca/SPKG.rst
@@ -0,0 +1,18 @@
+khoca: Khoca as pip installable package
+=======================================
+
+Description
+-----------
+
+Khoca as pip installable package
+
+License
+-------
+
+GPLv2+
+
+Upstream Contact
+----------------
+
+https://pypi.org/project/khoca/
+
diff --git a/build/pkgs/khoca/dependencies b/build/pkgs/khoca/dependencies
@@ -0,0 +1,5 @@
+ ipython cypari | $(PYTHON_TOOLCHAIN) sagelib $(PYTHON)
+
+
+----------
+All lines of this file are ignored except the first.
diff --git a/build/pkgs/khoca/package-version.txt b/build/pkgs/khoca/package-version.txt
@@ -0,0 +1 @@
+1.4
diff --git a/build/pkgs/khoca/requirements.txt b/build/pkgs/khoca/requirements.txt
@@ -0,0 +1,2 @@
+# See https://github.com/sagemath/sage/pull/40081
+khoca
diff --git a/build/pkgs/khoca/spkg-configure.m4 b/build/pkgs/khoca/spkg-configure.m4
@@ -0,0 +1 @@
+SAGE_SPKG_CONFIGURE([khoca], [SAGE_PYTHON_PACKAGE_CHECK([khoca])])
diff --git a/build/pkgs/khoca/spkg-install.in b/build/pkgs/khoca/spkg-install.in
@@ -0,0 +1,2 @@
+cd src
+sdh_pip_install .
diff --git a/build/pkgs/khoca/type b/build/pkgs/khoca/type
@@ -0,0 +1 @@
+optional
diff --git a/build/pkgs/khoca/version_requirements.txt b/build/pkgs/khoca/version_requirements.txt
@@ -0,0 +1 @@
+khoca
diff --git a/src/sage/features/khoca.py b/src/sage/features/khoca.py
@@ -0,0 +1,31 @@
+r"""
+Check for Khoca
+"""
+from . import PythonModule
+
+
+class Khoca(PythonModule):
+    r"""
+    A :class:`sage.features.Feature` describing the presence of Khoca.
+
+    Khoca is provided by an optional package in the Sage distribution.
+
+    EXAMPLES::
+
+        sage: from sage.features.khoca import Khoca
+        sage: Khoca().is_present()                     # optional - khoca
+        FeatureTestResult('khoca', True)
+    """
+    def __init__(self):
+        r"""
+        TESTS::
+
+            sage: from sage.features.khoca import Khoca
+            sage: isinstance(Khoca(), Khoca)
+            True
+        """
+        PythonModule.__init__(self, 'khoca', spkg='khoca')
+
+
+def all_features():
+    return [Khoca()]
diff --git a/src/sage/interfaces/all.py b/src/sage/interfaces/all.py
@@ -23,6 +23,7 @@
 lazy_import('sage.interfaces.gnuplot', 'gnuplot')
 lazy_import('sage.interfaces.gp', ['gp', 'gp_version', 'Gp'])
 lazy_import('sage.interfaces.kash', ['kash', 'kash_version', 'Kash'])
+lazy_import('sage.interfaces.khoca', ['khoca', 'Khoca'])
 lazy_import('sage.interfaces.lie', ['lie', 'LiE'])
 lazy_import('sage.interfaces.lisp', ['lisp', 'Lisp'])
 lazy_import('sage.interfaces.macaulay2', ['macaulay2', 'Macaulay2'])
diff --git a/src/sage/interfaces/khoca.py b/src/sage/interfaces/khoca.py
@@ -0,0 +1,215 @@
+r"""
+Interface to Khoca
+
+Khoca is computer program writen by Lukas Lewark to calculate sl(N)-homology
+of knots and links. It calculates the following:
+
+* Khovanov sl(2)-homology of arbitrary links, given as a braid or in PD code.
+* Khovanov-Rozansky `sl(N)`-homology with `N > 2` of bipartite knots, given by a
+  certain encoding of a matched diagram of the knot.
+* Homology over the integers, the rationals or a prime field.
+* Either equivariant homology, or homology with an arbitrary fixed potential.
+* All pages of the spectral sequence of filtered homology over a field.
+* Reduced and unreduced homology.
+* Homology of sums and mirror images of knots.
+
+For more details please have a look at the `Khoca repository <https://github.com/LLewark/khoca>`__.
+If you are using khoca for a project or publication, please cite the web page or the literature
+given there. Furthermore, note that not all functionality listed above is available through
+this interface. Especially this is true for `sl(N)` homology for `N > 2` since we don't have
+a method to obtain a *matched diagram* for bipartite knots.
+
+The Khoca interface will only work if the optional Sage package Khoca is installed.
+
+AUTHORS:
+
+- Sebastian Oehms (2025):
+"""
+
+##############################################################################
+#       Copyright (C) 2025 Sebastian Oehms <seb.oehms@gmail.com>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#                  https://www.gnu.org/licenses/
+##############################################################################
+
+from sage.misc.cachefunc import cached_function
+from enum import Enum
+
+
+class KnownKeywords(Enum):
+    r"""
+    Enum class to specify if a keyword belongs to the interface.
+
+    EXAMPLES::
+
+        sage: from sage.interfaces.khoca import KnownKeywords
+        sage: [kwd for kwd in KnownKeywords]
+        [<KnownKeywords.frobenius_algebra: 'frobenius_algebra'>,
+        <KnownKeywords.root: 'root'>,
+        <KnownKeywords.equivariant: 'equivariant'>,
+        <KnownKeywords.reduced: 'reduced'>,
+        <KnownKeywords.code: 'code'>]
+    """
+    frobenius_algebra = 'frobenius_algebra'
+    root = 'root'
+    equivariant = 'equivariant'
+    reduced = 'reduced'
+    code = 'code'
+
+
+@cached_function
+def check_kwds(**kwds):
+    r"""
+    Return the keys of ``kwds`` as a list of elements of ``KnownKeywords``.
+    If ``kwds`` contains a key that is not in ``KnownKeywords`` a ``KeyError``
+    is raised.
+
+    EXAMPLES::
+
+        sage: from sage.interfaces.khoca import check_kwds
+        sage: check_kwds(frobenius_algebra=(0,0), root=0)
+        [<KnownKeywords.frobenius_algebra: 'frobenius_algebra'>,
+        <KnownKeywords.root: 'root'>]
+        sage: check_kwds(frobenius=(0,0), root=0)
+        Traceback (most recent call last):
+        ...
+        ValueError: 'frobenius' is not a valid KnownKeywords
+    """
+    keylist = []
+    for k in kwds:
+        keylist.append(KnownKeywords(k))
+    return keylist
+
+
+@cached_function
+def khoca_interface(ring, **kwds):
+    r"""
+    Return an instance of ``InteractiveCalculator` of the ``Khoca``.
+    This is a calculator for Khovanov homology written by Lukas
+    Lewark. For more information see :class:`~sage.features.khoca.Khoca`.
+
+    EXAMPLES::
+
+        sage: # optional khoca
+        sage: from sage.interfaces.khoca import khoca_interface
+        sage: khoca_interface(ZZ)
+        Khovanov homology calculator for Frobenius algebra: Z[X] / (1*X^2).
+        sage: khoca_interface(QQ)
+        Khovanov homology calculator for Frobenius algebra: Q[X] / (1*X^2).
+        sage: khoca_interface(GF(3))
+        Khovanov homology calculator for Frobenius algebra: F_3[X] / (1*X^2).
+        sage: khoca_interface(ZZ, frobenius_algebra=(1,-2), root=1)
+        Khovanov homology calculator for Frobenius algebra: Z[X] / (1*X^2 + -2*X + 1).
+        sage: khoca_interface(QQ, equivariant=3)
+        Traceback (most recent call last):
+        ...
+        NotImplementedError: keyword equivariant is not implemented yet
+    """
+    from sage.features.khoca import Khoca
+    Khoca().require()
+    keys = check_kwds(**kwds)
+    ch = ring.characteristic()
+    rg = ch
+    if rg == 0 and ring.is_field():
+        rg = 1
+    from khoca import InteractiveCalculator
+    frobenius_algebra = (0, 0)
+    if KnownKeywords.frobenius_algebra in keys:
+        frobenius_algebra = kwds[KnownKeywords.frobenius_algebra.value]
+    root = 0
+    if KnownKeywords.root in keys:
+        root = kwds[KnownKeywords.root.value]
+    equivariant = None
+    if KnownKeywords.equivariant in keys:
+        raise NotImplementedError('keyword %s is not implemented yet' % KnownKeywords.equivariant.value)
+    return InteractiveCalculator(coefficient_ring=rg,
+                                 frobenius_algebra=frobenius_algebra,
+                                 root=root,
+                                 equivariant=equivariant)
+
+
+@cached_function
+def khoca_raw_data(link, ring, red_typ=True, **kwds):
+    r"""
+    Return the raw data for the Khovanov homology from the ``Khoca``
+    calculator. This needs the optional feature ``khoca`` be present.
+
+    INPUT:
+
+    - ``link`` -- :class:`~sage.knots.link.Link`
+    - ``ring`` -- the coefficient ring
+    - ``kwds`` -- dictionary of options to be passes to ``Khoca``
+
+    OUTPUT:
+
+    A list of quadruples ``[degree, height, torsion, rank]`` each of which
+    represents a summand of a homology group for the given degree and height.
+
+    EXAMPLES::
+
+        sage: # optional - khoca
+        sage: from sage.interfaces.khoca import khoca_raw_data
+        sage: B2 = BraidGroup(2)
+        sage: b2 = B2((1,1))
+        sage: L2 = Link(b2)
+        sage: khoca_raw_data(L2, ZZ)
+        {(0, 0, 0): 1, (2, 0, 0): 1, (4, 2, 0): 1, (6, 2, 0): 1}
+        sage: khoca_raw_data(L2, ZZ, reduced=True)
+        {(1, 0, 0): 1, (5, 2, 0): 1}
+        sage: b3 = B2((1,1,1))
+        sage: K3 = Link(b3)
+        sage: khoca_raw_data(K3, ZZ, code='pd') == khoca_raw_data(K3, ZZ, code='braid')
+        True
+        sage: khoca_raw_data(L2, ZZ, equivariant=3)
+        Traceback (most recent call last):
+        ...
+        NotImplementedError: keyword equivariant is not implemented yet
+        sage: khoca_raw_data(K3, QQ, code='gauss')
+        Traceback (most recent call last):
+        ...
+        ValueError: unknown code gauss, must be one of (pd, braid)
+    """
+    def prepare_data(data):
+        r"""
+        compress and adapt data to Sage
+        """
+        data_as_dict = {}
+
+        for i in data:
+            # i[0]: degree, i[1]: height, i[2]: torsion i[3]: rank
+            d, h, t, r = i
+            # make d compatibil with Sage
+            d = int(t/2) - d
+            if (h, d, t) in data_as_dict:
+                data_as_dict[(h, d, t)] += r
+            else:
+                data_as_dict[(h, d, t)] = r
+        return data_as_dict
+
+    if not red_typ:
+        keys = check_kwds(**kwds)
+        arg = link.braid().Tietze()
+        if KnownKeywords.code in keys:
+            code = kwds[KnownKeywords.code.value]
+            if code == 'pd':
+                arg = link.pd_code()
+            elif code != 'braid':
+                raise ValueError('unknown code %s, must be one of (pd, braid)' % code)
+
+        KH = khoca_interface(ring, **kwds)
+        khres = KH(arg)
+        return {'red': prepare_data(khres[0]), 'unred': prepare_data(khres[1])}
+
+    raw_data = khoca_raw_data(link, ring, red_typ=False, **kwds)
+    if 'reduced' in kwds:
+        red = kwds['reduced']
+        if type(red) == bool:
+            if red:
+                return raw_data['red']
+            else:
+                raise TypeError('reduced must be a boolean')
+    return raw_data['unred']
diff --git a/src/sage/interfaces/meson.build b/src/sage/interfaces/meson.build
@@ -21,6 +21,7 @@ py.install_sources(
   'jmoldata.py',
   'kash.py',
   'kenzo.py',
+  'khoca.py',
   'latte.py',
   'lie.py',
   'lisp.py',
diff --git a/src/sage/knots/link.py b/src/sage/knots/link.py

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 + ipython cypari | $(PYTHON_TOOLCHAIN) sagelib $(PYTHON)
++
++
 +----------
 +All lines of this file are ignored except the first.
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+# See https://github.com/sagemath/sage/pull/40081`
	`2`	`+khoca`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+SAGE_SPKG_CONFIGURE([khoca], [SAGE_PYTHON_PACKAGE_CHECK([khoca])])`