# hydrogens and submodule contents¶

## hydrogens¶

Hydrogen optimization module for PDB2PQR.

This is an module for hydrogen optimization routines.

Todo

This module has too many lines and should be simplified.

Code author: Todd Dolinsky

Code author: Jens Erik Nielsen

Code author: Yong Huang

Code author: Nathan Baker

class pdb2pqr.hydrogens.HydrogenRoutines(debumper, handler)[source]

The main routines for hydrogen optimization.

Todo

This class really needs to be refactored.

__init__(debumper, handler)[source]

Initialize object.

Parameters: debumper (debump.Debump) – Debump object handler (HydrogenHandler) – HydrogenHandler object
cleanup()[source]

Delete extra carboxylic atoms.

If there are any extra carboxlyic *1 atoms, delete them. This may occur when no optimization is chosen.

initialize_full_optimization()[source]

Initialize the full optimization.

Detects all optimizeable donors and acceptors and sets the internal optlist.

initialize_wat_optimization()[source]

Initialize optimization for waters only.

Detects all optimizeable donors and acceptors and sets the internal optlist.

is_optimizeable(residue)[source]

Check to see if the given residue is optimizeable. There are three ways to identify a residue:

1. By name (i.e., HIS)
2. By reference name - a PDB file HSP has a HIS reference name
3. By patch - applied by propka, terminal selection
Parameters: residue (Residue) – the residue in question None if not optimizeable, otherwise the OptimizationHolder instance that corresponds to the residue. None or OptimizationHolder
optimize_hydrogens()[source]

The main driver for the optimization.

Note

Should be called only after the optlist has been initialized.

Todo

Remove hard-coded progress threshold and increment values.

Todo

This function needs to be simplified.

parse_hydrogen(res, topo)[source]

Parse a list of lines in order to make a hydrogen definition.

This is the current definition: Name Ttyp  A R # Stdconf HT Chi OPTm

Todo

The type of the res appears to be incorrect.

Todo

This function is too long and needs to be simplified.

Parameters: res (unknown) – the lines to parse (list) topo (pdb2pqr.topology.Topology) – Topology object the hydrogen definition object HydrogenDefinition
classmethod pka_switchstate(amb, state_id_)[source]

Switch a residue to a new state by first removing all hydrogens. This routine is used in pKa calculations only!

Parameters: amb (tup) – the amibiguity to switch state_id (int) – the state id to switch to
read_hydrogen_def(topo)[source]

Parameters: topo (Topology object) – Topology object
set_optimizeable_hydrogens()[source]

Set any hydrogen listed in HYDROGENS.xml that is optimizeable.

Used BEFORE hydrogen optimization to label atoms so that they won’t be debumped - i.e. if SER HG is too close to another atom, don’t debump but wait for optimization.

Note

This function should not be used if full optimization is not taking place.

switchstate(states, amb, state_id)[source]

Switch a residue to a new state by first removing all hydrogens.

Parameters: states (list) – the list of states amb (tup) – the amibiguity to switch state_id (int) – the state id to switch to
pdb2pqr.hydrogens.TITRATION_DICT = {'ARG': '1+2+3+4+5', 'ARG0': '1+2+3+4', 'ASH1c': '1', 'ASH1t': '2', 'ASH2c': '3', 'ASH2t': '4', 'ASP': '0', 'CTR-': '0', 'CTR01c': '1', 'CTR01t': '2', 'CTR02c': '3', 'CTR02t': '4', 'GLH1c': '1', 'GLH1t': '2', 'GLH2c': '3', 'GLH2t': '4', 'GLU': '0', 'H2': '2', 'H3': '1', 'H3+H2': '1+2', 'HSD': '1', 'HSE': '2', 'HSP': '1+2', 'LYS': '1', 'LYS0': '0', 'TYR': '1', 'TYR-': '0'}

A dictionary of the titration states for residues

pdb2pqr.hydrogens.create_handler(hyd_path='HYDROGENS.xml')[source]

Create and populate a hydrogen handler.

Parameters: hyd_def_file (string or pathlib.Path object) – path to hydrogen definition file HydrogenHandler object HydrogenHandler

## hydrogens.optimize¶

Hydrogen optimization routines.

Code author: Todd Dolinsky

Code author: Jens Erik Nielsen

