first bits and pieces of documentation for the mm module

modules/mol/mm/doc/buildingblock.rst

+Blocks
+================================================================================
+
+.. currentmodule:: ost.mol
+
+The most basic type of a residue description is the BuildingBlock. It contains
+information of atom names and their corresponding types, charges and
+optionally also their masses. Interactions for all particles can also
+be defined even though they are optional, except the bonds giving
+information about the connectivity. 
+You often need to manipulate building blocks or
+the residues they refer to in an automated manner. That's where the 
+Blockmodifiers come in, with the GromacsBlockModifier as a specific
+implementation. As a special case there also exist HydrogenConstructors.
+
+
+.. class:: BuildingBlock
+
+  .. method:: Match(residue, match_connectivity)
+
+    Checks, wether the given residue matches the atom names in the 
+    BuildingBlock. The Connectivity gets optionally checked.
+
+    :param residue:    
+    :param match_connectivity: If set to true, the function checks the bonds
+                               in the residue with the defined bonds in the
+                               buildingblock 
+
+    :type residue:    :class:`ResidueHandle`
+    :type match_connectivity:    :class:`bool`
+
+
+  .. method:: Connect(residue, editor)
+
+    Connects residue based on the bond definitions of the BuildingBlock.
+
+    :param residue:     residue to be connected
+    :param editor:      editor associated to the residues entity
+
+    :type residue:      :class:`ResidueHandle`
+    :type editor:       :class:`XCSEditor`
+
+    :raises:            :class:`RuntimeError` when required atom can not be found in 
+                        residue
+
+
+  .. method:: AddAtom(name, type, charge, mass = None)
+
+    :param name:        name of atom
+    :param type:        its corresponding forcefield type
+    :param charge:      its charge
+    :param mass:        its mass
+
+
+  .. method:: RemoveAtom(name)
+
+    removes atom from building block with all its associated values and 
+    interactions
+
+    :param name:        name of atom to be removed
+
+
+  .. method:: ReplaceAtom(name, new_name, new_type, new_charge, new_mass = None)
+
+    Replace given atom with and resets type, charge and mass. All interactions
+    containing that atom get adapted as well
+
+    :param name:        name of atom to be replaced
+    :param new_name:    new name of atom
+    :param new_type:    new type of atom
+    :param new_charge:  new charge of atom
+    :param new_mass:    new mass of atom
+
+
+  .. method:: RemoveInteractionsToPrev()
+
+    Removes all interactions associated to an atom of a previous residues.
+    This gets indicated by an atom name prefixed by a *-*
+
+
+  .. method:: RemoveInteractionsToNext()
+
+    Removes all interactions associated to an atom of a next residues.
+    This gets indicated by an atom name prefixed by a *+*
+
+
+  .. method:: AddBond(bond, replace_existing = False)
+
+    :param bond:        Bond to be added
+    :param replace_existing: Whether potentially already existing bond for the
+                             same atoms should be replaced.
+
+    :type bond:         :class:`Interaction`
+    :type replace_exisiting: bool
+
+
+  .. method:: AddAngle(angle, replace_existing = False)
+
+    :param angle:        Angle to be added
+    :param replace_existing: Whether potentially already existing angle for the
+                             same atoms should be replaced.
+
+    :type angle:         :class:`Interaction`
+    :type replace_exisiting: bool
+
+
+  .. method:: AddDihedral(dihedral, replace_existing = False)
+
+    :param dihedral:    Dihedral to be added
+    :param replace_existing: Whether potentially already existing dihedral for the
+                             same atoms should be replaced.
+
+    :type dihedral:     :class:`Interaction`
+    :type replace_exisiting: bool
+
+
+  .. method:: AddImproper(improper, replace_existing = False)
+
+    :param improper:    Improper to be added
+    :param replace_existing: Whether potentially already existing improper for the
+                             same atoms should be replaced.
+
+    :type improper:     :class:`Interaction`
+    :type replace_exisiting: bool
+
+
+  .. method:: AddExclusion(exclusion, replace_existing = False)
+
+    :param exclusion:        Exclusion to be added
+    :param replace_existing: Whether potentially already existing Exclusion for the
+                             same atoms should be replaced.
+
+    :type exclusion:         :class:`Interaction`
+    :type replace_exisiting: bool
+
+
+  .. method:: AddCMap(cmap, replace_existing = False)
+
+    :param cmap:        CMap to be added
+    :param replace_existing: Whether potentially already existing cmap for the
+                             same atoms should be replaced.
+
+    :type cmap:         :class:`Interaction`
+    :type replace_exisiting: bool
+
+
+  .. method:: AddConstraint(constraint, replace_existing = False)
+
+    :param constraint:  Constraint to be added
+    :param replace_existing: Whether potentially already existing constraint for the
+                             same atoms should be replaced.
+
+    :type constraint:         :class:`Interaction`
+    :type replace_exisiting: bool 
+
+
+  .. method:: GetType(name)
+
+    Gets forcefield type from atom with given name
+
+    :param name:        Name from atom you want the type from
+
+    :type name:         :class:`str`
+
+    :raises: :exc: `RuntimeError` when atom can not be found in 
+                                  BuildingBlock    
+
+  .. method:: GetCharge(name)
+
+    Gets charge from atom with given name
+
+    :param name:        Name from atom you want the charge from
+
+    :type name:         :class:`str`
+
+    :raises: :class:`RuntimeError` when atom can not be found in 
+                                   BuildingBlock 
+
+
+  .. method:: GetMass(name)
+
+    Gets mass from atom with given name
+
+    :param name:        Name from atom you want the mass from
+
+    :type name:         :class:`str`
+
+    :raises: :class:`RuntimeError` when atom can not be found in 
+                                   BuildingBlock 
+
+
+  .. method:: GetBonds()
+    :returns: list of all bonds
+
+
+  .. method:: GetAngles()
+    :returns: list of all angles
+
+
+  .. method:: GetDihedrals()
+    :returns: list of all dihedrals
+
+
+  .. method:: GetImpropers()
+    :returns: list of all impropers
+
+
+  .. method:: GetCMaps()
+    :returns: list of all cmaps
+
+
+  .. method:: GetExclusions()
+    :returns: list of all exlusions
+
+
+  .. method:: GetConstraints()
+    :returns: list of all constraints
+
+Automated modification of :class:`BuildingBlock` and :class:`ResidueHandle`
+--------------------------------------------------------------------------------
+
+.. class:: GromacsBlockModifier
+
+  .. method:: ApplyOnBuildingBlock(block)
+
+    Applies all defined rules on the given :class:`BuildingBlock`
+
+    :param block:       :class:`BuildingBlock`
+
+  .. method:: ApplyOnResidue(residue)
+
+    Applies all defined rules on the given :class:`ResidueHandle`
+
+    :param residue:     :class:`ResidueHandle`
+
+  .. method:: AddReplaceRule(name, new_name, new_type, new_charge)
+
+    Rule, that basically renames and an atom and also resets its type and charge
+    in a :class:`BuildingBlock`. A simple renaming occurs in a :class:`ResidueHandle`.
+
+    :param name:        :class:`str` name of the atom to be changed
+    :param new_name:    :class:`str`
+    :param new_type:    :class:`str`
+    :param new_charge:  :class:`float`
+
+  .. method:: AddAddRule(number, method, atom_names, anchors, type, charge)
+
+    A rule to add new atoms the gromacs way, see
+    `Gromacs Manual <http://www.gromacs.org/Documentation/Manual>`_ 
+    for the exact definition of the parameters. A :class:`BuildingBlock`
+    gets modified by adding the new atom definitions and also the
+    corresponding bonds describing the connectivity. In case of 
+    :class:`ResidueHandle` the new Atoms with connectivity get added with 
+    their positions as defined by the gromacs adding rule. 
+
+    :param number:      :class:`int` number of atoms to be added
+    :param method:      :class:`int` gromacs adding rule
+    :param atom_names:  :class:`list` of strings containing the new atom names
+    :param anchors:     :class:`list` of strings containing atom names used as anchor
+    :param type:        :class:`str` the type the atoms will have
+    :param charge:      :class:`float` the charge the atoms will have
+
+  .. method:: AddDeleteAtom(name)
+
+    Defines an atom that has to be removed. In case of the 
+    :class:`BuildingBlock` this removes this particular atom plus all 
+    interactions connected to it, in case of :class:`ResidueHandle`, the
+    atom simply gets deleted.
+
+    :param name:        :class:`str` atom to be deleted
+
+  .. method:: AddBond(bond)
+
+    Adds a bond, this only has effect on :class:`BuildingBlock`, not
+    on :class:`ResidueHandle`
+
+    :param bond:        :class:`Interaction` bond to be added
+
+  .. method:: AddAngle(angle)
+
+    Adds an angle, this only has effect on :class:`BuildingBlock`, not
+    on :class:`ResidueHandle`
+
+    :param angle:        :class:`Interaction` angle to be added
+
+  .. method:: AddDihedral(dihedral)
+
+    Adds a dihedral, this only has effect on :class:`BuildingBlock`, not
+    on :class:`ResidueHandle`
+
+    :param dihedral:        :class:`Interaction` dihedral to be added
+
+  .. method:: AddImproper(improper)
+
+    Adds an improper, this only has effect on :class:`BuildingBlock`, not
+    on :class:`ResidueHandle`
+
+    :param improper:        :class:`Interaction` improper to be added
+
+  .. method:: AddCMap(cmap)
+
+    Adds a cmap, this only has effect on :class:`BuildingBlock`, not
+    on :class:`ResidueHandle`
+
+    :param cmap:        :class:`Interaction` cmap to be added
+
+
+.. class:: GromacsHydrogenConstructor
+
+  The :class:`GromacsHydrogenConstructor` is the gromacs way of adding
+  hydrogens to a structure.
+
+  .. method:: ApplyOnBuildingBlock(block)
+
+    Guess what it does: !!ABSOLUTELY NOTHING!! just there for consistency
+
+    :param block:       :class:`BuildingBlock` block that won't be changed at all!
+                                               Isn't that awesome?
+
+  .. method:: ApplyOnResidue(residue)
+
+    Constructs hydrogens based on the defined hydrogen adding rules
+
+    :param residue:     :class:`ResidueHandle` to be modified
+
+  .. method:: AddHydrogenRule(number, method, hydrogen_names, anchors)
+
+    Adds a hydrogen building rule as defined in 
+    `Gromacs Manual <http://www.gromacs.org/Documentation/Manual>`_ 
+    
+    :param number:      :class:`int` number of hydrogens to be added
+    :param method:      :class:`int` gromacs adding rule
+    :param hydrogen_names:  :class:`list` of strings containing the hydrogen names
+    :param anchors:     :class:`list` of strings containing atom names used as anchor
+
+
+.. class:: HeuristicHydrogenConstructor
+
+  As soon as we leave the well defined world of gromacs residue definitions,
+  we have to find new ways for constructing hydrogens. The 
+  :class:`HeuristicHydrogenConstructor` takes a :class:`BuildingBlock` at
+  initialization and builds heuristic rules to build hydrogens based on 
+  the connecticity defined in the given block.
+
+  .. method:: ApplyOnBuildingBlock(block)
+
+    Guess what it does: !!ABSOLUTELY NOTHING!! just there for consistency
+
+    :param block:       :class:`BuildingBlock` block that won't be changed at all!
+                                               Isn't that awesome?
+
+  .. method:: ApplyOnResidue(residue)
+
+    Constructs hydrogen based on heuristic rules
+
+    :param residue:     :class:`ResidueHandle` to be modified
+

