A program for finding strings of hydrogen bonded atoms in a trajectory file generated from the Discover and LAMMPS molecular dynamics program.

• Installation
• Usage
• Input
  • Discover
  • LAMMPS
• Output
  • Hydrogen bond strings
    • Generating Images
  • Neighbor distance in chains
  • Hydrogen bond lengths
  • Hydrogen bond angles
  • Hydrogen bond list
  • Hydrogen bond lifetime correlations

To compile the program

mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=release ..
make
src/TraceHBonds

To generate the documentation as html, which will be available at docs/html/index.html, use

make docs

To cross-compile, use your toolchain cmake file as:

cmake -DCMAKE_BUILD_TYPE=release -DCMAKE_TOOLCHAIN_FILE=<Toolchain cmake file> ..

A typical command line would look like this when using CAR/MDF files:

TraceHBonds --input molecule.arc -p HBonds -s .dat -H h1o -A o2h -r 2.5 -a 90.0 --verbose --all

or this when using LAMMPS trajectory files:

TraceHBonds --input molecule.data --trajectory molecule.lammpstrj --molecule molecule.dat -p HBonds -s .dat -H h1o -A o2h -r 2.5 -a 90.0 --verbose --all

Below is a table of all options available from the command line. The long form options are preceded with --, and short form a single -. For options with both a long and short form, either one may be used on the command line.

The standard CAR/MDF and LAMMPS trajectory files are recognized. If compiled with support for LZMA, GZIP, and/or BZIP2, compressed files may be read and written.

The standard CAR/MDF files are read.

The --input option, when loading a LAMMPS file, defines the name of the data file. The masses section of the data file must have a comment, it will be used as the forefield type used for atom selection with the --hydrogen and --acceptor flags.

And example masses section of a LAMMPS data file:

Masses

   1  15.999400 # o
   2  12.011150 # c2
   3  12.011150 # c
   4   1.007970 # h
   5  12.011150 # cPrime
   6  12.011150 # c3
   7  15.999400 # oPrime
   8  15.999400 # oh
   9   1.007970 # ho

The --trajectory option defines the name of a LAMMPS trajectory file. The trajectory file must be saved by a dump custom or custom/gz command with atom attributes starting with 'id mol x y z', any other atom attribute may follow.

The --molecule option is used when loading LAMMPS trajectory and data files, and loads a file that defines which atoms belong to which molecule. While the LAMMPS data file has a column, Molecule-Id for defining molecules, the msi2lmp script uses residue IDs there. This file is required when using LAMMPS files, whether msi2lmp is used or not.

The example file below defines 4 molecules and their associated atoms. The atoms must be in sequence for each molecule.

# Molecule FirstAtom LastAtom
     1      1    248
     2    249    496
     3    497    744
     4    745    992

Depending upon the command line options, many data files may be generated. The description of all calculations are listed below

• Hydrogen bond strings (--sizehist)
  • List of Files Created
• Neighbor distance in chains (--neighborhist)
  • List of Files Created
• Hydrogen bond lengths (--length)
  • List of Files Created
• Hydrogen bond angles (--angles)
  • List of Files Created
• Hydrogen bond list (--list)
  • List of Files Created
• Hydrogen bond lifetime correlations (--lifetime)
  • List of Files Created

The --sizehist option calculates hydrogen bonds, traces the hydrogen bonds into connected strings, and tabulates the sizes.

• <prefix>#<suffix>

Where # indicates the frame of the trajectory. For a trajectory containing 100 frames, 100 files will be generated.

The files generated from the --sizehist option consist of two parts: the individual chains and their atoms, and histograms of chain sizes.

As an example, a few lines from a data file follows, showing 3 chains. The output will look a little different if either the --povray, or --json options are used.

# Current Element : 589
# Atoms in Chain : 3
# Molecules : 2
# Unique forcefields : 3
# Times chain switched between Molecules (switching) : 1
# Periodic boundary conditions applied.
  21.6276   27.0261   44.9056 [O]  Molecule  O87  o2h
  21.3585   27.9405   44.8265 [H]  Molecule  H592  h1o
  20.1321   29.5776   43.8281 [O]  Molecule2  O1493  o1=
# Chain end-to-end distance: 3.147660


# Current Element : 590
# Atoms in Chain : 9
# Molecules : 2
# Unique forcefields : 3
# Times chain switched between Molecules (switching) : 1
# Periodic boundary conditions applied.
  24.6835   23.4992   41.1162 [O]  Molecule  O95  o2h
  24.2312   22.9546   41.6786 [H]  Molecule  H601  h1o
  23.0622   23.9573   43.4825 [O]  Molecule  O88  o2h
  22.4585   23.9183   44.2600 [H]  Molecule  H593  h1o
  21.5617   24.1262   45.5633 [O]  Molecule9  O8207  o2h
  21.6362   24.7840   46.3132 [H]  Molecule9  H8711  h1o
  22.6499   25.4540   47.5703 [O]  Molecule9  O8208  o2h
  23.5335   25.7281   47.6493 [H]  Molecule9  H8712  h1o
  25.0893   24.1132   46.6706 [O]  Molecule9  O8209  o1=
# Chain end-to-end distance: 5.602967