Code author: Yong Huang

Code author: Nathan Baker

class pdb2pqr.hydrogens.optimize.OptimizationHolder[source]

A holder class for the XML parser.

__init__()[source]

Initialize self. See help(type(self)) for accurate signature.

class pdb2pqr.hydrogens.optimize.Optimize[source]

The holder class for the hydrogen optimization routines.

Individual optimization types inherit off of this class. Any functions used by multiple types appear here.

__init__()[source]

Initialize self. See help(type(self)) for accurate signature.

static get_hbond_angle(atom1, atom2, atom3)[source]

Get the angle between three atoms

Parameters: atom1 (Atom) – the first atom atom2 (Atom) – the second (vertex) atom atom3 (Atom) – the third atom the angle between the atoms in degrees float
static get_pair_energy(donor, acceptor)[source]

Get the energy between two atoms

Todo

Lots of code in this function could be accelerated with numpy.

Todo

Lots of hard-coded parameters in this function that need to be abstracted out.

Parameters: donor (Atom) – the first atom in the pair acceptor (Atom) – the second atom in the pair the energy of the pair float
classmethod get_position_with_three_bonds(atom)[source]

Find position for last bond in tetrahedral geometry.

Todo

Should this be a staticmethod rather than a classmethod?

Todo

Remove hard-coded values in function.

If there’s three bonds in a tetrahedral geometry, there’s only one available position. Find that position.

Parameters: atom (Atom) – atom to check coordinates (float, float, float)
classmethod get_positions_with_two_bonds(atom)[source]

Return possible coordinates for new bonds.

Todo

Remove some hard-coded values in this function.

Given a tetrahedral geometry with two existing bonds, return the two potential sets of coordinates that are possible for a new bond.

Parameters: atom (Atom) – atom to test for bonds 2-tuple of coordinates (floats) tuple
is_hbond(donor, acc)[source]

Determine whether this donor acceptor pair is a hydrogen bond.

Todo

Remove hard-coded hydrogen bond distance and angles.

Parameters: donor – donor atom acc – acceptor atom whether this pair is a hydrogen bond bool
make_atom_with_no_bonds(atom, closeatom, addname)[source]

Create an atom with no bonds.

Called for water oxygen atoms with no current bonds. Uses the closeatom to place the new atom directly colinear with the atom and the closeatom.

Parameters: atom (Atom) – the oxygen atom of the water closeatom (Atom) – the nearby atom (donor/acceptor) addname (str) – the name of the atom to add
classmethod make_atom_with_one_bond_h(atom, addname)[source]

Add a hydrogen to an alcoholic donor with one existing bond.

Todo

Does this need to be a classmethod or could it be a staticmethod?

Parameters: atom (Atom) – existing atom addname (str) – name of atom to add
classmethod make_atom_with_one_bond_lp(atom, addname)[source]

Add a lone pair to an alcoholic donor with one existing bond.

Todo

Does this need to be a classmethod or could it be a staticmethod?

Parameters: atom (Atom) – existing atom addname (str) – name of atom to add
classmethod make_water_with_one_bond(atom, addname)[source]

Add an atom to a water residue that already has one bond.

Uses the water reference structure to align the new atom.

Todo

Does this need to be a classmethod or could it be a staticmethod?

Parameters: atom (Atom) – existing atom addname (str) – name of atom to add
try_positions_three_bonds_h(donor, acc, newname, loc)[source]

Try making a hydrogen bond with the lone available position.

Parameters: donor (Atom) – hydrogen bond donor acc (Atom) – hydrogen bond acceptor newname (str) – name for new atom indication of whether atom was added bool
try_positions_three_bonds_lp(acc, donor, newname, loc)[source]

Make a hydrogen bond in the only position possible.

Try making a hydrogen bond using the lone available hydrogen position.

Parameters: acc (Atom) – hydrogen bond acceptor donor (Atom) – hydrogen bond donor newname (str) – new atom name loc ((float, float, float)) – location for atom (coordinates) indication whether atom was added bool
try_positions_with_two_bonds_h(donor, acc, newname, loc1, loc2)[source]

Try adding a new hydrogen to the two potential locations. If both form hydrogen bonds, place at whatever returns the best bond as determined by get_pair_energy.

