Package: kymoknot-py
title: KymoKnot - A software package and webserver to identify and locate knots
bibliography: pandoc/ref.bibKymoKnot provides programs and libraries to localize the knotted portion of
knotted rings and linear chains.  A complete overview of this package and of the
webserver can be found in @kymoknot.  An interactive web-server interface is available athttp://kymoknot.sissa.it/interactive.php.
When using Kymoknot, please cite @kymoknot.Kymoknot adopts the Minimally-Interfering closure @minint to circularize both linear
chains and chain subportions.This package currently provides 3 programs.KymoKnot_ring.xKymoKnot_linear.xK_close.xThe first two programs locate knots, respectively on ring and linear chains,
using the simplification only as a mean to reduce the number of chain
subportions to be considered in the search for the knotted portion. The
topology of each chain subportion is evaluated by closing the corresponding
portion of the original, unsimplified chain.K_close.xtakes an open chain
in input and closes it using the Minimally-Interfering closure scheme.When searching for knotted portions, different search schemes identify
different entanglement properties of a chain and may in general give different
results.  For a detailed study, see ref @multiscale.  In the current version, the
bottom-up, top-down and  'unsafe' bottom-up search schemes can be used. The
bottom-up is enabled by default if no search scheme is specified by the user.Important.KymoKnot identifies knots based on the Alexander determinants in
$t=-1$ and $t=-2$ @minint.
Prime knots with 8 or more crossings can have the same
Alexander determinants of other knots, including composite one; therefore the
code must be used with caution when analyzing complex knots.
The table of known knots is in the header fileKNT_table.h.[1]: 1. Tubiana L., Orlandini E, Micheletti CProbing the Entanglement and Locating Knots in Ring Polymers: A Comparative Study of Different Arc Closure SchemesProgress of Theoretical Physics supplement, 192, 192-204 (2011)[2]: 2. Tubiana L., Orlandini E, Micheletti CMultiscale entanglement in ring polymers under spherical confinementPhys. Rev. Lett. 107, pg 188302 (2011).15-02-2018KymoKnot is a direct evolution ofLocKnotReferencesInstallationThis project makes use ofqhull.In case your package manager provides the library and it is installed, the build
system will use that version, otherwise it will compile also the local version of libqhull.
The library is needed by the Minimally-Interfering closure algorithm.Runmake docsto produce a README file in pdf. Requirespandoc.The project builds three targets:the C binariesthe python bindings module for C binariesthe python bindings binary, just for development purposescmake buildThe build system of kymoknot is cmake.
To build:$gitclone--recursivehttps://gitlab.physics.unitn.it/luca.tubiana/kymoknot-devel.git$cdkymoknot-devel/$mkdirbuild$cdbuild/$cmake..$make$sudomakeinstallThe cmake build offers the following parameters:BUILD_OWN_LIBS (default value OFF)the parameter forces cmake to build also the external dependencies, even if already present in the system.
Currently the only dependency is libqhull.It is possible to change cmake build parameters using the standard cmake syntax.$ cmake -DBUILD_OWN_LIBS=ON ..Python bindings package buildThis project provides some python bindings distributed as a python module calledkymoknot.Prerequisites:$pip3installbuildThen the build is launched with:$python3-mbuildThe build procedure will create the directorykymoknot-devel/distcontaining the .whl python package.$pip3installdist/kymoknot_py-*.whlThe python package that provides the module can be built to use the system qhull libraries or
to use the local version of the qhull library in a static fashion.
To switch between the dynamically linked build and the static one, users are required to define the QHULL_PREFIX environment
variable with the qhull installation path.
When the variable is defined, the kymoknot/build.py script will use that path instead of relying on pkg-build.$exportQHULL_PREFIX="/usr/local"$python3-mbuildIf your OS does not provide a libqhull package or the provided one is ignored by cmake (for example on Ubuntu 18.04 and Ubuntu 20.04),
you will have to compile libqhull before building the python module.
Seecmake buildsection.$gitclone--recursivehttps://gitlab.physics.unitn.it/luca.tubiana/kymoknot-devel.git$cdkymoknot-devel/$mkdirbuild$cdbuild/$cmake..$make$sudomakeinstall$cd..$exportQHULL_PREFIX="/usr/local"$python3-mbuild$pip3installdist/kymoknot_py-*.whlPython bindings binary build$python3kymoknot/build.pydevPlease note that when building the module binary this way, when callingimportkymoknotfrom a script, the python code is actually loaded fromkymoknot-devel/kymoknotdirectory and using the
binary produced by cffi compilation (i.e.:_kymoknot_bindings.cpython-310-x86_64-linux-gnu.so).
The first line ofkymoknot/__init__.pywill load the python module from the .so file:from_kymoknot_bindingsimportffi,libBuild and Installation on macOSPrerequisites:brew install cmake qhull pkg-configAfter having activated your preferred conda or virtual environment:$cdkymoknot-devel/$mkdirbuild$cdbuild/$cmake..$make$cd..$python3-mbuild$pip3installdist/kymoknot_py-0.9-*.whlBuilding python module on macOS using own qhull sources:$ cd kymoknot-devel/
$ mkdir build/ install/
$ cd build/
$ cmake -DBUILD_OWN_LIBS=ON -DCMAKE_INSTALL_PREFIX=$(pwd)/../install ..
$ make
$ make install
$ cd ..
$ export QHULL_PREFIX=$(pwd)/install/
$ python -m buildDocker buildsSome docker containers are provided to test build procedure in docker/ directory.
To build in a docker container:$cdkymoknot-devel$dockerbuild-tkymoknot_build_u1804$(pwd)/docker/ubuntu_18.04$dockerrun-it--rm-v$(pwd):/root/kymoknot-develkymoknot_build_u1804The build script will create the executables and the python module in build/ and
dist/ directories.
However, the build results are suited for the docker image, hence cannot be used in
the host system (unless it matches the one of the docker image).Usageusage:KymoKnot_ring.x [options] input_file(the same holds for KymoKnot_linear.x).The input file must use the format:N
        x y z
        x y z
        ...where N is the length of the coordinate sets.  If the input files contain