modules/mol/mm/doc/forcefield.rst

+Forcefields
+================================================================================
+
+.. currentmodule:: ost.mol
+
+The forcefields are a dump for interactions with their parameters, but also
+for atom specific information or residue definitions in form of a :class:`BuildingBlock`.
+They're also involved in the naming mess we're observing in the molecular mechanics
+community and contain definable renaming rules, that can be applied on an
+:class:`EntityHandle` for renaming from e.g. PDB standard to the forcefield
+specific standard. The standard forcefields in OpenStructure are loaded from
+the files provided by GROMACS and the "standard" naming is therefore the same.
+This has implications for controlling the protonation states for histidine.
+If you for example want to enforce a d-protonated histidine you have to name
+it HISD. Further reading can be found in the 
+`Gromacs Manual <http://www.gromacs.org/Documentation/Manual>`_ 
+
+Loading the standard forcefields provided by OpenStructure
+--------------------------------------------------------------------------------
+
+.. function:: LoadCHARMMForcefield()
+
+   Loads the CHARMM27 forcefield read from GROMACS
+   
+   :returns: The loaded :class:`Forcefield`
+
+
+.. function:: LoadAMBERForcefield()
+
+   Loads the AMBER03 forcefield read from GROMACS
+   
+   :returns: The loaded :class:`Forcefield`
+
+
+Reading forcefields
+--------------------------------------------------------------------------------
+The :class:`FFReader` object is rather experimental. It has nevertheless been 
+thoroughly tested for loading the CHARMM and AMBER forcefields in the
+gromacs format. The reader is capable of resolving the preprocessor statements
+as they are used in GROMACS.
+
+
+.. class:: FFReader
+
+  .. method:: ReadGromacsForcefield()
+
+    Searches and reads the forcefield.itp and atomtypes.atp files 
+    in the base_dir given at initialization. All atom specific informations
+    and bonded as well as nonbonded forces are read this way.
+
+  .. method:: ReadResidueDatabase(basename)
+
+    Searches and reads all files belonging the the residue database
+    defined by basename. With basename aminoacids this function
+    searches and reads all files in the base_dir matching aminoacids.x
+    where x is .rtp .arn .hdb .n.tdb .c.tdb .vsd .r2b
+    Only the rtp file is mandatory, all others are neglected if not present.
+
+    :param basename:    :class:`str` basename of residue database to be loaded
+
+  .. method:: ReadITP(basename)
+
+    Searches and reads the itp file in the base_dir. basename amazing_ion
+    would therefore load the file amazing_ion.itp
+
+    :param basename:    :class:`str` basename of itp file to be loaded
+
+  .. method:: SetForcefield(forcefield)
+
+    Resets reader internal forcefield. Everything read so far is lost.
+
+    :param forcefield:  :class:`Forcefield`
+
+  .. method:: GetForcefield()
+
+    Get the forcefield with everything read so far.
+
+    :returns: The reader internal :class:`Forcefield` 
+
+
+
+
+  .. code-block:: python
+    
+    path = "path_to_gromacs/share/top/charmm27.ff"
+    reader = FFReader(path)
+
+    #read in the data given in forcefield.itp and atomtypes.atp
+    reader.ReadGromacsForcefield()
+
+    #we also want to read several residue databases
+    reader.Read("aminoacids")
+    reader.Read("rna")
+    reader.Read("dna")
+
+    #ions and water are also nice to have, they're stored in itp files
+    reader.ReadITP("tip3p")
+    reader.ReadITP("ions")
+
+    #let's finally get the reader internal forcefield out
+    ff = reader.GetForcefield()
+
+    #there is also an amazing ion definition in some other directory
+    new_reader = FFReader("path/to/directory/with/itp/files")
+
+    #we want to modify the previously read forcefield
+    new_reader.SetForcefield(ff)
+
+    #and read the amazing ion definition from an itp file
+    #note, that any previously defined preprocessor statements
+    #from the previous reader are lost 
+    new_reader.ReadITP("amazing_ion")
+
+    #the new forcefield finally contains everything we need, lets
+    #extract it and save it down
+    ff = new_reader.GetForcefield()
+    ff.Save("charmm_forcefield.dat")
+
+
+.. class:: Forcefield
+
+
+  .. method:: Save(filename)
+
+    dumps forcefield into a binary file on disk
+
+    :param filename:    :class:`str` 
+
+
+
+  .. method:: Load(filename)
+
+    reads in binary forcefield file
+
+    :param filename:    :class:`str`
+
+    :returns:           loaded :class:`Forcefield`
+
+    :raises:            :class:`RuntimeError` when file can't be found
+
+
+
+  .. method:: AddBond(bond)
+
+    :param bond:        :class:`Interaction`
+
+    :raises:            :class:`RuntimeError` when given interaction has
+                                              no bond specific FuncType
+
+
+
+  .. method:: AddAngle(angle)
+
+    :param angle:       :class:`Interaction`
+
+    :raises:            :class:`RuntimeError` when given interaction has
+                                              no angle specific FuncType
+
+
+  .. method:: AddDihedral(dihedral)
+
+    :param dihedral:    :class:`Interaction`
+
+    :raises:            :class:`RuntimeError` when given interaction has
+                                              no dihedral specific FuncType
+
+
+  .. method:: AddImproper(improper)
+
+    :param improper:    :class:`Interaction`
+
+    :raises:            :class:`RuntimeError` when given interaction has
+                                              no improper specific FuncType
+
+
+  .. method:: AddCMap(cmap)
+
+    :param cmap:        :class:`Interaction`
+
+    :raises:            :class:`RuntimeError` when given interaction has
+                                              no cmap specific FuncType
+
+
+  .. method:: AddImplicitGenborn(gb)
+
+    :param gb:          :class:`Interaction`
+
+    :raises:            :class:`RuntimeError` when given interaction has
+                                              no gb specific FuncType
+
+
+  .. method:: AddLJ(lj)
+
+    :param lj:          :class:`Interaction`
+
+    :raises:            :class:`RuntimeError` when given interaction has
+                                              no lj specific FuncType
+
+
+  .. method:: AddLJPair(lj_pair)
+
+    :param lj_pair:     :class:`Interaction`
+
+    :raises:            :class:`RuntimeError` when given interaction has
+                                              no lj_pair specific FuncType
+
+
+  .. method:: AddConstraint(constraint)
+
+    :param constraint:  :class:`Interaction`
+
+    :raises:            :class:`RuntimeError` when given interaction has
+                                              no constraint specific FuncType
+
+
+  .. method:: AddMass(type, mass)
+
+    :param type:        :class:`str` type of atom
+    :param mass:        :class:`float` its mass
+
+
+  .. method:: SetFudgeLJ(factor)
+
+    :param factor:      :class:`float` factor with which the 1,4 lennard jones term
+                                       should be damped
+
+
+  .. method:: SetFudgeQQ(factor)
+
+    :param factor:      :class:`float` factor with which the 1,4 electrostatic term
+                                       should be damped
+
+
+  .. method:: SetGenPairs(gen_pairs)
+
+    :param gen_pairs:   :class:`bool` if set to false, all 1,4 interactions must be set
+                                      with AddLJPair. The Lorentz-Berthelot rule gets
+                                      used otherwise. 
+
+
+  .. method:: AddResidueRenamingRule(name, ff_main_name, ff_n_ter_name, 
+                                     ff_c_ter_name, ff_two_ter_name)
+
+    :param name:        :class:`str` original name or the residue 
+                                     (e.g. pdb/gromacs standard)
+
+    :param ff_main_name: :class:`str` forcefield specific residue name
+
+    :param ff_n_ter_name: :class:`str` forcefield specific name if the residue
+                                       is N-Terminal
+
+    :param ff_c_ter_name: :class:`str` forcefield specific name if the residue
+                                       is C-Terminal
+
+    :param ff_two_ter_name: :class:`str` forcefield specific name if the residue
+                                         is N- and C_Terminal
+
+
+
+  .. method:: AddAtomRenamingRule(res_name, old_atom_name, new_atom_name)
+
+    :param res_name:    :class:`str` forcefield specific residue name the
+                                     atom is belonging to
+
+    :param old_atom_name: :class:`str` atom name in pdb/gromacs standard
+
+    :param new_atom_name: :class:`str` ff specific atom name
+
+
+  .. method:: AddBuildingBlock(name, block)
+
+    :param name:        :class:`str` name of residue this :class:`BuildingBlock` 
+                                     is supposed to be related
+
+    :param block:       :class:`BuildingBlock`
+
+
+  .. method:: AddHydrogenConstructor(name, h_constructor)
+
+    :param name:        :class:`str` name of residue this 
+                                     :class:`HydrogenConstructor` 
+                                     is supposed to be related
+
+    :param h_constructor:       :class:`HydrogenConstructor`
+
+
+  .. method:: AddBlockModifier(name, modifier)
+
+    :param name:        :class:`str` name of residue this 
+                                     :class:`BlockModifier` 
+                                     is supposed to be related
+
+    :param modifier:       :class:`BlockModifier`
+
+
+  .. method:: SetStandardCTer(res_name, ter_name)
+
+    Setting a standard CTer incluences the behaviour of the GetCTerModifier 
+    function. If no specific block modifier is defined there, this is the
+    one that gets returned.
+
+    :param res_name:    :class:`str` ff specific residue name this block 
+                                     modifier is supposed to be related
+
+    :param ter_name:    :class:`str` name of the default c-terminal block 
+                                     modifier for this residue
+
+
+  .. method:: SetStandardNTer(res_name, ter_name)
+
+    Setting a standard NTer incluences the behaviour of the GetNTerModifier 
+    function. If no specific block modifier is defined there, this is the
+    one that gets returned.
+
+    :param res_name:    :class:`str` ff specific residue name this block 
+                                     modifier is supposed to be related
+
+    :param ter_name:    :class:`str` name of the default n-terminal block 
+                                     modifier for this residue
+
+
+  .. method:: AssignFFSpecificNames(ent, reverse = False)
+
+    This function does the forcefield specific renaming magic. It takes
+    the given :class:`EntityHandle` and applies the rules set in
+    AddResidueRenamingRule and AddAtomRenamingRule.
+
+    :param ent:         :class:`EntityHandle`
+
+    :param reverse:     :class:`bool` If False, the function does the renaming
+                                      from pdb/gromacs naming to the forcefield
+                                      specific naming.
+                                      If True, the opposite happens.
+
+
+  .. method:: GetBond(type1, type2)
+
+    :param type1:       :class:`str`
+
+    :param type2:       :class:`str`
+
+    :returns: an :class:`Interaction` with a bond FuncType
+
+    :raises:            :class:`RuntimeError` when no :class:`Interaction`
+                                              matching given types can be found
+
+
+  .. method:: GetAngle(type1, type2, type3)
+
+    :param type1:       :class:`str`
+
+    :param type2:       :class:`str`
+
+    :param type3:       :class:`str`
+
+    :returns: an :class:`Interaction` with a angle FuncType
+
+    :raises:            :class:`RuntimeError` when no :class:`Interaction`
+                                              matching given types can be found
+
+
+  .. method:: GetDihedrals(type1, type2, type3, type4)
+
+    Several dihedral definitions can be merged to one dihedral function.
+    This function therefore returns a list. 
+    In a first step all dihedrals matching the given types are gathered
+    and returned.
+    If No dihedrals could be found, the search continues by including
+    wildcard characters in the atom types (X). All found dihedrals
+    matching with all possible combinations of wildcards are then gathered
+    and returned.
+
+    :param type1:       :class:`str`
+
+    :param type2:       :class:`str`
+
+    :param type3:       :class:`str`
+
+    :param type4:       :class:`str`
+
+    :returns: a :class:`list` of :class:`Interaction` objects with dihedral 
+              FuncType matching given types
+
+    :raises:            :class:`RuntimeError` when no :class:`Interaction`
+                                              matching given types can be found
+
+
+
+  .. method:: GetImpropers(type1, type2, type3, type4)
+
+    The same search strategy as in GetDihedrals is used to extract 
+    the impropers.
+
+    :param type1:       :class:`str`
+
+    :param type2:       :class:`str`
+
+    :param type3:       :class:`str`
+
+    :param type4:       :class:`str`
+
+    :returns: a :class:`list` of :class:`Interaction` objects with improper
+              FuncType matching given types
+
+    :raises:            :class:`RuntimeError` when no :class:`Interaction`
+                                              matching given types can be found
+
+
+  .. method:: GetCMap(type1, type2, type3, type4, type5)
+
+    :param type1:       :class:`str`
+
+    :param type2:       :class:`str`
+
+    :param type3:       :class:`str`
+
+    :param type4:       :class:`str`
+
+    :param type5:       :class:`str`
+
+    :returns: an :class:`Interaction` with a cmap FuncType
+
+    :raises:            :class:`RuntimeError` when no :class:`Interaction`
+                                              matching given types can be found
+
+
+  .. method:: GetImplicitGenborn(type)
+
+    :param type:       :class:`str`
+
+    :returns: an :class:`Interaction` with a gb FuncType
+
+    :raises:            :class:`RuntimeError` when no :class:`Interaction`
+                                              matching given type can be found
+
+
+  .. method:: GetLJ(type)
+
+    :param type:       :class:`str`
+
+    :returns: an :class:`Interaction` with a lj FuncType
+
+    :raises:            :class:`RuntimeError` when no :class:`Interaction`
+                                              matching given type can be found
+
+
+  .. method:: GetLJ(type1, type2, pair=False)
+
+    :param type1:        :class:`str`
+
+    :param type2:        :class:`str`
+
+    :param pair:         :class:`bool` If set to true, the interaction is
+                                       assumed to be a 1,4-interaction and
+                                       the set lj_pairs are first searched
+                                       for matches. In case of no success,
+                                       the function uses the Lorentz-Berthelot
+                                       rule to combine the sigma and epsilon 
+                                       parameters.
+                                       If set to false, the Lorentz-Berthelot
+                                       rule is applied directly.
+
+    :raises:            :class:`RuntimeError` when no :class:`Interaction`
+                                              matching given types can be found
+                                              or when pair is true and no 
+                                              appropriate lj_pair is set.
+
+
+  .. method:: GetConstraint(type1, type2)
+
+    :param type1:       :class:`str`
+
+    :param type2:       :class:`str`
+
+    :returns: an :class:`Interaction` with a constraint FuncType
+
+    :raises:            :class:`RuntimeError` when no :class:`Interaction`
+                                              matching given types can be found
+
+
+  .. method:: GetMass(type)
+
+    :param type:        :class:`str`
+
+    :returns: the mass
+
+    :raises:            :class:`RuntimeError` no mass has been set for this 
+                        atom type has been set
+
+
+  .. method:: GetFudgeLJ()
+
+    :returns:  :class:`float` factor with which the 1,4 lennard jones term
+               should be damped
+
+  .. method:: GetFudgeQQ()
+
+    :returns:  :class:`float` factor with which the 1,4 lennard jones term
+               should be damped
+
+
+  .. method:: GetAtomType(res_name, atom_name)
+
+    :param res_name:    :class:`str` forcefield specific residue name
+
+    :param atom_name:  :class:`str` forcefield specific atom name belonging
+                                     to that residue
+
+    :returns:  atom type
+
+    :raises:            :class:`RuntimeError` if forcefield has no such
+                        :class:`BuildingBlock` or when atom is not present 
+                        in that :class:`BuildingBlock`   
+
+
+
+  .. method:: GetHydrogenConstructor(res_name)
+
+    :param res_name:    :class:`str`
+
+    :returns: :class:`HydrogenConstructor` for this name, invalid if it can't
+              be found
+
+
+  .. method:: GetBuildingBlock(res_name)
+
+    :param res_name:    :class:`str`
+
+    :returns:  :class:`BuildingBlock` for this name, invalid if it can't be 
+               found
+
+
+  .. method:: GetBlockModifier(res_name)
+
+    :param res_name:    :class:`str`
+
+    :returns: :class:`BlockModifier` for this name, invalid if it can't
+              be found
+
+
+  .. method:: GetNTerModifier(res_name, ter_name="")
+
+    :param res_name:    :class:`str`
+
+    :param ter_name:    :class:`str` if not set, the ter_name
+                        defined by SetStandardNTer gets used
+
+    :returns: :class:`BlockModifier` for this name, invalid if it can't
+              be found
+
+
+  .. method:: GetCTerModifier(name, ter_name="")
+
+    :param res_name:    :class:`str`
+
+    :param ter_name:    :class:`str` if not set, the ter_name
+                        defined by SetStandardCTer gets used
+
+    :returns: :class:`BlockModifier` for this name, invalid if it can't
+              be found
+
+
+
+
+    