Parameters: donor (Atom) – donor atom acc (Atom) – acceptor atom newname (str) – new atom name loc1 ((float, float, float)) – first coordinate to try loc2 ((float, float, float)) – first coordinate to try indication whether atom was added bool
try_positions_with_two_bonds_lp(acc, donor, newname, loc1, loc2)[source]

Attempt to place a LP on an atom.

Try placing an LP on a tetrahedral geometry with two existing bonds. If this isn’t a hydrogen bond it can return - otherwise ensure that the H(D)-A-LP angle is minimized.

Parameters: acc (Atom) – hydrogen bond acceptor donor (Atom) – hydrogen bond donor newname (str) – name for lone pair loc1 ((float, float, float)) – first location to try loc2 ((float, float, float)) – second location to try indication of whether LP was added bool
try_single_alcoholic_h(donor, acc, newatom)[source]

Attempt to add an atom to make a hydrogen bond.

Todo

Remove some hard-coded values in this function.

After a new bond has been added using makeAtomWithOneBond(), try to find the best orientation by rotating to form a hydrogen bond. If a bond cannot be formed, remove the newatom (thereby returning to a single bond).

Parameters: donor (Atom) – hydrogen bond donor acc (Atom) – hydrogen bond acceptor newatom (Atom) – new atom to add indication whether atom was added bool
try_single_alcoholic_lp(acc, donor, newatom)[source]

Attempt to add an atom to make a hydrogen bond.

Todo

Remove some hard-coded values in this function and figure out where others (e.g., “72”) come from.

After a new bond has been added using makeAtomWithOneBond(), ensure that a hydrogen bond has been made. If so, try to minimze the H(D)-A-LP angle. If that cannot be minimized, ignore the bond and remove the atom.

Parameters: donor (Atom) – hydrogen bond donor acc (Atom) – hydrogen bond acceptor newatom (Atom) – new atom to add indication whether atom was added bool

## hydrogens.structures¶

Topology-related classes for hydrogen optimization.

class pdb2pqr.hydrogens.structures.Alcoholic(residue, optinstance, routines)[source]

The class for alcoholic residue.

__init__(residue, optinstance, routines)[source]

Initialize the alcoholic class by removing the alcoholic hydrogen if it exists.

Parameters: residue (Residue) – the residue to optimize optinstance (OptimizationHandler) – the optimization instance containing information about what to optimize routines (Debump) – debumping routines object
complete()[source]

Complete an alcoholic optimization.

Call finalize() and then remove all extra LP atoms.

finalize()[source]

Finalize an alcoholic residue.

Todo

Replace hard-coded values in the function.

Try to minimize conflict with nearby atoms by building away from them. Called when LPs are still present so as to account for their bonds.

try_acceptor(acc, donor)[source]

Add a lone pair to an optimizeable residue.

Parameters: donor (Atom) – hydrogen bond donor acc (Atom) – hydrogen bond acceptor indication of whether addition was successful bool
try_both(donor, acc, accobj)[source]

Attempt to optimize both the donor and acceptor.

If one is fixed, we only need to try one side. Otherwise first try to satisfy the donor - if that’s succesful, try to satisfy the acceptor. An undo may be necessary if the donor is satisfied and the acceptor isn’t.

Parameters: donor (Atom) – hydrogen bond donor acc (Atom) – hydrogen bond acceptor accobj (Flip) – a Flip-like hydrogen bond structure object indication of whether hydrogen was added bool
try_donor(donor, acc)[source]

Add hydrogen to an optimizable residue.

Parameters: donor (Atom) – hydrogen bond donor acc (Atom) – hydrogen bond acceptor indication of whether addition was successful bool
class pdb2pqr.hydrogens.structures.Carboxylic(residue, optinstance, routines)[source]

The class for carboxylic residues

__init__(residue, optinstance, routines)[source]

Initialize carboxylic optimization class.

Initialize a case where the lone hydrogen atom can have four different orientations. Works similar to initializeFlip() by pre-adding the necessary atoms.

This also takes into account that the carboxyl group has different bond lengths for the two C-O bonds - this is probably due to one bond being assigned as a C=O. As a result hydrogens are only added to the C-O (longer) bond.

Parameters: residue (Residue) – the residue to flip optinstance (OptimizationHandler) – the optimization instance containing information about what to optimize routines (Debump) – debumping routines object
complete()[source]