# Current Element : 591
# Atoms in Chain : 5
# Molecules : 2
# Unique forcefields : 2
# Times chain switched between Molecules (switching) : 1
# Periodic boundary conditions applied.
  28.8885   22.9984   40.5006 [O]  Molecule  O96  o2h
  29.6141   22.3548   40.3725 [H]  Molecule  H602  h1o
  30.7792   21.1779   38.8075 [O]  Molecule6  O5419  o2h
  31.6526   21.1038   39.2359 [H]  Molecule6  H5925  h1o
  33.3777   21.2051   38.4486 [O]  Molecule6  O5420  o2h
# Chain end-to-end distance: 5.251614

This histogram shows how many chains of a specific length there are in this frame. It also shows how many chains form closed loops (begin and end at the same hydrogen bond). This particular data had no closed loops.

# Atoms/HBonds |Count| (For all Chains, including Closed Loops)
#    3 /   1   |  175|**************************************************************
#    5 /   2   |   72|**************************
#    7 /   3   |   19|*******
#    9 /   4   |   16|******
#   11 /   5   |    7|**
#   13 /   6   |    1|
#   15 /   7   |    1|
#   17 /   8   |    1|
#
# Atoms/HBonds |Count| (For Closed Loops)
#

The next series of histograms show how many times a hydrogen bond chain switches to another molecule, for each chain length. Switching of 0 means the chain was on a single molecule. Switching of 1 means it started on a molecule and ended on another. The switching number does not indicate how many molecules a chain is composed of, since it may switch back and forth between two molecules multiple times.

# Switching |Count| (For Chain length of 3)
#    0      |  107|**************************************************************
#    1      |   68|***************************************
#
# Switching |Count| (For Chain length of 5)
#    0      |   18|************************
#    1      |   46|**************************************************************
#    2      |    8|***********
#
# Switching |Count| (For Chain length of 7)
#    0      |    8|**************************************************************
#    1      |    6|***********************************************
#    2      |    5|***************************************

The following histograms shows how many molecules a chain is composed of, for each chain length.

# Molecules |Count| (For Chain length of 3)
#    1      |  107|**************************************************************
#    2      |   68|***************************************
#
# Molecules |Count| (For Chain length of 5)
#    1      |   18|**********************
#    2      |   50|**************************************************************
#    3      |    4|*****
#
# Molecules |Count| (For Chain length of 7)
#    1      |    8|**************************************************************
#    2      |    8|**************************************************************
#    3      |    3|***********************

The program Blender can be used to convert the output of --sizehist --json to an image or even a movie of the image rotating. Here is an example image using the hbchain.py script in the blender directory (I need to add a legend):

The image was created by Blender using

blender -P blender/hbchain.py -- -f output/HBonds1.json

where output/HBonds1.json is the output of TraceHBonds with the appropriate options.

For help with the Blender script, try

blender -P hbchain.py -- --help

The program POV-Ray can be used to convert the output of --sizehist --povray to an image or even a movie of the image rotating. Here is an example image using the prettybox.pov script in the povray directory:

The legend text was added with GIMP.

The --neighborhist option calculates the distance between non-hydrogen atoms in the hydrogen bond chains. For a chain consisting of only oxygen and hydrogen atoms, this would calculate the neighbor distances between oxygen atoms in the chain.

• <prefix>-NN-AllFrames<suffix>
• <prefix>-NN-Combined<suffix>
• <prefix>-NN-only<suffix>

All files contain tab delimited text.

The data start with statistics of each individual frame in a trajectory NN-AllFrames, then all frames together NN-Combined, followed by combining all chain lengths together for a list of only neighbor distances NN-only.

The table in this file consists of a Count, Average, and StdDev column for each frame of the trajectory, so the table can have many columns if a trajectory with many frames is used. It's not uncommon to read 100, 1000, or more frames. Sample output is shown below, in table format for easy viewing. Note: Only the first 2 off 1000 frames of a large trajectory file are shown, and the first 13 of 27 atoms in chain for this particular sample trajectory file.

n.n. = Nearest neighbor, and f is the frame number.

The table in this file combines data from all the frames into single Count, Average, and StdDev columns. Sample data is shown below, in table format for easy viewing. Note: Only the first 13 of 27 atoms in a chain are shown for this particular sample trajectory file.

This file combines all frames as in NN-Combined, and also all the 'Atoms in chain' column for a complete nearest neighbor table. Sample output is shown below, in table format for easy viewing. Only first 6 of 13 shown for this particular sample trajectory file.

The --lengths option calculates the length of all hydrogen bonds (hydrogen-acceptor distance), in every frame.

• <prefix>-lengths<suffix>

Single column of data listing the hydrogen bond lengths in angstroms.

The --angles option calculates the angle of all hydrogen bonds, in every frame.

• <prefix>-angles<suffix>

Single column of data listing the hydrogen bond angles in degrees.

The --list option calculates the list of all hydrogen bonds, in every frame.

• <prefix>-list<suffix>

Seven (7) column data, in tab delimited format. The columns are:

1. Frame number, starting with 0.
2. Molecule of atom connected to donor hydrogen.
3. Name of atom connected to donor hydrogen.
4. Molecule of donor hydrogen atom.
5. Name of donor hydrogen atom.
6. Molecule of acceptor atom.
7. Name of acceptor atom.

The --lifetime option calculates the continuous and intermittent hydrogen bond lifetime autocorrelation.

• <prefix>-lifetimes<suffix>

Three column data, in tab delimited format. The columns are:

1. Frame number, starting with 0.
2. Continuous hydrogen bond lifetime correlation
3. Intermittent hydrogen bond lifetime correlation