Usage#

Simple examples#

The examples below are based on a simple test case using Berger POPC. The files can be found on github in the directories docs/Berger_POPC_test_case and def_files. You will need 3 files :

Here are some examples on how to run buildH with these 3 files:

Basic run on a single structure#

buildH -c start_128popc.pdb -l Berger_POPC -d Berger_POPC.def

buildH can be used on a single structure (OK not very common for research, but useful for debugging ;-)). The pdb structure is passed with option -c (it also works with gro files), the def file with -d. The flag -l is mandatory, it tells buildH what force field and lipid to use: here it is Berger_POPC. The order parameters will be written to OP_buildH.out which is the default name.

Same but with a chosen output name#

buildH -c start_128popc.pdb -l Berger_POPC -d Berger_POPC.def \
-o my_OP_buildH.out

Here we add a -o flag which tells buildH to output the results in a file named my_OP_buildH.out.

Run on a trajectory#

buildH -c start_128popc.pdb -l Berger_POPC -d Berger_POPC.def \
-t popc0-25ns_dt1000.xtc

Here the flag -t indicates a trajectory. The final order parameters will be averaged over all lipids and all frames for each C-H present in the def file. More can be found on how the averaging is done here. The default name OP_buildH.out will be used.

Same with an output trajectory with reconstructed hydrogens#

buildH -c start_128popc.pdb -l Berger_POPC -d Berger_POPC.def \
-t popc0-25ns_dt1000.xtc -opx popc0-25ns_dt1000_with_H

Here we added the flag -opx to request a pdb and an xtc file of the system with all the reconstructed hydrogens. Note that the flag takes a base name without extension since it will create a pdb and an xtc, here popc0-25ns_dt1000_with_H.pdb and popc0-25ns_dt1000_with_H.xtc. The use of this flag -opx requires the .def file to contain all possible pairs of C-H to reconstruct (since the trajectory with all Hs will be reconstructed). Importantly, the newly built hydrogens in the output pdb will be named according to the names written in the def file. See more about this here. The order parameters will be written in OP_buildH.out (default name).

Get a single pdb file with reconstructed hydrogens#

If you do not provide a trajectory with the -t flag and you use the opx flag, buildH will only output a pdb file with hydrogens (no xtc will be produced):

buildH -c start_128popc.pdb -l Berger_POPC -d Berger_POPC.def \
-opx start_128popc_wH

In this case, the file start_128popc_wH.pdb with reconstructed hydrogens will be created as well as OP_buildH.out with the order parameters.

Additional details#

Why do I need a def file?#

A def file looks like this:

gamma1_1 POPC C1  H11
gamma1_2 POPC C1  H12
gamma1_3 POPC C1  H13
[...]

Each line corresponds to a given C-H. The 4 columns correspond to the generic name, residue name, carbon name and hydrogen name, respectively, for that C-H.

In buildH, the def file has three main purposes:

  • Tell what are the C-H we want to consider for H reconstruction and order parameter calculation.

  • Give a generic name to each C-H (which will appear in the output) and make the correspondance with the PDB names (e.g. gamma1_1 stands for the C-H which have C1 and H11 atom names in the pdb file.

  • If an output file with the newly built hydrogens is requested, their names will follow the 4th column of the def file. For example, the 3 hydrogens reconstructed on atom C1 will be named H11, H12 and H13.

In the following example dealing with a Berger POPC, the order parameters will be calculated on the polar head only (excluding the CH3s of choline):

beta1  POPC C5  H51
beta2  POPC C5  H52
alpha1 POPC C6  H61
alpha2 POPC C6  H62
g3_1   POPC C12 H121
g3_2   POPC C12 H122
g2_1   POPC C13 H131
g1_1   POPC C32 H321
g1_2   POPC C32 H322

Using the Berger POPC trajectory of 25 frames, the output OP_buildH.out will contain the order parameters of the C-H specified in the def file:

# OP_name            resname atom1 atom2  OP_mean OP_stddev OP_stem
#--------------------------------------------------------------------
beta1                POPC    C5    H51    0.04934  0.11999  0.01061
beta2                POPC    C5    H52    0.07162  0.12108  0.01070
alpha1               POPC    C6    H61    0.11839  0.15261  0.01349
alpha2               POPC    C6    H62    0.13903  0.19003  0.01680
g3_1                 POPC    C12   H121  -0.28674  0.09135  0.00807
g3_2                 POPC    C12   H122  -0.16195  0.14832  0.01311
g2_1                 POPC    C13   H131  -0.15159  0.14511  0.01283
g1_1                 POPC    C32   H321   0.21133  0.22491  0.01988
g1_2                 POPC    C32   H322   0.09638  0.16189  0.01431

The def files of the lipids supported by buildH can be found here.

More on def files and creating your own ones can be found here.

Supported lipids#

The list of supported lipids can be requested with buildH -h. This command will throw a detailed help to the screen, the list will be indicated at the last line. If you want to analyze a lipid that is not present in buildH, you will have to create your own def file as well as a json file which explains to buildH how the hydrogens will be reconstructed. This user json file is passed with option -lt. Here is more documentation on how to create your own def file and how to create your own json file.

What about polar hydrogens?#

When a lipid contains polar hydrogens, such as the 3 Hs of ethanolamine in PE or the H of the hydroxyl group in cholesterol, these Hs are handled explicitely by the force field. Thus they already exist in the input pdb (and possibly xtc) given as input to buildH. In this case, those Hs will be ignored by buildH and no order parameter will be calculated on these ones. Usually, these Hs are exchangeable and we do not have experimental order parameters for them. If an output trajectory is requested, buildH will just copy the coordinates of these Hs as it does for the heavy atoms.

There is an exception for the force field CHARMM36UA. In this force field, only the apolar Hs of the sn-1 and sn-2 aliphatic tails are in a united-atom representation (starting from the 3rd carbon up to the end of the chain). The other apolar Hs (choline, glycerol, second carbon of sn-1 and sn-2) are explicit. Thus for these latter, buildH will ignore them as it does for polar Hs as explained above. Again, if an output pdb (or xtc) is requested, those Hs will be copied to the output pdb and xtc files.

Mixtures of lipids#

If you have a mixture of lipids, you will have to run buildH for each lipid separately. If you request an output trajectory, this will have to be done iteratively as well. A guided example on a POPC/POPE mixture can be found in Notebook03. Another one on a POPC/cholesterol mixture can be found in Notebook05.

Periodic boundary conditions#

Sometimes, when performing MD, some molecules are split over periodic boundary conditions (PBC). buildH takes as input whole structures (pdb, gro, xtc, etc.). If broken molecules are supplied, it will most likely generate nonsense results. So it is up to the user to take care of making molecules whole before running buildH (e.g. by using a tool like trjconv in GROMACS with flag -pbc mol).

BuildH as a module#

buildH is intended to be used mainly in the Unix command line. It is also possible to use it as a module but to a lesser extent. The features available are minimal: you can just call the main function (buildh.launch()) and result files are still written.

It’s not a proper API but more a way to call buildH inside larger analysis python scripts.

A guided example can be found on Notebook04.