modules/mol/mm/doc/interaction.rst

+Interactions
+================================================================================
+
+.. currentmodule:: ost.mol.mm
+
+The interaction object is intended to build a basic container tat can be used
+in various scenarios. At the initialization a FuncType has to be defined.
+Whenever names, types or parameters are set, the number of parameters
+gets checked according to the FuncType. A name or type can also consist of
+a wildcard expressed as X.
+
+
+The FuncType enum
+--------------------------------------------------------------------------------
+
+Every Interaction is linked to one particular *FuncType* describing the types 
+of interactions supported by OpenStructure. There are a 15 possible values with
+Invalid defining an unknown interaction:
+
+  HarmonicBond, HarmonicAngle, UreyBradleyAngle, PeriodicDihedral, 
+  PeriodicImproper, HarmonicImproper, CMap, LJ, LJPair, GBSA, 
+  DistanceConstraint, Exclusion, HarmonicPositionRestraint,
+  HarmonicPositionRestraint, Invalid
+
+The implementation guarantees, that the parameter related to atom types,
+names, parameters are checked regarding their dimension (e.g. 3 atoms for
+a harmonic angle) 
+
+--------------------------------------------------------------------------------
+
+
+.. class:: Interaction
+
+  ..method:: SetTypes(types)
+
+    Sets the forcefield specific atom types.
+
+    :param types:   A list of strings describing the force field specific atom
+                    types.
+
+    :type types:    :class:`list`
+
+    :raises: :exc:` RuntimeError` when size of input is not consistent with
+                                  the interactions functype
+
+
+  ..method:: SetNames(names)
+
+    Sets atom names.
+
+    :param types:   A list of strings describing the atom names.
+
+    :type names:    :class:`list`
+
+    :raises: :exc:` RuntimeError` when size of input is not consistent with
+                                  the interactions functype
+
+
+  ..method:: SetParam(names)
+
+    Sets interaction specific parameters.
+
+    :param types:  A list of real values .
+
+    :type names:   :class:`list`
+
+    :raises: :exc:`RuntimeError` when size of input is not consistent with
+                                  the interactions functype
+
+
+  ..method:: GetTypes()
+
+    Get Previously set types
+
+    :returns:      :class:`list`
+
+
+
+  ..method:: GetNames()
+
+    Get Previously set names
+
+    :returns:      :class:`list`
+
+
+  ..method:: GetParam()
+
+    Get Previously set parameters
+
+    :returns:      :wtf:`bool`
+
+
+  ..method:: GetAtoms(residue)
+
+    Returns an AtomHandleList containing the atoms in residue matching
+    the atom names
+
+    :param residue :class:`~mol.ResidueHandle`
+    :returns:      :class:`~mol.AtomHandleList`
+    :raises: :exc:`RuntimeError` when atom cannot be found in residue
+
+
+  ..method:: GetFuncType()
+
+    Returns the functype enum of the interaction
+
+    :returns:      :enum:`~mol.mm.FuncType`  
+
+
+  ..method:: ReplaceAtom(name, new_name, new_type)
+
+    Searches for given atom name. If found, this particular atom name
+    gets changed to new_name. If the atom types are set as well, the
+    associated atom type gets also reset to new_type.
+
+    :param name    :class:`string`
+    :param new_name:class:`string`
+    :param new_type:class:`string`
+    :returns:      :wtf:`bool` whether replacement was successful or not
+
+
+  ..method::MatchTypes(atom_types)
+
+    Checks, whether the given types match the internal types. The match
+    can be "as is" or in reversed order
+
+    :param atom_types    :class:`list`
+    :returns:     `:wtf:`bool`
+
+
+  ..method::MatchNames(atom_names)
+
+    Checks, whether the given names match the internal names. The match
+    can be "as is" or in reversed order
+
+    :param atom_names    :class:`list`
+    :returns:     `:wtf:`bool`
+
+
+  ..method::HasName(name)
+
+    Checks, whether the given name is present in the internal names
+
+    :param name    :class:`string`
+    :returns:      :wtf:`bool`
+
+
+  ..method::HasType(type)
+
+    Checks, whether the given type is present in the internal types
+
+    :param type    :class:`string`
+    :returns:      :wtf:`bool`
+
+
+  ..IsParametrized()
+
+    Checks, whether the parameters have been set
+
+    :returns:      :wtf:`bool`
+
+
+  ..HasTypeWildcard()
+
+    Checks, whether one of the types is a wildcard (X)
+
+    :returns:      :wtf:`bool`
+
+
+  ..HasNameWildcard()
+
+    Checks, whether one of the names is a wildcard (X)
+
+    :returns:      :wtf:`bool`