If not already fixed, finalize the optimization.

finalize()[source]

Finalize a protontated residue.

Try to minimize conflict with nearby atoms.

fix(donor, acc)[source]

Fix the carboxylic residue.

is_carboxylic_hbond(donor, acc)[source]

Determine whether this donor acceptor pair is a hydrogen bond.

Parameters: donor (Atom) – hydrogen bond donor acc (Atom) – hydrogen bond acceptor accobj (Flip) – a Flip-like hydrogen bond structure object indication of whether hydrogen was added bool
rename(hydatom)[source]

Rename the optimized atoms appropriately.

This is done since the forcefields tend to require that the hydrogen is linked to a specific oxygen, and this atom may have different parameter values.

Parameters: hydatom (Atom) – the hydrogen atom that was added
try_acceptor(acc, donor)[source]

Add lone pair to an optimizable residue.

Parameters: donor (Atom) – hydrogen bond donor acc (Atom) – hydrogen bond acceptor indication of whether addition was successful bool
try_both(donor, acc, accobj)[source]

Attempt to optimize donor and acceptor.

Called when both the donor and acceptor are optimizeable. If one is fixed, we only need to try one side. Otherwise first try to satisfy the donor - if that’s succesful, try to satisfy the acceptor. An undo may be necessary if the donor is satisfied and the acceptor isn’t.

Parameters: donor (Atom) – hydrogen bond donor acc (Atom) – hydrogen bond acceptor accobj (Flip) – a Flip-like hydrogen bond structure object indication of whether hydrogen was added bool
try_donor(donor, acc)[source]

Add hydrogen to an optimizable residue.

Parameters: donor (Atom) – hydrogen bond donor acc (Atom) – hydrogen bond acceptor indication of whether addition was successful bool
class pdb2pqr.hydrogens.structures.Flip(residue, optinstance, routines)[source]

The holder for optimization of flippable residues.

__init__(residue, optinstance, routines)[source]

Initialize a potential flip.

Rather than flipping the given residue back and forth, take each atom that would be flipped and pre-flip it, making a new *FLIP atom in its place.

Parameters: residue (Residue) – the residue to flip optinstance (OptimizationHandler) – the optimization instance containing information about what to optimize routines (Debump) – debumping routines object
complete()[source]

Complete the flippable residue optimization.

Call the finalize() function, and then rename all FLIP atoms back to their standard names.

finalize()[source]

Finalize a flippable group back to its original state.

Since the original atoms are now *FLIP, it deletes the * atoms and renames the *FLIP atoms back to *.

fix_flip(bondatom)[source]

Remove atoms if hydrogen bond has been found for specified atom.

If bondatom is of type *FLIP, remove all * atoms, otherwise remove all *FLIP atoms.

Parameters: bondatom (Atom) – atom to flip
try_acceptor(acc, donor)[source]

Aa lone pair to an optimizable residue.

Parameters: acc (Atom) – hydrogen bond acceptor donor (Atom) – hydrogen bond donor indication of whether addition was successful bool
try_both(donor, acc, accobj)[source]

Try to optimize both donor and acceptor bonds.

Called when both the donor and acceptor are optimizeable. If one is fixed, we only need to try one side. Otherwise first try to satisfy the donor - if that’s succesful, try to satisfy the acceptor. An undo may be necessary if the donor is satisfied and the acceptor isn’t.

Parameters: donor (Atom) – hydrogen bond donor acc (Atom) – hydrogen bond acceptor accobj (Flip) – a Flip-like hydrogen bond structure object indication of whether hydrogen was added bool
try_donor(donor, acc)[source]

Add hydrogen to an optimizable residue.

Parameters: donor (Atom) – hydrogen bond donor acc (Atom) – hydrogen bond acceptor indication of whether addition was successful bool
class pdb2pqr.hydrogens.structures.Generic(residue, optinstance, routines)[source]

Generic optimization class

__init__(residue, optinstance, routines)[source]

Initialize a potential optimization.

Parameters: residue (Residue) – the residue to optimize optinstance (OptimizationHandler) – the optimization instance containing information about what to optimize routines (Debump) – debumping routines object
complete()[source]

finalize()[source]

Initialize some variable and pass.

