Forcefields¶
The forcefields are a dump for interactions with their parameters, but also
for atom specific information or residue definitions in the form of a
BuildingBlock
. Objects for modifying residues can be set in form of
BlockModifier
or HydrogenConstructor
.
They’re also involved in dealing with the naming mess we’re observing in the molecular mechanics
community and contain definable renaming rules that can be applied on an
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 e.g. want to enforce a d-protonated histidine you have to name
it HISD. Further reading can be found in the
Gromacs Manual
Loading the standard forcefields provided by OpenStructure¶
-
LoadCHARMMForcefield
()¶ Loads the CHARMM27 forcefield read from Gromacs
Returns: The loaded Forcefield
-
LoadAMBERForcefield
()¶ Loads the AMBER03 forcefield read from Gromacs
Returns: The loaded Forcefield
Reading forcefields¶
The 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
(base_dir)¶ Parameters: base_dir ( str
) – Base path of the reader. All loaded files must be defined relative to this base path.The
FFReader
builds up aForcefield
, that gets updated with every call to the read functions. If the read files contain preprocessor statements as they are used in Gromacs, they will be applied to all subsequent lines read in. Parsed preprocessor statements are: #include, #define, #ifdef, #ifndef, #else and #endif-
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.
-
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.
Parameters: basename ( str
) – Basename of residue database to be loaded
-
ReadITP
(basename)¶ Searches and reads the itp file in the base_dir. basename=amazing_ion would therefore load the file amazing_ion.itp
Parameters: basename ( str
) – Basename of itp file to be loaded
-
SetForcefield
(forcefield)¶ Resets reader internal forcefield. Everything read so far is lost, except the already read preprocessor statements.
Parameters: forcefield ( Forcefield
) – Forcefield to be set
-
GetForcefield
()¶ Get the forcefield with everything read so far.
Returns: The reader internal Forcefield
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")
-
The Forcefield Class¶
-
class
Forcefield
¶ -
Save
(filename)¶ Dumps forcefield into a binary file on disk
Parameters: filename ( str
) – Filename of the saved forcefield
-
Load
(filename)¶ reads in binary forcefield file
Parameters: filename ( str
) – Filename of the forcefield to be loadedReturns: loaded Forcefield
Raises: RuntimeError
when filename can’t be found
-
AddBond
(bond)¶ Parameters: bond ( Interaction
) – Bond to be addedRaises: RuntimeError
when given interaction has no bond specific FuncType
-
AddAngle
(angle)¶ Parameters: angle ( Interaction
) – Angle to be addedRaises: RuntimeError
when given interaction has no angle specific FuncType
-
AddDihedral
(dihedral)¶ Parameters: dihedral ( Interaction
) – Dihedral to be addedRaises: RuntimeError
when given interaction has no dihedral specific FuncType
-
AddImproper
(improper)¶ Parameters: improper ( Interaction
) – Improper to be addedRaises: RuntimeError
when given interaction has no improper specific FuncType
-
AddCMap
(cmap)¶ Parameters: cmap ( Interaction
) – CMap to be addedRaises: RuntimeError
when given interaction has no cmap specific FuncType
-
AddImplicitGenborn
(gb)¶ Parameters: gb ( Interaction
) – GB to be addedRaises: RuntimeError
when given interaction has no gb specific FuncType
-
AddLJ
(lj)¶ Parameters: lj ( Interaction
) – LJ to be addedRaises: RuntimeError
when given interaction has no lj specific FuncType
-
AddLJPair
(lj_pair)¶ Parameters: lj_pair ( Interaction
) – LJPair to be addedRaises: RuntimeError
when given interaction has no lj_pair specific FuncType
-
AddConstraint
(constraint)¶ Parameters: constraint ( Interaction
) – Constraint to be addedRaises: RuntimeError
when given interaction has no constraint specific FuncType
-
AddMass
(type, mass)¶ Parameters: - type (
str
) – Type of atom - mass (
float
) – Its mass
- type (
-
SetFudgeLJ
(factor)¶ Parameters: factor ( float
) – Factor with which the 1,4 Lennard Jones term should be dampened
-
SetFudgeQQ
(factor)¶ Parameters: factor ( float
) – Factor with which the 1,4 electrostatic term should be dampened
-
SetGenPairs
(gen_pairs)¶ Parameters: gen_pairs ( bool
) – If set to false, all 1,4 interactions must be set with AddLJPair. The Lorentz-Berthelot rule gets used otherwise.
-
AddResidueRenamingRule
(name, ff_main_name, ff_n_ter_name, ff_c_ter_name, ff_two_ter_name)¶ Parameters: - name (
str
) – Original name of the residue (e.g. PDB/Gromacs standard) - ff_main_name (
str
) – Forcefield specific residue name - ff_n_ter_name (
str
) – Forcefield specific name if the residue is N-Terminal - ff_c_ter_name (
str
) – Forcefield specific name if the residue is C-Terminal - ff_two_ter_name (
str
) – Forcefield specific name if the residue is N- and C-Terminal
- name (
-
AddAtomRenamingRule
(res_name, old_atom_name, new_atom_name)¶ Parameters: - res_name (
str
) – Forcefield specific name of the residue the atom belongs to - old_atom_name (
str
) – Atom name in PDB/Gromacs standard - new_atom_name (
str
) – FF specific atom name
- res_name (
-
AddBuildingBlock
(name, block)¶ Parameters: - name (
str
) – Name of residue thisBuildingBlock
is supposed to be related to - block (
BuildingBlock
) – BuildingBlock to be added
- name (
-
AddHydrogenConstructor
(name, h_constructor)¶ Parameters: - name (
str
) – Name of residue thisHydrogenConstructor
is supposed to be related to - h_constructor (
HydrogenConstructor
) – HydrogenConstructor to be added
- name (
-
AddBlockModifier
(name, modifier)¶ Parameters: - name (
str
) – Name of residue thisBlockModifier
is supposed to be related to - modifier (
BlockModifier
) – BlockModifier to be added
- name (
-
SetStandardCTer
(res_name, ter_name)¶ Setting a standard CTer influences the behaviour of the GetCTerModifier function. If no specific block modifier is defined there, this is the one that gets returned.
Parameters: - res_name (
str
) – Forcefield specific residue name this block modifier is supposed to be related to - ter_name (
str
) – Name of the default c-terminal block modifier for this residue
- res_name (
-
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.
Parameters: - res_name (
str
) – Forcefield specific residue name this block modifier is supposed to be related to - ter_name (
str
) – Name of the default n-terminal block modifier for this residue
- res_name (
-
AssignFFSpecificNames
(ent[, reverse = False])¶ This function does the forcefield specific renaming magic. It takes the given
EntityHandle
and applies the rules set in AddResidueRenamingRule and AddAtomRenamingRule.Parameters: - ent (
EntityHandle
) – Entity to be renamed - reverse (
bool
) – If False, the function does the renaming from PDB/Gromacs naming to the forcefield specific naming. If True, the opposite happens.
- ent (
-
GetBond
(type1, type2)¶ Parameters: - type1 (
str
) – Type of interacting particle 1 - type2 (
str
) – Type of interacting particle 2
Returns: an
Interaction
with a bond FuncTypeRaises: RuntimeError
when noInteraction
matching given types can be found- type1 (
-
GetAngle
(type1, type2, type3)¶ Parameters: - type1 (
str
) – Type of interacting particle 1 - type2 (
str
) – Type of interacting particle 2 - type3 (
str
) – Type of interacting particle 3
Returns: an
Interaction
with a angle FuncTypeRaises: RuntimeError
when noInteraction
matching given types can be found- type1 (
-
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 can 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.
Parameters: - type1 (
str
) – Type of interacting particle 1 - type2 (
str
) – Type of interacting particle 2 - type3 (
str
) – Type of interacting particle 3 - type4 (
str
) – Type of interacting particle 4
Returns: a
list
ofInteraction
objects with dihedral FuncType matching given typesRaises: RuntimeError
when noInteraction
matching given types can be found- type1 (
-
GetImpropers
(type1, type2, type3, type4)¶ The same search strategy as in GetDihedrals is used to extract the impropers.
Parameters: - type1 (
str
) – Type of interacting particle 1 - type2 (
str
) – Type of interacting particle 2 - type3 (
str
) – Type of interacting particle 3 - type4 (
str
) – Type of interacting particle 4
Returns: a
list
ofInteraction
objects with improper FuncType matching given typesRaises: RuntimeError
when noInteraction
matching given types can be found- type1 (
-
GetCMap
(type1, type2, type3, type4, type5)¶ Parameters: - type1 (
str
) – Type of interacting particle 1 - type2 (
str
) – Type of interacting particle 2 - type3 (
str
) – Type of interacting particle 3 - type4 (
str
) – Type of interacting particle 4 - type5 (
str
) – Type of interacting particle 5
Returns: an
Interaction
with a cmap FuncTypeRaises: RuntimeError
when noInteraction
matching given types can be found- type1 (
-
GetImplicitGenborn
(type)¶ Parameters: type ( str
) – Type of particleReturns: an Interaction
with a gb FuncTypeRaises: RuntimeError
when noInteraction
matching given type can be found
-
GetLJ
(type)¶ Parameters: type ( str
) – Type of particleReturns: an Interaction
with a lj FuncTypeRaises: RuntimeError
when noInteraction
matching given type can be found
-
GetLJ
(type1, type2[, pair=False]) Parameters: - type1 (
str
) – Type of interacting particle 1 - type2 (
str
) – Type of interacting particle 2 - pair (
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: RuntimeError
when noInteraction
matching given types can be found or when pair is true and no appropriate lj_pair is set despite gen_pair flag being false.- type1 (
-
GetConstraint
(type1, type2)¶ Parameters: - type1 (
str
) – Type of interacting particle 1 - type2 (
str
) – Type of interacting particle 2
Returns: an
Interaction
with a constraint FuncTypeRaises: RuntimeError
when noInteraction
matching given types can be found- type1 (
-
GetMass
(type)¶ Parameters: type ( str
) – Type of particleReturns: float
- the massRaises: RuntimeError
if no mass has been set for this atom type
-
GetFudgeLJ
()¶ Returns: float
- Factor with which the 1,4 Lennard Jones term should be dampened
-
GetFudgeQQ
()¶ Returns: float
- Factor with which the 1,4 electrostatic term should be dampened
-
GetAtomType
(res_name, atom_name)¶ Parameters: - res_name (
str
) – Forcefield specific residue name - atom_name (
str
) – Forcefield specific atom name belonging to that residue
Returns: str
- atom typeRaises: RuntimeError
if forcefield has no suchBuildingBlock
or when atom is not present in thatBuildingBlock
- res_name (
-
GetHydrogenConstructor
(res_name)¶ Parameters: res_name ( str
) – Name of residueReturns: HydrogenConstructor
for this name, invalid if it can’t be found
-
GetBuildingBlock
(res_name)¶ Parameters: res_name ( str
) – Name of residueReturns: BuildingBlock
for this name, invalid if it can’t be found
-
GetBlockModifier
(res_name)¶ Parameters: res_name ( str
) – Name of residueReturns: BlockModifier
for this name, invalid if it can’t be found
-
GetNTerModifier
(res_name[, ter_name=""])¶ Parameters: - res_name (
str
) – Name of residue - ter_name (
str
) – If not set, the ter_name defined by SetStandardNTer gets used
Returns: BlockModifier
for this name, invalid if it can’t be found- res_name (
-
GetCTerModifier
(name[, ter_name=""])¶ Parameters: - res_name (
str
) – Name of residue - ter_name (
str
) – If not set, the ter_name defined by SetStandardCTer gets used
Returns: BlockModifier
for this name, invalid if it can’t be found- res_name (
-