© Copyright 2021 Tom Herschberg, Kyle Pifer and Eleni Panagiotou
If you use this code you must reference the following paper:
Herschberg, T., Pifer, K. and Panagiotou, E., 2022, A computational package for measuring Topological Entanglement in Polymers, Proteins and Periodic systems (TEPPP), Comp. Phys. Commun. 286 108639
visit www.elenipanagiotou.com for updated information
What is TEPPP?
Getting Started
Building
Usage
Examples
Gauss linking integral
Periodic Writhe
Jones Polynomial
Scan Jones Polynomial
License
Contributors
TEPPP is a software package designed to aid in the calculation of several topological entanglement values in molecular systems. It is designed to work both in serial and in parallel when coupled with a functioning MPI installation.
TEPPP requires a compiler which fully supports C++17 (GCC 10 and up). If parallel execution is desired, a functioning MPI installation must be present in the PATH variable.
To build only the serial version of the software, run the following command:
make serial
To build only the parallel version of the software, run the following command:
make mpi
To make both versions of the software, type the following command:
make all
The current version of TEPPP only supports running individual commands through the command line to obtain the desired results. If the coordinates of the system to be analyzed are in a file with an extension other than .teppp, they must be converted into a file readable by TEPPP. To do this, run the following command in the top-level installation directory:
./convertor "/path/to/filename.ext" CHAIN_LENGTH NUM_CHAINS BOX_DIM
where CHAIN_LENGTH is the number of atoms in each chain, NUM_CHAINS is the number of chains in the system, and BOX_DIM is the length of one side of the periodic box if the system uses periodic boundary conditions. If the system does not use periodic boundary conditions, enter 0 for BOX_DIM.
? Note that only .teppp files are supported. All other data files must be converted to .teppp either by the user or by using the convertor utility. Only .read_data files (with all coordinates in unwrapped form) are supported by the convertor utility at this time. Once the convertor command has been run, the file with the converted data will be located in the
TEPPP/converteddirectory for further use.
Once a .teppp file with the desired coordinates has been generated, any of the software commands can be used in conjunction with the file to generate results. The base commands that are currently available are:
jones | Calculates the Jones polynomial of each chain in the system
lk | Calculates the linking number between each pair of chains in the systemLinking Numbers
wr | Calculates the Writhe of each chain in the system
All base commands are called using the same syntax:
The filename (including path) of the data file containing the coordinates of the system to analyze followed by CHAIN_LENGTH NUM_CHAINS ARCHITECTURE (NUM_PROJECTIONS) BOX_DIM, where CHAIN_LENGTH: the length of the chains in the system (assuming they all have the same length) NUM_CHAINS: the number of chains in the system ARCHITECTURE: currently supporting ring or linear, denoted by 0, 1, respectively. NUM_PROJECTIONS: applies only to jones-it is the number of projections to use for the computation of the Jones polynomial. If working with ring chains, use 1. BOX_DIM: periodic box dimensions, assuming cubic box
In addition to these base commands, there are several types of variant commands also included in TEPPP. periodic commands analyze the topological entanglement of a given system while accounting for periodic boundary conditions. The periodic commands that are currently available are:
periodic_wr | Calculates the periodic Writhe of each chain in the system
periodic_lk | Calculates the periodic linking number between each pair of chains in the system
The syntax for calling periodic commands is the same as the syntax for calling base commands.
scan commands are used to analyze the topological entanglement of certain parts of chains rather than the entire chain. For example, if a user wants to the part of a single chain that contributes the most to the overall Writhe of that chain, they would use a scan command. The scan commands that are currently available are:
jones_scan | Calculates the Jones polynomial along each chain at given scanning lengths
lk_scan | Calculates the linking number along each pair of chains at given scanning lengths
wr_scan | Calculates the Writhe along each chain at given scanning lengths
Calling scan commands requires 4 parameters, which must be provided in the command line in the order shown below:
The filename (including path) of the data file containing the coordinates of the system to analyze, followed by CHAIN_LENGTH NUM_CHAINS ARCHITECTURE (NUM_PROJECTIONS)
The length of the initial interval at which to scan.
The length of the final interval at which to scan.
The amount to increase the interval after a scan completes.
BOX_DIM (optional)
mpi commands are parallel versions of the base, periodic, and scan commands discussed above. They leverage MPI to split the workload between a given number of processors rather than performing the work serially. The mpi commands that are currently available are:
jones_mpi | Calculates the Jones polynomial of each chain in the system in parallel
lk_mpi | Calculates the linking number between each pair of chains in the system in parallel
wr_mpi | Calculates the Writhe of each chain in the system in parallel
periodic_wr_mpi | Calculates the periodic Writhe of each chain in the system in parallel
periodic_lk_mpi | Calculates the periodic linking number between each pair of chains in the system in parallel
jones_scan_mpi | Calculates the Jones polynomial along each chain at given intervals in parallel
lk_scan_mpi | Calculates the linking number along each pair of chains at given intervals in parallel
wr_scan_mpi | Calculates the Writhe along each chain at given intervals in parallel
mpi commands have the same syntax as their base, periodic, and scan counterparts but must be called using mpirun rather than running the command itself.
To calculate the Gauss linking integral between each pair of chains in a system found in "../data/systemA.teppp" with 100 linear chains each of length 20 in a cubic periodic box of length 13.35315:
./lk "../data/systemA.teppp" 20 100 1 13.35315
using MPI to split the work between 4 different processes:
mpirun -np 4 ./lk_mpi "../data/systemA.teppp" 20 100 1 13.35315
To calculate the Periodic Writhe of each chain in a system found in "../data/systemA.teppp" with 100 chains each of length 20 in a cubic periodic box of length 13.35315:
./periodic_wr "../data/systemA.teppp" 20 100 1 13.35315
To compute the Jones polynomial of each chain in a system found in "../data/systemA.teppp" with 100 chains each of length 20 in a cubic periodic box of length 13.35315:
./jones "../data/systemA.teppp" 20 100 1 100 13.35315
To scan along each chain and calculate the Jones polynomial of each subchain in a system found in "../data/systemA.teppp" with 100 chains each of length 20 starting with scanning length 5 up to scanning length 10 with a step of 5:
./jones_scan "../data/systemC.teppp" 20 100 1 100 5 10 5
Copyright (c) 2021, Tom Herschberg, Kyle Pifer and Eleni Panagiotou
All rights reserved.