class pdb2pqr.hydrogens.structures.HydrogenAmbiguity(residue, hdef, routines)[source]

Contains information about ambiguities in hydrogen conformations.

__init__(residue, hdef, routines)[source]

If the residue has a rotateable hydrogen, remove it.

If it can be flipped, pre-flip the residue by creating all additional atoms.

Parameters: residue (Residue) – the residue in question hdef – the hydrogen definition matching the residue routines (Debump) – the debumping routines object
class pdb2pqr.hydrogens.structures.HydrogenConformation(hname, boundatom, bondlength)[source]

Class for possible hydrogen conformations.

The HydrogenConformation class contains data about possible hydrogen conformations as specified in the hydrogen data file.

__init__(hname, boundatom, bondlength)[source]
Parameters: hname – The hydrogen name (string) boundatom – The atom the hydrogen is bound to (string) bondlength – The bond length (float)
add_atom(atom)[source]

Add an atom to the list of atoms.

Parameters: atom (DefinitionAtom) – the atom to be added
class pdb2pqr.hydrogens.structures.HydrogenDefinition(name, opttype, optangle, map_)[source]

Class for potential ambiguities in amino acid hydrogens.

It is essentially the hydrogen definition file in object form.

__init__(name, opttype, optangle, map_)[source]

Initialize the object with information from the definition file.

See HYDROGENS.XML for more information.

Parameters: name (str) – the name of the grouping opttype (str) – the optimization type of the grouping optangle (str) – the optimization angle of the grouping map – the map of hydrogens
add_conf(conf)[source]

Add a hydrogen conformation to the list.

Parameters: conf (HydrogenConformation) – the conformation to be added
class pdb2pqr.hydrogens.structures.HydrogenHandler[source]

Extends the SAX XML Parser to parse the Hydrogens.xml class.

__init__()[source]

Initialize self. See help(type(self)) for accurate signature.

characters(text)[source]

Set a given attribute of the object to the text.

Parameters: text (str) – value of the attribute
endElement(name)[source]

Complete object is passed in by name parameter.

Todo

Rename this and related methods to conform with PEP8

Parameters: name (str) – name for element
startElement(name, _)[source]

Create optimization holder objects or atoms.

Todo

Rename this and related methods to conform with PEP8

Parameters: name (str) – name for element
class pdb2pqr.hydrogens.structures.PotentialBond(atom1, atom2, dist)[source]

A class containing the hydrogen bond structure.

__init__(atom1, atom2, dist)[source]

Initialize the class.

Parameters: atom1 (Atom) – the first atom in the potential bond atom2 (Atom) – the second atom in the potential bond dist (float) – the distance between the two atoms
class pdb2pqr.hydrogens.structures.Water(residue, optinstance, routines)[source]

The class for water residues.

__init__(residue, optinstance, routines)[source]

Initialize the water optimization class.

Parameters: residue (Residue) – the residue to flip optinstance (OptimizationHandler) – the optimization instance containing information about what to optimize routines (Debump) – debumping routines object
complete()[source]

Complete the water optimization process.

finalize()[source]

Finalize a water residue.

Try to minimize conflict with nearby atoms by building away from them. Called when LPs are still present so as to account for their bonds.

try_acceptor(acc, donor)[source]

The main driver for adding an LP to an optimizeable residue.

Todo

This looks like a bug: donorh ends up being the last item in donor.bonds. This may be fixed by setting a best_donorh to go with bestdist and using best_donorh in the function below

Parameters: donor (Atom) – hydrogen bond donor acc (Atom) – hydrogen bond acceptor indication of whether addition was successful bool
try_both(donor, acc, accobj)[source]

Attempt to optimize both the donor and the acceptor.

If one is fixed, we only need to try one side. Otherwise first try to satisfy the donor - if that’s successful, try to satisfy the acceptor. An undo may be necessary if the donor is satisfied and the acceptor isn’t.

Parameters: donor (Atom) – hydrogen bond donor acc (Atom) – hydrogen bond acceptor accobj (Flip) – a Flip-like hydrogen bond structure object indication of whether hydrogen was added bool
try_donor(donor, acc)[source]

Add hydrogen to an optimizable residue.

Parameters: donor (Atom) – hydrogen bond donor acc (Atom) – hydrogen bond acceptor indication of whether addition was successful bool