# `forcefield`

Force fields are fun.

The forcefield structure is modeled off of the structures.py file, where each forcefield is considered a chain of residues of atoms.

Code author: Todd Dolinsky

Code author: Yong Huang

class pdb2pqr.forcefield.Forcefield(ff_name, definition, userff, usernames=None)

  Parameter definitions for a given forcefield.

  Note

  Pass ff and ff names file like objects rather than sorting out whether to use user-created files here.

  The forcefield class contains definitions for a given forcefield. Each forcefield object contains a dictionary of residues, with each residue containing a dictionary of atoms. Dictionaries are used instead of lists as the ordering is not important. The forcefield definition files are unedited, directly from the forcefield - all transformations are done within.

  __init__(ff_name, definition, userff, usernames=None)

    Initialize the class by parsing the definition file.

    Todo

    Why are files being loaded so deep in this function?

    Parameters:

      - ff_name (str) – the name of the forcefield (can be None)

      - definition (Definition) – the definition object for the Forcefield

      - userff (str) – path for user-defined forcefields file

      - usernames (str) – path to user-defined atom/residue names file

    Raises:

      ValueError – if invalid force field names specified

  classmethod get_amber_params(residue, name)

    Get AMBER forcefield definitions.

    Todo

    Should this be a staticmethod or a classmethod?

    Todo

    Figure out why residue.type has `int` values

    Parameters:

      - residue (Residue) – the residue

      - name (str) – the atom name

    Returns:

      (forcefield name of residue, forcefield name of atom)

    Return type:

      (str, str)

  classmethod get_charmm_params(residue, name)

    Get CHARMM forcefield definitions.

    Todo

    Should this be a staticmethod or a classmethod?

    Todo

    Figure out why residue.type has `int` values

    Parameters:

      - residue (Residue) – the residue

      - name (str) – the atom name

    Returns:

      (forcefield name of residue, forcefield name of atom)

    Return type:

      (str, str)

  get_group(resname, atomname)

    Get the group/type associated with the input fields.

    Parameters:

      - resname (str) – the residue name

      - atomname (str) – the atom name

    Returns:

      group name or empty string

    Return type:

      str

  get_names(resname, atomname)

    Get forcefield names associated with residue and atom.

    The names passed in point to ForcefieldResidue and ForcefieldAtom objects which may have different names; grab these names and return.

    Parameters:

      - resname (str) – the residue name

      - atomname (str) – the atom name

    Returns:

      (forcefield’s name for this residue, forcefield’s name for this atom)

    Return type:

      (str, str)

  get_params(resname, atomname)

    Get the charge and radius parameters for an atom in a residue.

    The residue itself is needed instead of simply its name because the forcefield may use a different residue name than the standard amino acid name.

    Todo

    Why do both `get_params()` and `get_params1()` exist?

    Parameters:

      - resname (str) – the residue name

      - atomname (str) – the atom name

    Returns:

      (charge of the atom, radius of the atom)

    Return type:

      (float, float)

  get_params1(residue, name)

    Get the charge and radius parameters for an atom in a residue.

    The residue itself is needed instead of simply its name because the forcefield may use a different residue name than the standard amino acid name.

    Todo

    Why do both `get_params()` and `get_params1()` exist?

    Parameters:

      - resname (str) – the residue name

      - name (str) – the atom name

    Returns:

      (charge of the atom, radius of the atom)

    Return type:

      (float, float)

  classmethod get_parse_params(residue, name)

    Get PARSE forcefield definitions.

    Todo

    Should this be a staticmethod or a classmethod?

    Parameters:

      - residue (Residue) – the residue

      - name (str) – the atom name

    Returns:

      (forcefield name of residue, forcefield name of atom)

    Return type:

      (str, str)

  get_residue(resname)

    Return the residue object with the given resname.

    Parameters:

      resname (str) – the name of the residue

    Returns:

      residue object

    Return type:

      ForcefieldResidue

  has_residue(resname)

    Check if the residue name is in the map or not.

    Parameters:

      resname (str) – the residue name to search

    Returns:

      indication of whether resname is in map

    Return type:

      bool

class pdb2pqr.forcefield.ForcefieldAtom(name, charge, radius, resname, group='')

  ForcefieldAtom class.

  Contains fields that are related to the forcefield at the atom level.

  __init__(name, charge, radius, resname, group='')

    Initialize the object.

    Parameters:

      - name (str) – atom name

      - charge (float) – the charge on the atom

      - radius (float) – the radius of the atom

      - resname (str) – the residue name

      - group (str) – the group name

  get(name)

    Get a member of the ForcefieldAtom class.

    Parameters:

      name (str) –

      the name of the member, including:

      - name: The atom name (returns string)

      - charge: The charge on the atom (returns float)

      - radius: The radius of the atom (returns float)

      - epsilon: The epsilon assocaited with the atom (returns float)

    Returns:

      the value of the member

    Raises:

      KeyError – if member does not exist

class pdb2pqr.forcefield.ForcefieldHandler(map_, reference)

  Process XML-format force field parameter files.

  __init__(map_, reference)

    Initialize handler

    Parameters:

      - map (dict) – dictionary of paramaeter information

      - reference (dict) – reference map for force field

  characters(text)

    Parse text information within XML tag.

    Parameters:

      text – the text value between the XML tags

  endElement(name)

    End XML element parsing.

    Parameters:

      name (str) – the name of the element

  classmethod find_matching_names(regname, map_)

    Find strings in the map that match the given regular expression.

    Todo

    Should this be a staticmethod instead of classmethod?

    Parameters:

      - regname (str) – the regular expression to search for in the map

      - map (dict) – the dictionary to search

    Returns:

      a list of regular expression match objects for dictionary keys that match the regular expression.

    Return type:

      [re.Match]

  startElement(name, _)

    Start XML element parsing.

    Parameters:

      name (str) – element name

  classmethod update_map(toname, fromname, map_)

    Update the given map by adding a pointer from a new name to an object.

    Todo

    Should this be a staticmethod instead of classmethod?

    Parameters:

      - toname (str) – the new name for the object

      - fromname (str) – the old name for the object

      - map (dict) – a dictionary of forcefield-related items

class pdb2pqr.forcefield.ForcefieldResidue(name)

  ForcefieldResidue class

  The ForceFieldResidue class contains a mapping of all atoms within the residue for easy searching.

  __init__(name)

    Initialize the ForceFieldResidue object.

    Parameters:

      name (str) – the name of the residue

  add_atom(atom)

    Add an atom to the ForcefieldResidue object.

    Parameters:

      atom (Atom) – the atom to be added

  get_atom(atomname)

    Return the atom object with the given atomname.

    Parameters:

      resname (str) – the name of the atom

    Returns:

      the atom object

    Return type:

      ForcefieldAtom

  has_atom(atomname)

    Check to see if the named atom is in the current residue.

    Parameters:

      atomname (str) – the name of the atom to search for

    Returns:

      indication of whether atmo is present

    Return type:

      bool