coordinate of rings, the edgesx_0 y_0 z_0andx_(N-1) y_(N-1) z_(N-1)must
coincide.A sequence of configurations can be passed one after the other in
the same input file.OUTPUTBU__[ -b option ]: shortest knotted portion. Bottom-up searchNBU__[ -u option ]: bottom-up search, without unknottedness check on complementar arcTD__[ -t option ]: shortest continuosly knotted portion. Top-down searchOUTPUT FILE FORMAT:ForKymoknot_linear.xandKymoknot_ring.x:index Adet_1 Adet_2 Knot_id start end lengthindex: index of the chain in the input sequence, starting from 0.Adet_1, Adet_1: Alexander determinantsKnot_id: Rolfsen knot id, seeKNT_table.hstart: knot starting beadend: knot ending beadlenght: length of the knotted portionNotes on the outputWhen several knotted portions are found they are printed on the same line.
Therefore,the number of columns in output is not fixedThe knot is identified on the whole chain, knotted portion will have the
topology of the whole chain.In rings, the start of the knot can come after its end, if the knot includes
the first bead on the chain.When performing a bracketed knot search with options-Fand-T, it is
possible that no knot is found in the given search window. In that case the
output line is left empty and a Warning is printed to screen.OPTIONS:-h:              print this help and exit.-s <max_stride>:         maximum stride for rectification. Default is 2% the chain length. Negative values in input set the stride to unlimited-m <mem_size>:   USE WITH CAUTION! Set the size of memory manually. Insert the expected length of the chain after simplification.-r <seed>:       set the pseudo random number generator's seed. Default: use time()+getpid().-b:      		Perform bottom-up search. ( DEFAULT )-t:      		Perform top-down search.  ( DEFAULT )-u:      		Perform bottom-up search without checking the complementar arc.-F <start>: ("From", use only in conjunction with -T) perform knot search between<start>and<end>, included.-T <end>: 	("To", use only in conjunction with -F) perform knot search between<start>and<end>, included.Options-Fand-Tcan be used also on rings, with<start>><end>in
which case kymoknot will look for knots passing through the first bead in the
chain.Usage examplesKymoknot_linear.x  linear_confs.datPerforms  a bottom-up search for knots,
with simplification stride set to 2% the length of each chain stored inlinear_confs.datKymoknot_ring.x -t ring_confs.datPerforms  a top-down search for knots,
with simplification stride set to 2% the length of each chain stored inlinear_confs.datKymoknot_ring.x -b -t -u ring_confs.datPerforms bottom-up, top-down and
"unsafe" searches.Kymoknot_ring.x -s 5 ring_confs.datPerforms a bottom-up search with maximum
stride set to 5 beads.Kymoknot_ring.x -F 100 -T 20 ring_confs.datPerforms a bottom-up search between
beads 100 and 20 of the rings, looking for knots passing through the origin.Python usageThe module can be used mainly in two ways:passing one or more numpy arrayspassing the path of a file containing the dataThe main purpose of the second way is to let the C code open and read the input data in a faster way
(at least rather than reading them from python).Here is an example of passing the input as numpy arrays:#!/bin/env/pythonimportkymoknotfromkymoknot.searchtypeimportSearchTypeimportnumpyasnpif__name__=="__main__":file_path="example_configurations/linear/start_A_3_1_N1024.knt"chains=[xforxinkymoknot.read_file(file_path)]kl=kymoknot.KymoKnotSearch(seed=0,closure_type=kymoknot.CL_QHULLHYB,close_subchain=kymoknot.CL_QHULLHYB,search_type=[SearchType.BU],)chain_res=kl.search(chains,kymoknot.INP_LINEAR)res=chain_res[SearchType.BU]#res[0] because res is a list containing an entry for each chain in input#and the example file contains 1 chainforkeinres[0]:print("{}".format(ke))To pass the input data as a file the sketch becomes:#!/usr/bin/env pythonimportkymoknotfromkymoknot.searchtypeimportSearchTypeimportnumpyasnpif__name__=="__main__":file_path="example_configurations/linear/start_A_3_1_N1024.knt"kl=kymoknot.KymoKnotSearch(seed=0,search_type=[SearchType.BU,SearchType.TD],)chain_res=kl.search(file_path,kymoknot.INP_LINEAR)res_bu=chain_res[SearchType.BU]res_td=chain_res[SearchType.TD]print("RES - bottom-up")foridx,chain_resinenumerate(res_bu):print(f"chain:{idx}")forkeinchain_res:print(ke)print("")print("RES - top-down")foridx,chain_resinenumerate(res_td):print(f"chain:{idx}")forkeinchain_res:print(ke)print("")Changelog31-07-2020ExpandedREADME.mdCorrected a bug which caused Kymoknot to fail if run on files containing a
sequence of rings with different lengths.15-02-2018KymoKnot is a direct evolution ofLocKnot