htmd.builder.preparation module

htmd.builder.preparation.proteinPrepare(mol_in, pH=7.0, verbose=0, returnDetails=False, hydrophobicThickness=None, holdSelection=None)

A system preparation wizard for HTMD.

Returns a Molecule object, where residues have been renamed to follow internal conventions on protonation (below). Coordinates are changed to optimize the H-bonding network. This should be roughly equivalent to mdweb and Maestro’s preparation wizard.

The following residue names are used in the returned molecule:

ASH Neutral ASP
CYX SS-bonded CYS
CYM Negative CYS
GLH Neutral GLU
HIP Positive HIS
HID Neutral HIS, proton HD1 present
HIE Neutral HIS, proton HE2 present
LYN Neutral LYS
TYM Negative TYR
AR0 Neutral ARG
Charge +1 Neutral Charge -1

A detailed table about the residues modified is returned (as a second return value) when returnDetails is True (see PreparationData object).

If hydrophobicThickness is set to a positive value 2*h, a warning is produced for titratable residues having -h<z<h and are buried in the protein by less than 75%. Note that the heuristic for the detection of membrane-exposed residues is very crude; the “buried fraction” computation (from propKa) is approximate; also, in the presence of cavities, residues may be solvent-exposed independently from their z location.


In case of problems, exclude water and other dummy atoms.

  • assign protonation states via propKa
  • flip residues to optimize H-bonding network
  • debump collisions
  • fill-in missing atoms, e.g. hydrogen atoms
  • mol_in (htmd.Molecule) – the object to be optimized
  • pH (float) – pH to decide titration
  • verbose (int) – verbosity
  • returnDetails (bool) – whether to return just the prepared Molecule (False, default) or a molecule and a ResidueInfo object including computed properties
  • hydrophobicThickness (float) – the thickness of the membrane in which the protein is embedded, or None if globular protein. Used to provide a warning about membrane-exposed residues.
  • holdSelection (str) – (Untested) Atom selection to be excluded from optimization. Only the carbon-alpha atom will be considered for the corresponding residue.

  • mol_out (Molecule) – the molecule titrated and optimized. The molecule object contains an additional attribute,
  • resData (PreparationData) – a table of residues with the corresponding protonation states, pKas, and other information


>>> tryp = Molecule('3PTB')
>>> tryp_op, prepData = proteinPrepare(tryp, returnDetails=True)
>>> tryp_op.write('proteinpreparation-test-main-ph-7.pdb')
>>> prepData                                                        
PreparationData object about 290 residues.
Unparametrized residue names: CA, BEN
Please find the full info in the .data property, e.g.:
  resname  resid insertion chain       pKa protonation flipped     buried
0     ILE     16               A       NaN         ILE     NaN        NaN
1     VAL     17               A       NaN         VAL     NaN        NaN
2     GLY     18               A       NaN         GLY     NaN        NaN
3     GLY     19               A       NaN         GLY     NaN        NaN
4     TYR     20               A  9.590845         TYR     NaN  14.642857
 . . .
>>> x_HIE91_ND1 = tryp_op.get("coords","resid 91 and  name ND1")
>>> x_SER93_H =   tryp_op.get("coords","resid 93 and  name H")
>>> len(x_SER93_H) == 3
>>> np.linalg.norm(x_HIE91_ND1-x_SER93_H) < 3
>>> tryp_op = proteinPrepare(tryp, pH=1.0)
>>> tryp_op.write('proteinpreparation-test-main-ph-1.pdb')
>>> tryp_op = proteinPrepare(tryp, pH=14.0)
>>> tryp_op.write('proteinpreparation-test-main-ph-14.pdb')
>>> mol = Molecule("1r1j")
>>> mo, prepData = proteinPrepare(mol, returnDetails=True)
>>> prepData.missedLigands
['NAG', 'ZN', 'OIR']
>>> his = == "HIS"
     resid insertion chain resname protonation
160    214               A     HIS         HID
163    217               A     HIS         HID
383    437               A     HIS         HID
529    583               A     HIS         HID
533    587               A     HIS         HIP
583    637               A     HIS         HID
627    681               A     HIS         HID
657    711               A     HIS         HIP
679    733               A     HIS         HID
>>> mor = Molecule("4dkl")
>>> mor.filter("protein and noh")
>>> mor_opt, mor_data = proteinPrepare(mor, returnDetails=True,
...                                    hydrophobicThickness=32.0)
>>> exposedRes =
>>> im=Molecule("4bkj")
>>> imo,imd=proteinPrepare(im,returnDetails=True)

See also



Unsupported/To Do/To Check:
  • ligands
  • termini
  • multiple chains
  • nucleic acids
  • coupled titrating residues
  • Disulfide bridge detection (implemented but unused)