# `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)

  The main routines for hydrogen optimization.

  Todo

  This class really needs to be refactored.

  __init__(debumper, handler)

    Initialize object.

    Parameters:

      - debumper (debump.Debump) – Debump object

      - handler (HydrogenHandler) – HydrogenHandler object

  cleanup()

    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()

    Initialize the full optimization.

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

  initialize_wat_optimization()

    Initialize optimization for waters only.

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

  is_optimizeable(residue)

    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

    Returns:

      None if not optimizeable, otherwise the OptimizationHolder instance that corresponds to the residue.

    Return type:

      None or OptimizationHolder

  optimize_hydrogens()

    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)

    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

    Returns:

      the hydrogen definition object

    Return type:

      HydrogenDefinition

  classmethod pka_switchstate(amb, state_id_)

    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)

    Read the hydrogen definition file

    Parameters:

      topo (Topology object) – Topology object

  set_optimizeable_hydrogens()

    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)

    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')

  Create and populate a hydrogen handler.

  Parameters:

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

  Returns:

    HydrogenHandler object

  Return type:

    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

  A holder class for the XML parser.

  __init__()

class pdb2pqr.hydrogens.optimize.Optimize

  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__()
  static get_hbond_angle(atom1, atom2, atom3)

    Get the angle between three atoms

    Parameters:

      - atom1 (Atom) – the first atom

      - atom2 (Atom) – the second (vertex) atom

      - atom3 (Atom) – the third atom

    Returns:

      the angle between the atoms in degrees

    Return type:

      float

  static get_pair_energy(donor, acceptor)

    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

    Returns:

      the energy of the pair

    Return type:

      float

  classmethod get_position_with_three_bonds(atom)

    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

    Returns:

      coordinates

    Return type:

      (float, float, float)

  classmethod get_positions_with_two_bonds(atom)

    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

    Returns:

      2-tuple of coordinates (floats)

    Return type:

      tuple

  is_hbond(donor, acc)

    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

    Returns:

      whether this pair is a hydrogen bond

    Return type:

      bool

  make_atom_with_no_bonds(atom, closeatom, addname)

    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)

    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)

    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)

    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)

    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

    Returns:

      indication of whether atom was added

    Return type:

      bool

  try_positions_three_bonds_lp(acc, donor, newname, loc)

    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)

    Returns:

      indication whether atom was added

    Return type:

      bool

  try_positions_with_two_bonds_h(donor, acc, newname, loc1, loc2)

    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

    Returns:

      indication whether atom was added

    Return type:

      bool

  try_positions_with_two_bonds_lp(acc, donor, newname, loc1, loc2)

    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

    Returns:

      indication of whether LP was added

    Return type:

      bool

  try_single_alcoholic_h(donor, acc, newatom)

    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

    Returns:

      indication whether atom was added

    Return type:

      bool

  try_single_alcoholic_lp(acc, donor, newatom)

    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

    Returns:

      indication whether atom was added

    Return type:

      bool

## `hydrogens.structures`

Topology-related classes for hydrogen optimization.

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

  The class for alcoholic residue.

  __init__(residue, optinstance, routines)

    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()

    Complete an alcoholic optimization.

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

  finalize()

    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)

    Add a lone pair to an optimizeable residue.

    Parameters:

      - donor (Atom) – hydrogen bond donor

      - acc (Atom) – hydrogen bond acceptor

    Returns:

      indication of whether addition was successful

    Return type:

      bool

  try_both(donor, acc, accobj)

    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

    Returns:

      indication of whether hydrogen was added

    Return type:

      bool

  try_donor(donor, acc)

    Add hydrogen to an optimizable residue.

    Parameters:

      - donor (Atom) – hydrogen bond donor

      - acc (Atom) – hydrogen bond acceptor

    Returns:

      indication of whether addition was successful

    Return type:

      bool

class pdb2pqr.hydrogens.structures.Carboxylic(residue, optinstance, routines)

  The class for carboxylic residues

  __init__(residue, optinstance, routines)

    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()

    If not already fixed, finalize the optimization.

  finalize()

    Finalize a protontated residue.

    Try to minimize conflict with nearby atoms.

  fix(donor, acc)

    Fix the carboxylic residue.

  is_carboxylic_hbond(donor, acc)

    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

    Returns:

      indication of whether hydrogen was added

    Return type:

      bool

  rename(hydatom)

    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)

    Add lone pair to an optimizable residue.

    Parameters:

      - donor (Atom) – hydrogen bond donor

      - acc (Atom) – hydrogen bond acceptor

    Returns:

      indication of whether addition was successful

    Return type:

      bool

  try_both(donor, acc, accobj)

    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

    Returns:

      indication of whether hydrogen was added

    Return type:

      bool

  try_donor(donor, acc)

    Add hydrogen to an optimizable residue.

    Parameters:

      - donor (Atom) – hydrogen bond donor

      - acc (Atom) – hydrogen bond acceptor

    Returns:

      indication of whether addition was successful

    Return type:

      bool

class pdb2pqr.hydrogens.structures.Flip(residue, optinstance, routines)

  The holder for optimization of flippable residues.

  __init__(residue, optinstance, routines)

    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()

    Complete the flippable residue optimization.

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

  finalize()

    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)

    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)

    Aa lone pair to an optimizable residue.

    Parameters:

      - acc (Atom) – hydrogen bond acceptor

      - donor (Atom) – hydrogen bond donor

    Returns:

      indication of whether addition was successful

    Return type:

      bool

  try_both(donor, acc, accobj)

    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

    Returns:

      indication of whether hydrogen was added

    Return type:

      bool

  try_donor(donor, acc)

    Add hydrogen to an optimizable residue.

    Parameters:

      - donor (Atom) – hydrogen bond donor

      - acc (Atom) – hydrogen bond acceptor

    Returns:

      indication of whether addition was successful

    Return type:

      bool

class pdb2pqr.hydrogens.structures.Generic(residue, optinstance, routines)

  Generic optimization class

  __init__(residue, optinstance, routines)

    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()

    If not already fixed, finalize.

  finalize()

    Initialize some variable and pass.

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

  Contains information about ambiguities in hydrogen conformations.

  __init__(residue, hdef, routines)

    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)

  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)
    Parameters:

      - hname – The hydrogen name (string)

      - boundatom – The atom the hydrogen is bound to (string)

      - bondlength – The bond length (float)

  add_atom(atom)

    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_)

  Class for potential ambiguities in amino acid hydrogens.

  It is essentially the hydrogen definition file in object form.

  __init__(name, opttype, optangle, map_)

    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)

    Add a hydrogen conformation to the list.

    Parameters:

      conf (HydrogenConformation) – the conformation to be added

class pdb2pqr.hydrogens.structures.HydrogenHandler

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

  __init__()
  characters(text)

    Set a given attribute of the object to the text.

    Parameters:

      text (str) – value of the attribute

  endElement(name)

    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, _)

    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)

  A class containing the hydrogen bond structure.

  __init__(atom1, atom2, dist)

    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)

  The class for water residues.

  __init__(residue, optinstance, routines)

    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()

    Complete the water optimization process.

  finalize()

    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)

    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

    Returns:

      indication of whether addition was successful

    Return type:

      bool

  try_both(donor, acc, accobj)

    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

    Returns:

      indication of whether hydrogen was added

    Return type:

      bool

  try_donor(donor, acc)

    Add hydrogen to an optimizable residue.

    Parameters:

      - donor (Atom) – hydrogen bond donor

      - acc (Atom) – hydrogen bond acceptor

    Returns:

      indication of whether addition was successful

    Return type:

      bool