Manual
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 39
.
AnalysisTools user manual
Karel ˇ
Sindelka
k.sindelka@gmail.com
March 21, 2019
Contents
Contents 2
1 Introdution 3
2 Installation 4
3 Format of input/output files 5
3.1 vsf structure file ............................. 5
3.2 vcf coordinate file ............................ 7
3.2.1 Ordered coordinate file ...................... 7
3.2.2 Indexed coordinate file ...................... 8
3.3 Aggregate file (agg)............................ 8
4 Utilities 10
4.1 AddToSystem ............................... 10
4.2 AngleMolecules .............................. 13
4.3 Aggregates and Aggregates-NotSameBeads ............... 14
4.4 Average .................................. 15
4.5 BondLength ................................ 17
4.6 Config ................................... 18
4.7 DensityAggregates ............................ 19
4.8 DensityBox ................................ 21
4.9 DensityMolecules ............................. 22
4.10 DihedralMolecules ............................. 23
4.11 DistrAgg .................................. 24
4.12 GenSystem ................................ 28
4.13 GyrationAggregates ............................ 29
4.14 GyrationMolecules ............................ 31
4.15 JoinAggregates .............................. 31
4.16 JoinRuns ................................. 32
4.17 lmp data .................................. 33
4.18 PairCorrel ................................. 33
4.19 PotentialAggregates ............................ 34
4.20 SelectedVcf ................................ 35
4.21 traject ................................... 36
4.22 TransformVsf ............................... 37
1
1. Introdution
This software package is a set of utilities aimed to analyse trajectories of coarse-
grained simulations. It was initially developed to work with DL MESO simulation
package. However, it works with vtf trajectory files, so it can be used to analyse
any vtf trajectories.
The emphasis is placed on assembly of molecules, e.i., self-assembly of polymers.
It therefore include utilities to determine if molecules are in aggregates and to calcu-
late various properties of aggregates. The utilities only calculate desired quantities
and write them to output text files, there is no plotting or visualisation.
Examples of the resulting data can be seen in the author’s thesis (ˇ
Sindelka,
Karel: The study of the association behavior of the amphiphilic copolymers in so-
lutions containing low molar compounds by means of computer simulations, disser-
tation thesis, Charles University, 2018) as well as in papers in impacted journals
(e.g., doi:10.1039/C8CP05907A,10.1134/S1811238217010052, or 10.1007/s00396-
017-4090-0).
3
2. Installation
All programs can be compiled using cmake which generates Makefile and subse-
quently running make. It requires Cand FORTRAN compilers. The compilation should
be done in a separate directory, such as build.
To create the Makefule and compile all utilities, simply run the following com-
mand (assuming build is a subdirectory of AnalysisTools root directory):
cmake -G "Unix Makefiles" ../
The binaries will be in ‘bin‘ subdirectory of ‘build‘.
Cmake variable -DCMAKE BUILD TYPE=Debug can be used to compile the version
of utilities for debugging.
To compile individual Cprograms using gcc, run (assuming you are in a subdi-
rectory of AnalysisTools root directory):
gcc -O3 -lm ../AnalysisTools.c ../Error.c ../Options.c ../Utility/pro-
gram.c.
4
3. Format of input/output files
All utilities read information about the system from vsf/vcf files (formatted as de-
scribed below) and FIELD file (input file for DL MESO simulation package). All
system information is read from the vsf structure file (Section 3.1) and from the
vcf coordinate file (Section 3.2). One vtf file containing a structure and coordinate
sections can also be used. The FIELD file is only used when bead charge and/or
mass is missing from the vsf structure file. The utilities consider only bead types
that are present in the vcf coordinate file (i.e., bead types present in the vsf file
but not in the vcf file are not seen by the utilities). A description of how the system
data are read is shown in Chapter 5.
Both vsf and vcf files can be generated using a traject utility provided by
the DL MESO simulation package (traject-v2 5 and traject-v2 6 provided here
are modified versions from earlier DL MESO simulation package versions). Both
structure and coordinates can be in one file (with vtf extension) – this file can be
used instead of separate vsf and vcf files.
All utilities assume cuboid simulation box with dimensions from 0 to N, where
Nis the side length of the box (which can be different in all three dimensions).
3.1 vsf structure file
The structure file contains all information about all beads and bonds except for their
Cartesian coordinates. The utilities are written for a vsf file created by a traject
utility (for DL MESO versions from 2.5 to 2.7), but other vsf files should work as
long as they adhere to the following format.
Avsf file is divided into two parts. The first part contains bead definitions.
Each line contains the description of a single bead and follows these rules:
•the line starts with atom (or just a)
•the second string is a bead index number that starts from 0 and increases with
every subsequent line (the last bead definition line therefore shows the total
number of beads in the simulation)
•the line contains bead name as name <char(8)>
•the first bead definition line may contain default instead of the index number;
every bead that is not explicitly written in the bead definition lines is has the
5
3. Format of input/output files 3.1. vsf structure file
default name
•if the bead is in a molecule, the line contains molecule name (resname <char(8)>)
and molecule id (resid <int>) that starts from 1
•mass and charge keywords are read if present (otherwise the mass and charge
of beads is read from FIELD)
•other keywords are ignored
The following is an example of bead definition lines containing all required data:
atom default name Bead_A
atom 0 name Bead_B
atom 3 name Bead_C resname Mol_A 1
atom 4 name Bead_C resname Mol_A 1
atom 6 name Bead_C resname Mol_A 2
atom 7 name Bead_C resname Mol_A 2
atom 8 name Bead_D resname Mol_B 3
atom 9 name Bead_D resname Mol_B 3
In this example, there are four bead types (named Bead A,Bead B, and Bead C,
and Bead D) and 10 beads in all (with indices from 0 to 9). Beads with indices
1, 2, and 5 are of the default type (Bead A). There are two molecule types named
Mol A and Mol B with molecule indices 1 to 3. All molecules with the same name
must have the same structure, i.e., the same number of beads and the same bond
connectivity.
The second part of a vsf file contains bonds definitions and must be preceded
by a blank line. Each bond definition line follows these rules:
•the line starts with bond (or just b)
•bond between two beads is specified by their indices separated by a colon
(there cannot be a space between the first number and the colon)
The following is an example of bead definition lines that complement the above-
shown bead definition lines:
bond 3: 4
# possible comment
bond 6: 7
bond 8: 9
In this example, there three bonds between beads with indices 3 and 4, 6 and 7,
8 and 9.
Blank lines and comments (lines beginning with #) are allowed in both parts of
the vsf file.
6
3. Format of input/output files 3.2. vcf coordinate file
3.2 vcf coordinate file
The coordinate file contains Cartesian coordinates of the beads and the size of
the cuboid simulation box. Coordinates are read from a vcf file containing either
ordered timesteps (Section 3.2.1) or indexed timesteps (Section 3.2.2).
An ordered vcf file must contain all beads defined in the vsf file, while an
indexed vcf file can contain only a subset of defined beads. Both indexed and
ordered vcf files contain a line before every timestep specifying the file type –
timestep ordered or timestep indexed (the keyword timestep can be omitted).
In both ordered and indexed vcf files, the size of the simulation box is given by
a line pbc <float> <float> <float> which is located before the first coordinate
block. Only timestep and pbc lines are read before the first coordinates (everything
else is ignored), so vtf file can be used instead of a vcf file.
The vcf file may contain comment lines (beginning with #) and blank lines
between timesteps, but the coordinate block must be continuous.
3.2.1 Ordered coordinate file
Coordinate lines in ordered vcf file contain only the Cartesian coordinates of the
beads in the form <float> <float> <float>. The beads are written in ascending
order of their indices as defined in the vsf file. The following is an example of an
ordered vcf file:
# any number of comments or blank lines
timestep ordered
pbc 10 10 10
0.0 0.0 0.0
0.5 0.5 0.5
...
# comments between timesteps
timestep ordered
# another comment
1.0 1.0 1.0
1.5 1.5 1.5
...
In this example, the simulation box is cubic with side length of 10. Beginnings
of two timesteps are represented by coordinates of the first two beads with indices
0 and 1 (as defined in the vsf file).
7
3. Format of input/output files 3.3. Aggregate file (agg)
3.2.2 Indexed coordinate file
Indexed coordinate files contains not only Cartesian coordinates, but also bead
indices (preceding the coordinates). Therefore an indexed timestep does not have
to contain all beads in the vsf structure file. Moreover, the beads do not have to
be ordered according to their ascending indices. The following is an example of an
ordered vcf file:
# any number of comments or blank lines
timestep indexed
pbc 10 10 10
2 0.5 0.5 0.5
21 0.0 0.0 0.0
...
# comments between timesteps
timestep indexed
# another comment
21 1.0 1.0 1.0
2 1.5 1.5 1.5
...
This example is similar to that for the ordored vcf file, but two beads have
indices 2 and 21 instead of 0 and 1.
3.3 Aggregate file (agg)
The aggregate file with agg extension is generated using Aggregates utility. The
file contains information about the number of aggregates in each timestep and which
molecules and monomeric beads belong to which aggregate. It serves as an additional
input file for utilities that calculate properties of whole aggregates – agg file is
therefore linked to the vcf that was used to generate it.
The agg file is a simple text file. The first line contains the command used to
generate it – parts of this command can be necessary for subsequent analysis of
aggregates. The second line is blank and from the third line the data for individual
timesteps are shown. Each timestep follows these rules:
•each timestep starts with Step: <int> (only Step keyword is read by the
utilities)
•the second line contains the number of aggregates in the given timestep and
followed by a blank line
8
3. Format of input/output files 3.3. Aggregate file (agg)
•there are two lines for each aggregate:
(1) number of molecules in the aggregate followed by their indices taken from
the vsf file
(2) number of monomeric beads in the aggregate followed by their indices
taken from the vsf file
•no blank or comment lines are allowed inside the aggregate block
•all molecules present in the vcf file used to generate this file must be present
in every timestep; here, aggregate can also refer to dissolved molecules
Following is an example of an agg file:
Aggregates in.vcf 1 1 out.agg A
Step: 1
2
2 : 1 3
3 : 10 100 1000
1 : 2
1 : 20
Step: 2
1
3 : 1 2 3
4 : 10 20 100 2000
Last Step: 2
In this example, command Aggregates in.vcf 1 1 out.agg A was used to
generate the file (see Section 4.3 for details about this utility). There are two
timesteps here – the first contains two aggregates (although one of them is a free,
dissolved molecule) and the second a single aggregate. As an example, the aggregate
in the second step contains three molecules with indices 1, 2, and 3 (taken from the
vsf file) and four monomeric beads (i.e., solvent or counterions) with indices 10, 20,
100, and 2000 (again, taken from the vsf file).
Besides using this file for further analysis using other utilities, the indices can be
used in vmd to visualize, e.g., only a specific aggregate.
9
4. Utilities
All utilities have command line help with short description when -h argument is
used. Besides -h, most of the utilities have several standard command line options
that are the same. The standard options can be used with any utility unless stated
otherwise.
Standard options
-i <name> use custom vsf file instead of traject.vsf
-v verbose output that provides information about all bead and
molecule types
-V detailed verbose output that provides information about all indi-
vidual molecules as well as about bead and molecule types
-s run silently, i.e., without any output at all (overrides -v and -V
options)
--script do not rewrite terminal line (useful if output is routed to a file)
-h print help and exit
4.1 AddToSystem
This utility takes an existing system specified by vcf coordinate and vsf structure
files and adds new beads into it. The new beads replace neutral unbonded ones with
the lowest indices (as ordered in the vsf file) from the original system. If molecules
are added, AddToSystem places them at the end (for the sake of DL MESO which
requires molecules to be after unbonded beads). The utility generates vcf and vsf
files for the new system.
AddToSystem does not check whether there are enough unbonded neutral beads
to be replaced by the new beads (if not, the utility will either crash or run forever).
The coordinates of the new unbonded beads are ruled by the -ld,-hd, and -bt
options, only the first bead of any molecule obeys the options. The coordinates of
the remaining beads in a molecule are governed by the provided coordinates. The
molecules are added with a random orientation.
If -ld and/or -hd options are used, they must accompanied by the -bt option.
The structure and number of added molecules and monomeric beads are read
from a FIELD-like file. This file must contain species section followed by molecule
10
4. Utilities 4.1. AddToSystem
section as described in the DL MESO simulation package.
The species section contains the number of bead types and their properties:
species <int>
<name> <mass> <charge> <number of unbonded beads>
The first line must start with species keyword followed by the number of bead
types. For each bead type, a single line must contain the name of the beads, their
mass and charge, and a number of these beads that are not in a molecule (i.e.,
unbonded or monomeric beads).
The molecule section that must be behind the species section contains infor-
mation about structure and numbers of molecules to be added:
molecule <int> number of types of molecules
<name> name of the first molecule type
nummols <int> number of these molecules
beads <int> number of beads in these molecules
<bead name> <float> <float> <float> a line for each of the <int> beads
... specifying bead name and
<bead name> <float> <float> <float> Cartesian coordinates
bonds <int> number of bonds in these molecule
<string> <int> <int> a line for each of the <int> bonds
... containing arbitrary string and
<string> <int> <int> indices connected beads
... anything beyond here is ignored
finish description of a molecule is finished
The molecule keyword specifies the number of molecule types, that is the
number of finish keywords that must be present. The <bead name> must be
present in the species section. The arbitrary <string> in the bonds is ignored by
AddToSystem (it is a relic from the DL MESO simulation package, where the <string>
specifies a type of bond). The indices in bond lines run from 1 to the number of
beads in the molecules and are ordered according to the beads line of the section.
Because molecule section in the FIELD file from DL MESO can also include bond
angles and dihedral angles, anything beyond the last bond line is ignored (until the
finish keyword is read).
If no molecules are to be added, the line molecule 0 must still be present in the
file.
The following is an example of the FIELD-like file:
species 3
A 1.0 1.0 0
11
4. Utilities 4.1. AddToSystem
B 1.0 0.0 0
CI 1.0 -1.0 30
molecule 2
Dimer
nummols 10
beads 2
A 0.0 0.0 0.0
A 0.5 0.5 0.5
bonds 1
harm 1 2
finish
surfact
nummols 10
beads 3
A 0.0 0.0 0.0
B 0.0 0.0 0.0
B 0.5 0.5 0.5
bonds 2
harm 1 2
harm 2 3
angles 1
harm 1 2 3
finish
In this example, 30 unbonded (or monomeric) negatively charged beads called CI
are added as well as 20 molecules – 10 molecules called Dimer and 10 molecules
called surfact.Dimer molecules contain two Abeads and one bond each; surfact
molecules contain three beads and two bonds each. The part starting with angles
and ending with finish is ignored. All in all, 80 beads are added – 30 CI, 30 A, and
20 Bbeads.
The utility creates the vcf and vsf files with the new system and can also write
the coordinates into a xyz file.
Usage:
AddToSystem <input.vcf> <input add> <out.vcf> <out.vsf> <options>
Mandatory arguments
<input> input coordinate file (either vcf or vtf format)
<input add> FIELD-like file specifying additions to the system
12
4. Utilities 4.2. AngleMolecules
<out.vcf> output vcf coordinate file for the new system
<out.vsf> output vsf structure file for the new system
Non-standard options
-st <int> timestep to add new beads to (default: 1)
-xyz <name> save coordinates to xyz file
-ld <float> lowest distance from beads specified by -bt option
-hd <float> highest distance from beads specified by -bt option
-bt <bead names> bead types to use in conjunction with -ld and/or -hd op-
tions
4.2 AngleMolecules
This utility calculates angles between beads in each molecule of specified molecule
type(s). The beads do not have to be connected, so the angle does not have to be
between two bonds.
The angle is specified by three bead indices taken from the vsf file (-n option)
These indices are from 1 to N, where Nis the number of beads in the molecule
type. Generally, the numbering of beads inside a molecule is made according to the
first molecule of the given type in vsf file. For example, assume that beads of the
first molecule called mol in the vsf file are ordered A(vsf index 123), B(vsf index
124), C(vsf index 200). Then, bead Ais 1, bead Bis 2, and Cis 3.
More than one angle can be specified (i.e., a multiple of three numbers have to
be supplied to the -n option.). For example, assuming indices 1 2 3 are specified
(default if -n option is not used), the angle will be between lines defined by beads
with indices 1 2 and 2 3. The angle is calculated in degrees and is between 0 and
180◦.
The utility calculates distribution of angles for each specified trio of bead indices
for each molecule type and prints overall averages at the end of <output> file. If
-a option is used, it can also write all the angles for all individual molecules in each
timestep (i.e., time evolution of the angle for each individual molecule).
Usage:
AngleMolecules <input> <mol name(s)> <options>
Mandatory arguments
<input> input coordinate file (either vcf or vtf format)
<mol name(s)> molecule name(s) to calculcate angles for
<output> output file for distribution
13
4. Utilities 4.3. Aggregates and Aggregates-NotSameBeads
Non-standard options
--joined specify that <input> contains joined coordinates (i.e., periodic
boundary conditions for molecules do not have to be removed)
-a <name> write all angles for all molecules in all timesteps to <name>
-n <ints> multiple of three indices for angle calculation (default: 1 2 3)
-st <int> starting timestep for calculation (default: 1)
Format of output files:
(1) <output> – distribution of angles
•first line: command used to generate the file
•second line: planes to calculate angles between (the dash-separated numbers
correspond to indices inside every molecule and are the same as the arguments
to the -n option) with the numbers in brackets corresponding to nth column
of data for each molecule type
•third line: numbering of columns (i.e., column headers)
–first is the centre of each bin in angles (governed by <width>); i.e., if <width>
is 5◦, then the centre of bin 0 to 5◦is 2.5, centre of bin 5 to 10◦is 7.5 and so
on
–the rest are for the calculated data: the range for each molecule type specifies
which column numbers correspond to the calculated angles for that particular
molecule type and the order of angles is given by the second line
•last two lines: arithmetic means for each calculated angle (last line) and headers
(second to last line) that again give range of columns in the last line for each
molecule type
(2) -a <name> – all angles for all molecules in all timesteps
•first and second lines are the same as for <output>
•third lines: column headers
–first is simulation timestep
–the rest are the calculated data: the range for each molecule type corresponds
to the number of molecules of the given type times the number of calculated
angles; for each molecule the angles are ordered according to the second line
4.3 Aggregates and Aggregates-NotSameBeads
These utilities determine which molecules belong to which aggregates according to
a simple criterion: two molecules belong to the same aggregate if they share at least
a specified number of contact pairs. A contact pair is a pair of two beads belonging
to different molecules which are closer than a specified distance.
The number of contact pairs, the distance, and bead type(s) to use for aggre-
gate determination are all arguments of the utilities. Any molecule type(s) can be
14
4. Utilities 4.4. Average
excluded from aggregate determination (and therefore from the output agg file).
While the Aggregates utility uses all possible pairs of given bead types, Aggrega-
tes-NotSameBeads does not use same-type pairs. For example, if bead types Aand
Bare given, Aggregates will use all three possible bead type pairs (i.e., A-A,A-B,
and B-B), but Aggregates-NotSameBeads will use only A-B bead type pairs.
Also, periodic boundary conditions can be removed from whole aggregates and
the new coordinates saved to an indexed vcf file (-j option). Therefore aggregates
will not be split by simulation box boundaries when, for example, visualizing the
molecules with vmd.
The information is written in agg format which is described in Section 3.3.
Usage:
Aggregates (or Aggregates-NotSameBeads)<input> <distance> <contacts>
<output.agg> <bead type name(s)> <options>
Mandatory arguments
<input> input coordinate file (either vcf or vtf format)
<distance> minimum distance for two beads to be in contact (thus
constituting a contact pair)
<contacts> minimum number of contact pairs between two molecules
to be in one aggregate
<output.agg> output agg file (must end in .agg) with aggregate informa-
tion
<bead type(s)> bead type name(s) to use for determining contact pairs (at
least two for Aggregates-NotSameBeads)
<options>
Non-standard options
-x <mol name(s)> exclude specified molecule type(s) from aggregate determi-
nation (and from the output agg file)
-j <output.vcf> output vcf file with coordinates of joined aggregates (i.e.,
without periodic boundary conditions)
4.4 Average
This utility uses the binning method to analyse data in a text file. It does not
use any of the standard options and prints the result only to standard output (e.i.,
screen).
15
4. Utilities 4.4. Average
Average calculates average, statistical error, and estimate of the autocorrelation
time τ. Empty lines and comments (lines beginning with #) are skipped. Average
prints to standard output (i.e., the screen) four numbers: <n blocks> <average>
<std error> <tau estimate>:
<n blocks> number of blocks used for the binning analysis
<average> simple arithmetic average
<std error> one-σstatistical error
<tau estimate> estimate of autocorrelation time τ
The average of an observable Ois a simple arithmetic mean:
hOi =1
N
N
X
i=1
Oi,(4.1)
where Nis the number of measurements and the subscript idenotes individual mea-
surements. If the measurements are independent (i.e., uncorrelated), the statistical
error is given by:
2=σ2
Oi
N,(4.2)
where σ2
Oiis the variance of the individual measurements,
σ2
Oi=1
N−1
N
X
i=1
(Oi− hOi)2.(4.3)
For correlated data, the autocorrelation time, τ, representing the number of
steps between two uncorrelated measurements must be determined. Every τ-th
measurement is uncorrelated, so the equation (4.2) can then be used to estimate the
error.
A commonly used method to estimate the autocorrelation time is the binning
(or block) method. In this method, the correlated data are divided into NBnon-
overlapping blocks of size k(N=kNB) with per-block averages, OB,n, defined as:
OB,n =1
k
kn
X
i=1+
(n−1)k
Oi.(4.4)
If kτ, the blocks are assumed to be uncorrelated and equation (4.2) can be used:
2=σ2
B
NB
=1
NB(NB−1)
NB
X
n=1
(OB,n − O)2.(4.5)
16
4. Utilities 4.5. BondLength
An estimate of the autocorrelation time can be obtained using the following formula:
τO=kσ2
B
2σ2
Oi
.(4.6)
A way to quickly estimate a ‘real’ value of τis to use a wide range of <n blocks>
value and plot the <tau estimate> values as a function of <n blocks>. Because the
number of data points in one block of the binning analysis should be significantly
larger than τ(e.g., ten times larger), plotting f(x) =(number of data lines in the
file)/(10x) will produce an exponential function that intersects the <tau estimate>
line. A value of <tau estimate> near the intersection (but to the left, where the
exponential is above <tau average>) can be used as a good estimate of τ.
Usage:
Average <input> <column> <discard> <n blocks>
Mandatory arguments
<input> input text file
<column> column number in <input> for data analysis
<discard> number of lines to discard from the beginning of <input>
<n blocks> number of blocks for binning analysis
4.5 BondLength
This utility calculates a distribution of bond lengths in specified molecule(s). For
each of the specified molecule type(s), BondLength calculates bond lengths between
all different types of connected bead pairs.
For example, assume two linear molecule types Mol 1 and Mol 2 both composed
of bead types Aand B.Mol 1 is connected like this: A-A-B;Mol 2 like this: A-B-B.
If both molecule types are used, BondLength calculates for each molecule type dis-
tribution of lengths for bonds A-A,A-B, and B-B (separate for each molecule even
though the molecules share the same bead types).
Furthermore, BondLength can also calculate distribution of distances between
specified beads in each of the specified molecules. The -d option takes as arguments
pairs of bead indices (according to the order of beads in the molecule in vsf –
similarly to the -n option in AngleMolecules, i.e., Section 4.2). More than one pair
can be specified. These indices are the same for all <mol name(s)>. If an index
higher than the number of beads in the molecule is provided, the utility takes the
last bead of the molecule (i.e., the highest index). For example, using -d file.txt
17
4. Utilities 4.6. Config
1 2 1 999 would write two distributions for each <mol name(s)> into <file.txt>:
distribution of distances between the first and second beads in each <mol name(s)>
and between the first and last (or 999th bead).
Usage:
BondLength <input> <width> <output> <mol name(s)> <options>
Mandatory arguments
<input> input coordinate file (either vcf or vtf format)
<width> width of each bin of the distribution
<output> output file with distribution of bond lengths
<mol name(s)> molecule name(s) to calculcate bond lengths for
Non-standard options
-st <int> starting timestep for calculation (default: 1)
-d <out> <ints> write distribution of distances between specified beads in
each specified molecule to <out>
Format of output files:
(1) <output> – distribution of bond length between all bead pairs
•first line: command used to generate the file
•second line: column headers
–first is the centre of each bin (governed by <width>); i.e., if <width> is 0.1,
then the centre of bin 0 to 0.1 is 0.05, centre of bin 0.1 to 0.2 is 0.15, etc.
–the rest are for the calculated data: for each molecule type, there is a list of
column numbers corresponding to all possible bead type pairs in the molecule;
if no beads of the given types are connected, the data column contains nan
(2) -d <output> <ints> – distribution of distances between specified beads
•first line: command used to generate the file
•second line: column headers
–first is again the centre of every bin
–the rest are for the calculated data: for each molecule type, there is a list
of column numbers corresponding to the given pairs of bead indices in the
molecule
4.6 Config
This utility creates DL MESO CONFIG file. It requires input coordinate file with all
beads; otherwise the utility will still run, but will produce incomplete CONFIG.
Usage:
18
4. Utilities 4.7. DensityAggregates
Config <input.vcf> <options>
Mandatory argument
<input> input coordinate file (either vcf or vtf format)
Non-standard option
-st <int> timestep for creating CONFIG file from (default: last step)
There is also utility Config from xyz which takes a xyz coordinate file and
creates the DL MESO CONFIG file. Because xyz file does not contain information
about the simulation box, the resulting CONFIG file must be modified manually –
Config from xyz prints x,y, and zinto the output file where box dimensions should
be.
Usage:
Config from xyz <input.xyz> <options>
Mandatory argument
<input> input xyz coordinate file
Non-standard option
-st <int> timestep for creating CONFIG file from (default: last step)
4.7 DensityAggregates
This utility calculates radial density profiles (RDP, or radial number densities) for
bead types in an aggregate with specified size (the number of molecules or aggrega-
tion number, AS) from its centre of mass.
RDPi(r) of bead type i, where ris distance from an aggregate’s centre of mass,
is the number of these beads in a spherical shell between the distances rand r+ dr
(in DensityAggregates, dris the <width> argument) divided by the volume of this
shell. The distance written in the output file is always r+ 0.5dr. Besides RDP,
the output file also contains radial number profiles (i.e., the number of beads in the
spherical shell not divided by the shell’s volume) and one-sigma errors for both RDP
and radial number profiles. The output file also contains a header describing what
is in each column.
Instead of ‘true’ aggregate size, a number of molecules of specific type(s) can be
used (-m option). For example, an aggregate containg 1 Mol A molecule and 2 Mol B
molecules (i.e., three molecules in all) can be specified in several ways:
19
4. Utilities 4.7. DensityAggregates
(1) with <agg size(s)> of 3;
(2) with <agg size(s)> of 3 and -m Mol A Mol B;
(3) with <agg size(s)> of 1 and -m Mol A; or
(4) with <agg size(s)> of 2 and -m Mol B.
Care must be taken when different molecule types share the same bead type. If
one bead type is in more molecule types, the resulting density for that bead type will
be the sum of its densities from all molecule types it appears in. The -x option can
overcome this – specific molecule types can be excluded from density calculations,
i.e., density of beads in the excluded molecule types will not be calculated. For
example, assume two molecule types – Mol 1 and Mol 2.Mol 1 contains bead types
Aand B;Mol 2 contains bead types Aand C. Depending on whether and how the -x
option is used, the utility will calculate:
(1) densities of A,B, and Cbeads (density of Abeads is a sum from both molecules),
if no -x is used;
(2) densities of only Aand Bbeads (with Abeads only from Mol 1), if -x Mol 2
is used;
(3) densities of only Aand Cbeads (with Abeads only from Mol 2), if -x Mol 1
is used; or
(4) no densities at all if -x Mol 1 Mol 2 is used.
Therefore, to be able to plot density of Abeads from Mol 1 and Mol 2 separately,
(2) and (3) should be used (i.e., DensityAggregates should be run twice).
Usage:
DensityAggregates <input> <output.agg> <width> <output.rho> <agg
size(s)> <options>
Mandatory arguments
<input> input coordinate file (either vcf or vtf format)
<input.agg> input agg file
<width> width of each bin of the distribution
<output.rho> output file(s) (one per aggregate size) with automatic #.rho
ending (#is aggregate size)
<agg size(s)> aggregate size(s) (the number of molecules in an aggregate
or the aggregation number, AS) to calculcate density for
Non-standard options
--joined specify that <input> contains joined coordinates (i.e., pe-
riodic boundary conditions for aggregates do not have to
be removed)
-n <int> number of bins to average to get smoother density (default:
1)
20
4. Utilities 4.8. DensityBox
-st <int> starting timestep for calculation (default: 1)
-m <mol name(s)> instead of ‘true’ aggregate size, use the number of specified
molecule type(s) in an aggregate
-x <mol name(s)> exclude specified molecule type(s) (i.e., do not calculate
density for beads in molecules <mol name(s)>)
Format of output files:
(1) <output.rho> – bead densities for one aggregate size
•first line: command used to generate the file
•second line: the order of data columns for each bead type – rdp is radial density
profile, rnp radial number profile and stderr are one-σerrors for rdp and rnp
•third line: column headers
–first is the centre of each bin (governed by <width>); i.e., if <width> is 0.1,
then the centre of bin 0 to 0.1 is 0.05, centre of bin 0.1 to 0.2 is 0.15, etc.
–the rest are for the calculated data: each number specifies the first column
with data for the given bead type (i.e., rdp column)
4.8 DensityBox
This utility calculates number density for all bead types in the specified direction
of the simulation box. The density is calculated from 0 to box length in the given
direction.
Usage:
DensityBox <input> <width> <output> <axis> <options>
Mandatory arguments
<input> input coordinate file (either vcf or vtf format)
<width> width of each bin of the distribution
<output> output file with automatic <axis>.rho ending
<axis> direction in which to calculate density: x,y, or z
Non-standard options
-n <int> number of bins to average to get smoother density (default: 1)
-st <int> starting timestep for calculation (default: 1)
Format of output files:
(1) <output> – bead densities
•first line: command used to generate the file
•second line: column headers
21
4. Utilities 4.9. DensityMolecules
–first is the centre of each bin (governed by <width>); i.e., if <width> is 0.1,
then the centre of bin 0 to 0.1 is 0.05, centre of bin 0.1 to 0.2 is 0.15, etc.
–the rest are for the calculated data: each number corresponds to the density
of the specified bead type
4.9 DensityMolecules
This utility works similarly to DensityAggregates, only instead for whole aggre-
gates, RDPs are calculated for individual molecules. Similarly to DensityAggregates,
the output file(s) also contain statistical errors and radial number profiles.
By default, the utility calculates RDPs from the molecule’s centre of mass,
but any bead in the molecule (with an index from vsf – similar to -n option in
AngleMolecules, Section 4.2) can be used instead (-c option).
Usage:
DensityMolecules <input> <width> <output> <mol name(s)> <options>
Mandatory arguments
<input> input coordinate file (either vcf or vtf format)
<width> width of each bin of the distribution
<output> output file(s) (one per molecule type) with automatic
<mol name>.rho ending
<mol name(s)> molecule name(s) to calculcate density for
Non-standard options
--joined specify that <input> contains joined coordinates (i.e., peri-
odic boundary conditions for molecules do not have to be
removed)
-n <int> number of bins to average for smoother density (default: 1)
-st <int> starting timestep for calculation (default: 1)
-c <name> <int> use specified bead in a molecule <name> instead of its centre
of mass
Format of output files:
(1) <output> – bead densities for one molecule
•first line: command used to generate the file
•second line: the order of data columns for each bead type – rdp is radial density
profile, rnp radial number profile and stderr are one-σerrors for rdp and rnp
•third line: column headers
–first is the centre of each bin (governed by <width>); i.e., if <width> is 0.1,
22
4. Utilities 4.10. DihedralMolecules
then the centre of bin 0 to 0.1 is 0.05, centre of bin 0.1 to 0.2 is 0.15, etc.
–the rest are for the calculated data: each number specifies the first column
with data for the given bead type (i.e., rdp column)
4.10 DihedralMolecules
This utility calculates angles between specified planes in each molecule of specified
molecule type(s). The planes in a molecule are arbitrary, so they can represent true
dihedral angles or improper dihedrals.
The angle is specified by six bead indices (according to the order of beads in
the molecule in vsf – similarly to the -n option in AngleMolecules, Section 4.2).
The first three indices specify one plane and the next three the other. For example,
assuming indices 1 2 3 4 5 6, the first plane is specified by the first three beads
in the molecule; second plane by the next three beads (beads 4 5 6). The default
indices (i.e., if -n option is not used) are 1 2 3 2 3 4. More than one angle can
be specified (i.e., a multiple of six numbers have to be supplied to the -n option.).
The utility calculates distribution of angles for each specified trio of bead indices
for each molecule type and prints overall averages at the end of <output> file. If
-a option is used, it can also write all the angles for all individual molecules in each
timestep (i.e., time evolution of the angle for each individual molecule).
Usage:
DihedralMolecules <input> <mol name(s)> <options>
Mandatory arguments
<input> input coordinate file (either vcf or vtf format)
<output> output file for distribution
<mol name(s)> molecule name(s) to calculcate angles for
Non-standard options
--joined specify that <input> contains joined coordinates (i.e., pe-
riodic boundary conditions for molecules do not have to be
removed)
-a <file> write all angles for all molecules in all timesteps to <file>
-n <ints> multiple of six indices for angle calculation (default: 1 2 3
2 3 4)
-st <int> starting timestep for calculation (default: 1)
Format of output files:
(1) <output> – distribution of angles
23
4. Utilities 4.11. DistrAgg
•first line: command used to generate the file
•second line: calculated angles (the dash-separated numbers correspond to in-
dices inside every molecule and are the same as the arguments to the -n option)
with the numbers in brackets corresponding to nth column of data for each
molecule type
•third line: numbering of columns (i.e., column headers)
–first is the centre of each bin in angles (governed by <width>); i.e., if <width>
is 5◦, then the centre of bin 0 to 5◦is 2.5, centre of bin 5 to 10◦is 7.5 and so
on
–the rest are for the calculated data: the range for each molecule type specifies
which column numbers correspond to the calculated angles for that particular
molecule type and the order of angles is given by the second line
•last two lines: arithmetic means for each calculated angle (last line) and headers
(second to last line) that again give range of columns in the last line for each
molecule type
(2) -a <file> – all angles for all molecules in all timesteps
•first and second lines are the same as for <output>
•third lines: column headers
–first is simulation timestep
–the rest are the calculated data: the range for each molecule type corresponds
to the number of molecules of the given type times the number of calculated
angles; for each molecule the angles are ordered according to the second line
4.11 DistrAgg
This utility calculates average aggregate mass and aggregation number for each
timestep (i.e., time evolution) and the averages over all timesteps. It calculates
number, weight, and z averages. It also calculates distribution functions of aggre-
gation sizes and volumes.
For a quantity O, the number, weight, and z averages, hOin,hOiw, and hOiz,
respectively, are defined as
hOin=PiOi
N,hOiw=PimiOi
Pimi
, and hOiz=Pim2
iOi
Pim2
i
,(4.7)
where Nis the total number of measurements, e.g., the total number of aggregates
if a utility calculates per-aggregate averages (or molecules if a utility calculates per-
molecule averages); miis mass of an aggregate i(or molecule i).
Per-timestep averages are written to the <output avg> and overall averages
are appended as comments (with commented legend) to both <output avg> and
<output distr> files.
24
4. Utilities 4.11. DistrAgg
Number, weight, and z distribution functions of aggregate sizes, Fn(AS), Fw(AS),
and Fz(AS) respectively, are defined as
Fn=NAS
PASNi
=NAS
N,
Fw=NASmAS
PASNimi
=NASmAS
PN
i=1 mi
=NASmAS
M, and
Fz=NASm2
AS
PASNim2
i
=NASm2
AS
PN
i=1 m2
i
,
(4.8)
where NASand mASstand for the number and mass, respectively, of aggregates
with aggregate size AS;Mis the total mass of all aggregates. The equations are
normalised so that PFx(AS) = 1.
Distribution of volume fractions of aggregates, φ(AS), is defined (assuming all
beads have the same volume) as
φ(AS) = NASmAS
PN
i=1 ni
=NASmAS
n,(4.9)
where niis the number of beads in aggregate iand nis the total number of beads in
all aggregates. If all beads have unit mass (as is often the case in dissipative particle
dynamics), the volume distribution, φ(AS), is the equal to the number distribution,
Fn(AS). These distribution are written into the <output distr> file.
Lastly, DistrAgg can calculate number distribution of composition for aggregates
with specified size(s) (-c option). This is a number distribution of the numbers of
different molecule types in the aggregate. For example, if the simulation box contains
molecule types Mol A and Mol B, aggregates with the same size can contain different
numbers of these molecules, or different ratios of the numbers of Mol A to Mol B
molecules, ξ=NMol A/NMol B. For now, DistriAgg can calculate this distribution
only for aggregates containing two molecule types. The composition distribution is
defined as
Fn(ξ) = Nξ,AS
NAS
,(4.10)
where Nξ,ASis the number of aggregate with aggregate size ASand ratio ξ;NASis
the total number of aggregates with aggregate size AS.
The definition of aggregate size is flexible. If none of -m,-x,--only options
is used, aggregate size is the ‘true’ aggregation number, AS, i.e., the number of all
molecules in the aggregate; if -m is used, aggregate size is the sum of only speci-
fied molecule type(s); if -x is used, aggregates containing only specified molecule
type(s) are disregarded; if --only is used, only aggregates composed of the speci-
fied molecule type(s) are taken into account. For example, consider a system in the
25
4. Utilities 4.11. DistrAgg
following table containing three aggregates composed of various numbers of three
different molecule types:
Molecule types Aggregate composition
Mol A Agg 1: 1 Mol A +2 Mol B +3 Mol C = 6 molecules
Mol B Agg 2: 1 Mol A +2 Mol B = 3 molecules
Mol C Agg 3: 1 Mol A = 1 molecule
Here is a list of several possibilities depending on the option(s) used:
(1) if none of -m,-x,--only is used, all three aggregates are counted and their
sizes are their aggregation numbers, i.e., AS= 6, 3, and 1
(2) if -m Mol A Mol B is used, all three aggregates are counted, but their size is
the sum of only Mol A and Mol B molecules: Agg 1 – 3; Agg 2 – 3; Agg 3 – 1
(3) if -m Mol B Mol C is used, Agg 3 is not counted, because its size would be
zero; DistrAgg would detect only two aggregates with sizes: Agg 1 – 5; Agg 2
– 2
(4) if -x Mol A Mol B is used, Agg 2 and Agg 3 are not counted, because neither
contains anything else than Mol A and/or Mol B;DistrAgg would detect only
one aggregate with size: Agg 1 – 6
(5) if -x Mol A Mol B is combined with -m Mol A Mol B,DistrAgg would again
detect only Agg 1, but its size would be taken as 3
(6) if --only Mol A Mol B is used, Agg 1 is not counted, because it contains a
molecule not specified by --only;DistrAgg would detect only two aggregates
with sizes: Agg 2– 3; Agg 3 – 1
(7) if --only Mol A Mol B is combined with -m Mol A, the two detected aggre-
gates have sizes: Agg 2 – 1; Agg 3 – 1
Usage:
DistrAgg <input.agg> <output distr> <output avg> <options>
Mandatory arguments
<input.agg> input agg file
<output distr> output file with distribution of aggregate sizes
<output avg> output file with per-timestep averages
Non-standard options
-st <int> starting timestep for calculation (default: 1)
-n <int> <int> use aggregate sizes in given range
-m <mol name(s)> use number of specified molecule type(s) as aggregate
size
26
4. Utilities 4.11. DistrAgg
-x <mol name(s)> exclude aggregates containing only specified molecule
type(s)
--only <mol name> use only aggregates composed of specified molecule
type
-c <output> <int(s)> save composition distribution for specified aggregate
size(s) to <output> file
Format of output files:
(1) <output distr> – distributions of aggregate sizes
•first line: command used to generate the file
•second line: column headers
–first is the aggregate size, As – either true aggregation number, or the size
specified by options
–F n(As) is number distribution of aggregate sizes – first equation in (4.8)
–F w(As) are weight distributions of aggregate sizes – second equation in (4.8);
whole agg mass denotes the distribution where mifrom (4.8) is the mass of
whole aggregate, regardless of the options used, i.e., even if some molecules
are not counted towards size, they are counted towards mass; the other dis-
tribution counts aggregate mass as only the mass of molecules that count
towards the size; if no size-altering options are used, the two columns are
identical
–F z(As) are z distribution functions of aggregate sizes – third equation in
(4.8); again, two distributions are calculated differing in aggregate mass
–<volume distribution> are distributions according to Equation (4.9); again,
the volume (i.e., the number of beads) is either the volume of whole aggregate
or the volume of only molecules contributing towards aggregate size
–next is the total number of aggregates with specified size
–the remaining columns show average numbers of all molecule types in an
aggregate with the specified size
•second to last line: column headers for overall averages written in the last line
–<M> n,<M> w, and <M> z are number, weight, and z averages, respectively, of
aggregate masses (the averages are defined in Equation (4.7))
–whole agg mass again denotes that mi(and O) in Equation (4.7) is the mass
of the whole aggregate, regardless of the options used
–a column denoted <mol name> n shows an average number of molecules named
mol name in an aggregate
(2) <output avg> – per-timestep averages
•first line: command used to generate the file
•second lines: column headers
–first is simulation timestep
–the rest are for the calculated data: number, weight, and z average aggregate
27
4. Utilities 4.12. GenSystem
mass (<M> n,<M> w, and <M> z, respectively) and aggregate size (<As> n,
<As> w, and <As> z, respectively)
–whole agg mass again denotes that mi(and O) in Equation (4.7) is the mass
of the whole aggregate, regardless of the options used
–whole agg As denotes that aggregate size (Oin Equation (4.7)) is the true
aggregation number
•the last two lines are the same as in <output distr>
(3) -c <name> – composition distribution
•first line: command used to generate the file
•second lines: column headers
–first is ratio of the two molecule types (i.e., 0 to 1)
–the rest are aggregate sizes
–in the data, only ratios that are non-zero for at least one aggregate size are
written; in case of more than one aggregate size specified by -a option, if the
ratio does not exist for some aggregate size(s), ‘?’ is displayed instead of zero
4.12 GenSystem
This simple utility uses modified FIELD file to create vsf structure file and to gen-
erate coordinates that could be used as a simulation’s starting point. The utility
assumes linear chains and uses equilibrium bond length to construct a prototype
molecule that is fully stretched in one direction for each molecule type. The utility
then creates layers of molecules that are separated by layers of unbonded beads (if
there are any). The utility should fill the whole box with given beads.
The input FIELD file must contain species and molecule sections, but the
interaction section is ignored (see DL MESO manual for details on the FIELD file).
The first line of FIELD that is ignored by DL MESO must start with box dimensions,
i.e., with three numbers (the rest of the file is ignored).
Usage (GenSystem does not use standard options):
Gensystem <out.vsf> <out.vcf> <options>
Mandatory arguments
<out.vsf> output vsf structure file
<out.vcf> output vcf coordinate file
Options
-f <name> FIELD-like file (default: FIELD)
-v verbose output that provides information about all bead and
molecule types
28
4. Utilities 4.13. GyrationAggregates
-h print help and exit
4.13 GyrationAggregates
This utility calculates the gyration tensor and its eigenvalues (or the roots of the
tensor’s characteristic polynomial) for all aggregates. Using the eigenvalues, the
utility calculates shape descriptors: radius of gyration, asphericity, acylindricity,
and relative shape anisotropy.
The eigenvalues, λ2
x,λ2
y, and λ2
z, (sorted so that λ2
x≤λ2
y≤λ2
z) are also written
to output file(s), because their square roots represent half-axes of an equivalent
ellipsoid.
The radius of gyration, RG, is defined as
R2
G=λ2
x+λ2
y+λ2
z.(4.11)
The asphericity, b, and the acylindricity, c, are defined, respectively, as
b=λ2
z−1
2(λ2
x+λ2
y) = 3
2λ2
z−R2
G
2and c=λ2
y−λ2
x.(4.12)
The relative shape anisotropy is defined in terms of the other descriptors as
κ2=b2+ 0.75c2
R4
G
(4.13)
Number average of all properties and, additionally, weight and z averages for
the radius of gyration are calculated (see Equation (4.7) in Section 4.11 for general
definitions of averages). Per-timestep averages (i.e., time evolution) are written to
the <output> file. To save averages for aggregate sizes, -ps option can be used.
The shape descriptors are by default calculated for all beads in the aggregates,
but -bt option can be used to specify which bead types to use.
Similarly to DistrAgg, the definition of aggregate size is flexible – see Section 4.11
for explanation of the -m and -x options.
Usage:
GyrationAggregates <input> <input.agg> <output> <options>
Mandatory arguments
<input> input coordinate file (either vcf or vtf format)
<input.agg> input agg file
29
4. Utilities 4.13. GyrationAggregates
<output> output file with per-timestep averages
Non-standard options
--joined specify that <input> contains joined coordinates (i.e., pe-
riodic boundary conditions for aggregates do not have to
be removed)
-bt <bead name(s)> bead type(s) used for calculation
-ps <name> output file with per-size averages
-m <mol name(s)> instead of ‘true’ aggregate size, use the number of speci-
fied molecule type(s) in an aggregate
-x <mol name(s)> exclude aggregates containing only specified molecule
type(s)
-n <int> <int> use only aggregate sizes in given range
-st <int> starting timestep for calculation (default: 1)
(1) <output> – per-timestep averages
•first line: command used to generate the file
•second line: column headers
–first is timestep
–rest are for calculated data: number, weight, and z averages (denoted by n,
w, and zrespectively) of radius of gyration and square of radius of gyra-
tion (Rg and Rg^2 respectively – Equation (4.11)); number averages of rela-
tive shape anisotropy (Anis – Equation (4.13)), acylindricity and asphericity
(Acyl and Aspher, respectively – Equation (4.12)), and all three eigenvalues
(eigen.x,eigen.y, and eigen.z –λ2
x,λ2
y, and λ2
z)
•second to last line: column headers for overall averages written in the last line
–<M> n and <M> w are number and weight, respectively, averages of aggregate
masses (the averages are defined in Equation (4.7)); aggregate mass here is
the mass of all beads of the chosen type(s) in the aggregate
–average numbers of molecules of each type in an aggregate are shown in
columns denoted <mol names>
–the remaining column represent overall averages of the per-timestep quantities
described above
(2) -ps <name> – per-size averages
•first line: command used to generate the file
•second line: column headers
–first is aggregate size, As
–last column is the total number of aggregates of the given size
–the rest are for the calculated data: simple averages of the numbers of
molecules of each type in the aggregate, of radius of gyration and its square,
of relative shape anisotropy, of acylindricity, of asphericity, and of all three
30
4. Utilities 4.15. JoinAggregates
eigenvalues (all denoted by the above-described symbols)
4.14 GyrationMolecules
This utility calculates shape descriptors similarly to GyrationAggregates (Sec-
tion 4.13), but for individual molecules instead for whole aggregates.
Usage:
GyrationMolecules <input> <output> <mol name(s)> <options>
Mandatory arguments
<input> input coordinate file (either vcf or vtf format)
<output> output file(s) (one per molecule type) with automatic
-<mol name>.txt ending
<mol name(s)> molecule name(s) to calculcate shape descriptors for
Non-standard options
--joined specify that <input> contains joined coordinates (i.e., pe-
riodic boundary conditions for molecules do not have to
be removed)
-bt <bead name(s)> bead type(s) to be used for calculation
-st <int> starting timestep for calculation (default: 1)
(1) <output> – per-timestep averages (one file per molecule type)
•first line: command used to generate the file
•second line: name of molecule type
•third line: column headers
–first is timestep
–rest are for calculated data: number, weight, and z averages (denoted by n,
w, and zrespectively) of radius of gyration (Rg – Equation (4.11)); number
averages of relative shape anisotropy (Anis – Equation (4.13)), acylindricity
and asphericity (Acyl and Aspher, respectively – Equation (4.12))
4.15 JoinAggregates
This utility is meant for cases when non-standard option -j is omitted from Aggrega-
tes (or Aggregates-NotSameBeads) command. JoinAggregates uses the provided
vcf and agg files to join aggregates, i.e., to remove periodic boundary conditions and
save the new coordinates into a vcf file. The utility reads Aggregates command
31
4. Utilities 4.16. JoinRuns
from the agg file to determine distance and number of contact pairs for aggregate
check (see Section 4.3 for details on Aggregates utility).
The output file is a vcf coordinate file.
Usage:
JoinAggregates <input> <input.agg> <output.vcf> <options>
Mandatory arguments
<input> input coordinate file (either vcf or vtf format)
<input.agg> input agg file
<output.vcf> output vcf coordinate file with indexed coordinates
Non-standard options
-st <int> starting timestep for calculation (default: 1)
4.16 JoinRuns
This utility probably does not work correctly.
This utility joins two independent simulation runs of the same system. That is,
the system contains identical beads and molecules, but these beads and molecules
are numbered differently in the vsf and vcf files from different simulations. The
two input vcf files must contain the same timestep type (i.e., both indexed or both
ordered) and the same number of beads (i.e., if one bead type is absent from one
vcf file, it must be absent from the second one as well).
The output is a vcf coordinate file with beads indexed according to the first vsf
structure file (i.e., traject.vsf or provided by -i option).
Usage:
JoinRuns <1st input> <2nd input> <2nd vsf> <output> <bead type(s)>
<options>
Mandatory arguments
<1st input> input coordinate file from the first simulation (either vcf or
vtf format)
<2nd input> input coordinate file from the second simulation (either vcf
or vtf format)
32
4. Utilities 4.18. PairCorrel
<2nd vsf> input structure file from the second simulation (structure file
from the first simulation is traject.vsf; changeable via -i
option)
<output> output vcf coordinate file with indexed coordinates
<bead type(s)> bead type names to save
Non-standard options
--join join molecules by removing periodic boundary conditions
-st1 <int> starting timestep first run (default: 1)
-st2 <int> starting timestep second run (default: 1)
-sk1 <int> number of steps skip per one used for first run (default: 0)
-sk2 <int> number of steps skip per one used for second run (default: 0)
4.17 lmp data
This utility generate data file for the lammps simulation package (see lammps man-
ual page for details on the data file format).
The utility reads information on system composition from DL MESO file (informa-
tion on all beads and structure of molecules – although it does not read dihedrals)
and coordinates from vcf coordinate file. The utility ignores the interactions part
from FIELD. The utility also ignore dihedrals.
Usage:
lmp data <input> <out.data> <options>
Mandatory arguments
<input> input vcf coordinate file
<out.data> output data file
Options
-f <name> FIELD file (default: FIELD)
-st <int> coordinate timestep for creating the data file
4.18 PairCorrel
This utility calculates pair correlation function (pcf) between specified bead types.
All bead type pairs are used – if Aand Bbead types, A-A,A-B, and B-B bead type
pairs are used. Right now, the pcfs are not correctly normalised.
33
4. Utilities 4.19. PotentialAggregates
The utility do not recognise between beads of the same type that are in different
molecules, so a pcf will be a sum of the beads from different molecule types.
Usage:
PairCorrel <input> <width> <output> <bead name(s)> <options>
Mandatory arguments
<input> input coordinate file (either vcf or vtf format)
<width> width of each bin of the pair correlation functions
<output> output file with pair correlation functions
<bead name(s)> bead type(s) used for calculation
Non-standard options
-n <int> number of bins to average to get smoother pair correlation
function (default: 1)
-st <int> starting timestep for calculation (default: 1)
Format of output files:
(1) <output> – pair correlation functions between all bead types
•first line: command used to generate the file
•second line: column headers
–first is the centre of each bin (governed by <width>); i.e., if <width> is 0.1,
then the centre of bin 0 to 0.1 is 0.05, centre of bin 0.1 to 0.2 is 0.15, etc.
–the rest are for the calculated data: each column correspond to one pair of
bead types
4.19 PotentialAggregates
This utility should be working, but it needs more testing.
This utility calculates electrostatic potential as a function of distance from the
centre of mass of specified aggregate size(s). It places a virtual particle with charge
q= 1 at several places on the surface of ever increasing sphere and calculates
electrostatic potential acting on that virtual particle.
At long range, the potential is calculated using Coulomb potential,
Ulong
ij =lBqiqj
rij
,(4.14)
where lBis the Bjerrum length, qiand qjare charges of particles iand j, and rij
is interparticle distance. At short range, the potential is for now calculated using
34
4. Utilities 4.20. SelectedVcf
potential between two charges with exponentially decreasing charge density,
Ushort
ij =Ulong
ij 1−(1 + βrij ) e−2βrij ,(4.15)
where β=5rc
8λ(rcis cut off distance and λis smearing constant). The utility takes
into account periodic images of the simulation box.
For now, parameters for the potential are hard coded in the source code: the
Bjerrum length is bjerrum=1.1 (aqueous solution), cut-off is r c=3, charge smear-
ing constant lambda=0.2, and number of periodic images of the simulation box is
images=5. The parameters can be changed but the utility must then be recompiled.
The aggregate size can be modified using -m options similarly to Density-
Aggregates (Section 4.7).
Usage:
PotentialAggregates <input> <input.agg> <width> <output> <agg size(s)>
<options>
Mandatory arguments
<input> input coordinate file (either vcf or vtf format)
<input.agg> input agg file
<width> width of each bin of the distribution
<output> output file(s) (one per aggregate size) with automatic
agg#.txt ending (#is aggregate size)
<agg size(s)> aggregate size(s) for calculation of electrostatic potential
Non-standard options
--joined specify that <input> contains joined coordinates (i.e., pe-
riodic boundary conditions for aggregates do not have to
be removed)
-st <int> starting timestep for calculation (default: 1)
-m <mol name(s)> instead of ‘true’ aggregate size, use the number of specified
molecule type(s) in an aggregate
4.20 SelectedVcf
This utility creates a new vcf coordinate file containing only beads of specified
types with output vcf file. The selected bead types are printed as comments at the
beginning of the output vcf file.
There is an option to remove periodic boundary conditions (i.e., to join molecules).
35
4. Utilities 4.21. traject
Conversely, the simualation box can be wrapped (i.e., the periodic boundary condi-
tions applied). If both --join and -w options are used, the simuation box is first
wrapped and then the molecules are joined.
Also, specified molecules can be excluded which is useful when the same bead
type is shared between more molecule types. However, as of now, no utilities can
read a vcf file that does not contain all beads of a given type, so this can be used
only for vmd visualization.
Lastly, xyz coordinate file can also be created from the selected bead type(s).
Usage:
SelectedVcf <input> <output> <bead type(s)> <options>
Mandatory arguments
<input> input coordinate file (either vcf or vtf format)
<output.vcf> output vcf coordinate file with indexed coordinates
<bead type(s)> bead type names to save (can be omitted if -r is used)
Non-standard options
-r reverse function, i.e., exclude <bead type(s)> instead of in-
cluding them; if no <bead type(s)> are specified, all bead
types are used (requires <input> with all bead types)
--join join molecules by removing periodic boundary conditions
-w wrap simulation box (i.e., apply periodic boundary condi-
tions)
-st <int> starting timestep for calculation (default: 1)
-sk <int> number of steps skip per one used (default: 0)
-n <int(s)> save only specified timesteps
-x <name(s)> exclude molecules of specified name(s) – do not use if
output.vcf is further analysed
-xyz <name> save coordinates to xyz file – does not take into account -x
option
4.21 traject
This utility is from the DL MESO simulation package and comes in three version
for 2.5, 2.6, and 2.7 versions of DL MESO. For the latest DL MESO version, the
utility is unmodified and therefore is not included here. The utilities traject-v2 5
and traject-v2 6 shipped with DL MESO 2.5 and 2.6 were modified to generate
36
4. Utilities 4.22. TransformVsf
separate vsf and vcf file (the traject for DL MESO 2.7 does this natively with
-sc command line option).
Usage of 2.5 and 2.6 versions (see DL MESO manual for the description of latest
version):
traject-v2 5 <int> or traject-v2 6 <int>
Mandatory argument
<int> number of computer cores used for the simulation run (equals the
number of HISTORY files)
4.22 TransformVsf
This not-very-useful utility just rewrites vsf file for better visualization with vmd.
The output vsf file contains not only bead name and index, but its charge and mass
as well.
Usage:
TransformVsf <output.vsf> <options>
Mandatory argument
<output.vsf> output structure file
37
5. Computational details
This chapter will contain some information about how things are coded in the util-
ities.
5.1 Read system data
ReadStructure() function reads all system information from vsf and vcf files.
FIELD file is used only to get mass and charge of beads if the information is not in
vsf file. Provided vsf file is used to get all information about beads and molecules
– names and numbers of bead and molecules, bonds in molecules. The first timestep
of the vcf file is used to determine numbers and ids of beads in that vcf file which
means that all timesteps must contain the same beads.
The procedure in ReadStructure() is as follows:
(1) Go through atom section of the vsf file to identify default bead type (if atom
default line is present), to find highest bead and molecule ids, and to find
bead type names (and charges and masses if present).
(2) Go again through the atom section to read names and ids of beads and
molecules as well as numbers of all beads and molecules for each type.
(3) Go through bond section of the vsf file to calculate number of bonds in each
molecule type.
(4) Go again through the bond section to read bonds for each molecule type.
(5) Go through the atom section (for the third time) to assign bead ids to molecules.
(6) Go through the first timestep of vcf file to find which beads are in that vcf
file (if no vcf file is provided – e.g., for DistrAgg utility – assume all beads
are used).
(7) Modify all arrays to accommodate only the beads that are present in the vcf
file.
(8) Read charge and mass from the FIELD file, if not already known from vsf file.
38
