User Manual for version 1 - weria-pezeshkian/FreeDTS GitHub Wiki
FreeDTS - Version 1 Manual
Overview
Welcome to the documentation for FreeDTS Version 1.
This version was initially released in 2023. With the advent of Version 2 in 2024, we have introduced significant enhancements and new capabilities. This manual remains a comprehensive guide to the original version (v1) of FreeDTS, ensuring ongoing support and reference for users who continue to operate with Version 1.
Compiling The Source Code
To compile the FreeDTS source code just execute “compile.sh” script.
./compile.sh
This will create three binary files: DTS, CNV, and GEN. The DTS is for running simulations; GEN is for generating triangulated files (TS) and CNV is for converting different file formats.
Command line options
| Identifier | Type | Default value | Description |
|---|---|---|---|
| -in | string | Input.dts | input file name |
| -top | string | topology.top | Topology file name |
| -b | int | 1 | initial time step |
| -e | int | 100 | final time step |
| -seed | int | 36723 | Random number seed |
| -defout | string | output | A general string for label a specific run |
| -ndx | string | Index.inx | Index file name |
| -restart | string | NO | restart file name |
| -angle | double | -0.5 | minimum of cos of the angle between two faces |
| -minDist | double | 1 | Square of minimum distance between two vertices |
| -maxDist | double | 3 | Square of maximum link length |
Generating TS topology file for FreeDTS
Generate (GEN)
GEN bindery allows you to create triangulated surface files with different topologies in two different file formats, “q” or “tsi”. Three options exist, flat bilayer periodic in x and y directions, cylinder periodic in the x-direction and a closed sphere. To see all the options, execute $path/GEN -h
Some example:
To generate flat bilayers,
$path/GEN -box 50 50 30 -type flat -o topol.q
Generating closed membranes
$PATH/GEN -box 50 50 50 -type tetrahedron -N 20 -o topol.q
Note: You can force this structure to become sphere by using Ellipspoidalshell command and a short simulation.
CoupleToRigidWalls = on EllipsoidalShell 10000 10 10 10 0.01
Input file option and format
The input file must have a dts extension. Below, you can find the most common options defined in this file. However, this file could contain more information, including inclusions and their interactions. Other options are defined in their corresponding sections.
Integrator = MC
MC_Moves = 1 1 1
Initial_Step = 1
Final_Step = 1000000
Display_periodic = 1000
OutPutEnergy_periodic = 1000
Restart_periodic = 10000
Kappa = 15 0
Spont_C = 0
Seed = 37382
OutPutTRJ_TSI = 1000 10 TrjTSI
GeneralOutputFilename = output
Cell_Size = 2.5 2.6 2.5
Integrator: The algorithm for updating the configuration of the system. Currently only “MC” available. MC_Moves: An option for activating or disactivating the MC moves. First one is vertex move, second is the link flip and the last one is the inclusion moves. 1 1 1 means all the moves are active. Initial_Step: Initial step of the simulation, usually it should be one, unless something else is intended. Final_Step: The final step of the simulations Display_periodic: Frequency of coordinate file in vtu file format. OutPutEnergy_periodic: Frequency of energy file. Energy file contains several other information depending on global constrains applied on the system. Restart_periodic: Frequency of restart file recording. Kappa: Membrane bending and gaussian rigidity. Spont_C: spontaneous curvature of the membrane Seed: Random number seed. OutPutTRJ_TSI: Frequency for writing trajectory frames in tsi file, the precision of the coordinates and the name of the folder that the files will be stored in. GeneralOutputFilename: A general string to label all the generated files of a specific run with that string. Cell_Size: The size of the unit cells for domain decompositions, should be larger than 1 Box_Centering_F: To canter the system inside a box after every m steps. The m should be provided as an input. FreezingAGroup: Freezes a group of vertices. Requires an index file in which the name of the group should have been defined in the index file. OutPutTRJ_BTS: Simulation trajectory output in a binary file format (bts extension). Requires 3 variables. (1) Frequency of saving the coordinates; (2) Precision for file saving (3) the name of the file. Min_Max_LinkLenghtsSquare: Square of the maximum and minimum allowed edge size. Two double numbers. Default values are 1 and 3, corresponding to 1 and √3 in length. MinfaceAngle: The minimum allowed dihedral angle between two neighbouring triangles. This number will indicate the minimum value for the cosine of the angle between the two triangle normals.
Applying Constraints
Certain commands can be added to the input file for simulation with constraints such as fixed global curvature or/and fixed volume.
Fixed frame tension simulations
For doing this, one needs to add below line to the input file. The last two numbers are the frame tension in the unit of [kBT/a^2] and inverse frequency of applying the box size check algorithm to maintain the fixed membrane tension respectively. Note: this algorithm only makes sense for periodic membranes.
Frame_Tension = on Position_Rescale 0 5
Pressure difference or fixed volume simulation
;Volume_Constraint = on eqtime DP K gamma
Volume_Constraint = on 100 -0.1 0 0
This command will link the system energy to a potential as
$$E_V=-ΔPV+K/2 (v-γ)^2$$
Where $v=V/V_0$ and $V_0=\sqrt{\frac{A^3}{6\sqrt{\pi}}}$
Osmotic pressure
Based on the Jacobus van 't Hoff equation $\Pi=icRT$
$$\Delta E(\Delta V) = -P_0 \left( V_0 \ln \left[1 + \frac{\Delta V}{V_0} \right] - \Delta V \right) $$
Add below line to the input.dts file
Osmotic_Pressure = Type time gamma P0
Coupling to Fixed Global Curvature
To apply a constraint on the global curvature below command can be added to the input file.
;CouplingtoFixedGlobalCurvature = state kr m0
CouplingtoFixedGlobalCurvature = on 60 0.1
This will couple the system energy to a function as $$E_s=k_r/2A (M-m_0 A)^2$$
Harmonic potential between two groups of vertices
To apply a harmonic potential between two groups of vertices, one need to add below command to the input file.
; HarmonicPotentialBetweenTwoGroups = on K L0 eqstep Group1 Group2 nx ny nz
HarmonicPotentialBetweenTwoGroups = on 10 100 2000000 Group1 Group2 0 0 1
You also need to provide an index file for the group definition. This file should have “inx” extension. An example of index file is as below:
Group1 1
24
Group2 3
12 16 33
Applying Constant Surface Area
Constant total area based on the triangles area
;Apply_Constant_Area = state eq_time gamma Ka
Apply_Constant_Area = on eq_time gamma Ka
Eq_time is number of the steps in which the energy of this command reaches its final value
Gamma is a number between zero and 1 that fixes the reference area. 1 provides the maximum possible area and zero is the minimum.
$$E_A=K/N_T (A-A_0 )^2$$
where
$$A_0=N_T (1+2\gamma) \sqrt{\frac{3}{4}}$$
Membranes in confined spaces
FreeDTS also allows simulating membranes while they are in confined regions. If the initial membrane is not within the defined region, the surface is forced to enter this region by defining an equilibrium time. However, if the eq time is short, it may fail to do so. There are four types of confided space defined in FreeDTS: TwoFlatParallelWall, Cuboid, Ellipsoid and EllipsoidalShell. To apply one of these confinements, one of the below commands must be added to the input file.
CoupleToRigidWalls = on TwoFlatParallelWall 10000 X
Xis a double number which represent half the distance between the two sandwiching walls.
CoupleToRigidWalls = on Cuboid 10000 10 10 10
CoupleToRigidWalls = on Ellipsoid 10000 10 10 10
CoupleToRigidWalls = on EllipsoidalShell 10000 10 10 10 0.01
Inclusions (protein model)
To have inclusion in the simulations, we need to define different type of inclusions. Inclusion type must be defined at the end of the input file as
INCLUSION
Define 4 Inclusions
SRotation Type K KG KP KL C0 C0P C0L
3 Pro1 10 0 0 0 0 0 0
3 Pro2 20 0 0 0 0 1 0
3 Pro3 20 5 0 0 0 0 0
2 Pro4 20 5 0 0 0 0 0
The Inclusion-inclusion interactions should be always placed at the end of the file as Inclusion-Inclusion-Int
1 1 1 2 0.0 0.0
Type 1: n A B
$$e_{i,j}=-A_{i,j}+B_{i,j} (1+\cos[nΘ])$$ Note: the form of function type two has changed a bit in version 2 but the same behaviour can be set by adjusting the parameters.
Type 2: A B n $\Theta_0$ C $\gamma_0$
$$e_{i,j}=-A_{i,j}-B_{i,j} \cos[n(Θ-Θ_0)]-C_{i,j} (\gamma-γ_0 )^2$$
Defining inclusions type inside the input file does not means that they are present in the simulation. To create inclusion in the simulations, we need to define them either inside the “tsi” file or tell the input file to generate them. Currently we can only generate random distribution of inclusions from the input file. However, some can manually or use a script to add such inclusions to the tsi file.
GenerateInclusions
Selection_Type Random
TypeID 1 2 3
Density 0.0 0 0
Topology file format
Topology file provides information about the position of all the vertices and how they are linked. There are two types of file that you can provide as a topology file; top and tsi file format.
top file: This file has a “top” extension and contains a list of TS files in q (TS file) file format. An advantage of this topology format is that it allows us to feed multiple TS file into the system. A disadvantage is that it does not include inclusions.
tsi file: tsi topology is single file that is also single frames of OPENDTS trajectories. An advantage of this topology file is that it includes the inclusions information.
TS file Triangulated surface files that can be read by FreeDTS either has “q” format or “tsi” format. The Generate script can generate files in both formats (see Generate script section).
“tsi” format files The following shows a part of a .tsi file with all necessary keywords highlighted in bold. Every .tsi file starts with a line calling version 1.1. The next line defines the box size (x, y, and z) of the system in nm. The next three sections describe the TS mesh. Each section starts with a keyword (vertex, triangle and inclusion) and their corresponding number. Here, we have 130 vertices (the numbering starts from 0). Each vertex has an index and a position in x, y and z (in nm). The 130 vertices are connected via 256 triangles. Again, every triangle has an index (starting from 0) and is defined by the vertices the triangle connects, i.e. triangle 0 connects vertices 11, 55 and 43. Furthermore, a .tsi file can have a (protein) inclusion section. Here, there are three inclusions from two different types. Again, each inclusion has an index. The index is followed by the inclusion type (here: type 1 for inclusions 0 and 1, type 2 for inclusion 2) and the corresponding vertex index. The last two (floating point) numbers describe a unit two-dimensional vector (sum of both numbers must be one!) which defines the orientation of the inclusion with respect to the bilayer normal.
version 1.1
box 50.0000000000 50.0000000000 50.0000000000
vertex 130
0 21.1606233083 25.4394806652 25.5960855271
1 27.0284995400 23.2012757654 21.6715285158
2 26.9921761232 25.5136587223 28.0195776981
3 23.3273229896 26.2315165676 28.0075875808
4 26.2722773116 26.3271061222 28.1420707299
5 22.0396876425 23.6080597437 26.8858740866
.
.
.
125 21.5556280860 25.5595098219 26.5363425272
126 23.2182025326 26.8060871266 21.5195141902
127 25.3199303865 24.3519379911 20.6752314764
128 28.0093200458 22.6356946990 23.4685318698
129 21.4000741257 26.5841316766 25.2761757772
triangle 256
0 11 55 43
1 94 75 14
2 64 3 91
3 59 52 40
.
.
.
253 33 109 44
254 53 69 47
255 85 6 74
inclusion 3
0 1 22 0 1
1 1 5 0 1
2 2 30 0 1
“q” format files The previous tsi file in q format can be seen below. Line 1: Box information (3 double numbers). Line 2: Number of vertices (1 integer number; Let’s call it NV). Line 3 to NV+2: Vertex ID and coordinate (1 integer number and 3 double numbers). Line NV+3: Number of triangles (1 integer number; Let’s call it NT). Line NV+4 to NV+NT+3: Triangle ID and ID of its vertices (4 integer number).
50.0000000000 50.0000000000 50.0000000000
130
0 21.1606233083 25.4394806652 25.5960855271
1 27.0284995400 23.2012757654 21.6715285158
2 26.9921761232 25.5136587223 28.0195776981
3 23.3273229896 26.2315165676 28.0075875808
4 26.2722773116 26.3271061222 28.1420707299
5 22.0396876425 23.6080597437 26.8858740866
.
.
.
125 21.5556280860 25.5595098219 26.5363425272
126 23.2182025326 26.8060871266 21.5195141902
127 25.3199303865 24.3519379911 20.6752314764
128 28.0093200458 22.6356946990 23.4685318698
129 21.4000741257 26.5841316766 25.2761757772
256
0 11 55 43
1 94 75 14
2 64 3 91
3 59 52 40
.
.
.
253 33 109 44
254 53 69 47
Generate Script
Generate (GEN) bindery allows you to create triangulated surface files with different topologies in two different file formats, q or tsi. Three options exist, flat bilayer periodic in x and y directions, cylinder periodic in the x-direction and a closed sphere. To see all the options, execute $path/GEN -h
Some example:
To generate flat bilayers
$path/GEN -box 50 50 30 -type flat -o topol.q
Generating closed membranes
$PATH/GEN -box 50 50 50 -type tetrahedron -N 20 -o topol.q
Note: You can force this structure to become sphere by using Ellipspoidalshell command and a short simulation.
CoupleToRigidWalls = on EllipsoidalShell 10000 10 10 10 0.01
Convert Script
The convert (CNV) bindery allows for converting tsi and q files to each other and several other different file format such as vtu and gro. To see all the options, execute $path/GEN -h