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
-
LoadAMBERForcefield()
Loads the AMBER03 forcefield read from Gromacs
Reading forcefields
-
class
FFReader(base_dir)
The FFReader builds up a Forcefield, 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
Note that this class 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.
| Parameters: | base_dir (str) – Base path of the reader.
All loaded files must be defined relative to this base
path. |
|---|
-
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.
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.ReadResidueDatabase("aminoacids")
reader.ReadResidueDatabase("rna")
reader.ReadResidueDatabase("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")
Generating forcefields with Antechamber
The antechamber submodule of mol.mm defines functions to use Antechamber (from
AmberTools) to automatically generate force field parameters and load the
results into Forcefield objects.
Example usage:
from ost.mol import mm
# create parameters for RVP using PDB's component dictionary
mm.antechamber.RunAntechamber('RVP', 'components.cif', base_out_dir='ligands')
# create force field
ff = mm.Forcefield()
ff = mm.antechamber.AddFromPath(ff, 'ligands/RVP')
# equivalent: ff = mm.antechamber.AddFromFiles(ff, 'ligands/RVP/frcmod',
# 'ligands/RVP/out.mpdb')
# since Antechamber cannot deal with ions, you can do it manually
ff = mm.antechamber.AddIon(ff, 'CL', 'CL', 35.45, -1.0, 0.4401, 0.4184)
# save it
ff.Save('ligands/ff.dat')
Functions:
-
RunAntechamber(res_name, filename, format='ccif', amberhome=None, base_out_dir=None)
Run Antechamber to guess force field parameters for a given residue name.
This requires an installation of AmberTools (tested with AmberTools15) with
binaries antechamber and parmchk2.
This has the same restrictions as Antechamber itself and we assume the input
to be uncharged. Note that Antechamber cannot deal with metal ions and other
non-organic elements.
The results are stored in a separate folder named res_name within
base_out_dir (if given, otherwise the current working directory). The main
output files are frcmod and out.mpdb. The former contains force field
parameters and masses. The latter maps atom names to atom types and defines
the partial charges. The same output could be obtained as follows:
$ antechamber -i <FILENAME> -fi <FORMAT> -bk '<RES_NAME>' -o out.mol2 -fo mol2 -c bcc -pf yes
$ parmchk2 -i out.mol2 -f mol2 -o frcmod -a Y
$ antechamber -i out.mol2 -fi mol2 -o out.mpdb -fo mpdb -pf yes
The force field parameters can be manually modified if needed. It can for
instance happen that some parameters cannot be identified. Those lines will
be marked with a comment “ATTN, need revision”.
| Parameters: |
- res_name (
str) – Residue name for which we desire force field parameters.
- filename (
str) – Path to a file which contains the necessary information for
res_name. It must include all hydrogens.
- format (
str) – Format of file given with filename. Common formats are ‘ccif’
for PDB’s component dictionary or ‘pdb’ for a PDB file
containing the desired residue with all hydrogens.
- amberhome (
str) – Base path of your AmberTools installation. If not None,
we look for antechamber and parmchk2 within
AMBERHOME/bin additionally to the system’s PATH.
- base_out_dir (
str) – Path to a base path, where the output will be stored.
If None, the current working directory is used.
|
|---|
-
AddFromFiles(force_field, frcmod_filename, mpdb_filename)
Add data from a frcmod and an mpdb file to a force field.
This will add a new BuildingBlock to force_field for
the residue defined in those files (residue name is extracted from the mpdb
file which can only contain a single residue). Charges for each atom are
extracted from the mpdb file. According to the frcmod file, an
Interaction is added for each bond, angle, dihedral and
improper. Atom types with masses and non-bonded interactions are added to
force_field as needed.
| Parameters: |
- force_field (
Forcefield) – A force field object to which the new parameters are
added.
- frcmod_filename (
str) – Path to frcmod file as generated by parmchk2.
- mpdb_filename (
str) – Path to mpdb file as generated by antechamber.
|
|---|
| Returns: | The updated force field (same as force_field).
|
|---|
| Return type: | Forcefield
|
|---|
-
AddFromPath(force_field, out_dir)
Add data from a directory created with Run() to a force field.
See AddFromFiles() for details.
| Parameters: |
- force_field (
Forcefield) – A force field object to which the new parameters are
added.
- out_dir (
str) – Output directory as created with Run(). Must contain
files frcmod and out.mpdb.
|
|---|
| Returns: | The updated force field (same as force_field).
|
|---|
| Return type: | Forcefield
|
|---|
-
AddIon(force_field, res_name, atom_name, atom_mass, atom_charge, lj_sigma, lj_epsilon)
Add a single atom as an ion to a force field.
Since Antechamber cannot deal with ions, you can add simple ones easily with
this function. This adds a BuildingBlock to force_field
for the given residue name containing a single atom. The atom will have a type
with the same name as the atom name and the given mass, charge and non-bonded
(LJ) interaction parameters.
| Parameters: |
- force_field (
Forcefield) – A force field object to which the ion is added.
- res_name (
str) – Residue name for the ion to be added.
- atom_name (
str) – Atom name which is also used as atom type name.
- atom_mass (
float) – Mass of the atom.
- atom_charge (
float) – Charge of the atom.
- lj_sigma (
float in nm) – The sigma parameter for the non-bonded LJ interaction.
- lj_epsilon (
float in kJ/mol) – The sigma parameter for the non-bonded LJ interaction.
|
|---|
The Forcefield Class
-
class
Forcefield
-
Save(filename)
Dumps forcefield into a binary file on disk
| Parameters: | filename (str) – Filename of the saved forcefield |
|---|
-
static
Load(filename)
reads in binary forcefield file
| Parameters: | filename (str) – Filename of the forcefield to be loaded |
|---|
| Returns: | loaded Forcefield |
|---|
| Raises: | RuntimeError when filename can’t be found |
|---|
-
AddBond(bond)
| Parameters: | bond (Interaction) – Bond to be added |
|---|
| Raises: | RuntimeError when given interaction has
no bond specific FuncType |
|---|
-
AddAngle(angle)
| Parameters: | angle (Interaction) – Angle to be added |
|---|
| Raises: | RuntimeError when given interaction has
no angle specific FuncType |
|---|
-
AddDihedral(dihedral)
| Parameters: | dihedral (Interaction) – Dihedral to be added |
|---|
| Raises: | RuntimeError when given interaction has
no dihedral specific FuncType |
|---|
-
AddImproper(improper)
| Parameters: | improper (Interaction) – Improper to be added |
|---|
| Raises: | RuntimeError when given interaction has
no improper specific FuncType |
|---|
-
AddCMap(cmap)
| Parameters: | cmap (Interaction) – CMap to be added |
|---|
| Raises: | RuntimeError when given interaction has
no cmap specific FuncType |
|---|
-
AddImplicitGenborn(gb)
| Parameters: | gb (Interaction) – GB to be added |
|---|
| Raises: | RuntimeError when given interaction has
no gb specific FuncType |
|---|
-
AddLJ(lj)
| Parameters: | lj (Interaction) – LJ to be added |
|---|
| Raises: | RuntimeError when given interaction has
no lj specific FuncType |
|---|
-
AddLJPair(lj_pair)
| Parameters: | lj_pair (Interaction) – LJPair to be added |
|---|
| Raises: | RuntimeError when given interaction has
no lj_pair specific FuncType |
|---|
-
AddConstraint(constraint)
| Parameters: | constraint (Interaction) – Constraint to be added |
|---|
| Raises: | RuntimeError when given interaction has
no constraint specific FuncType |
|---|
-
AddMass(type, mass)
| Parameters: |
- type (
str) – Type of atom
- mass (
float) – Its mass
|
|---|
-
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
|
|---|
-
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
|
|---|
-
AddBuildingBlock(name, block)
-
-
AddHydrogenConstructor(name, h_constructor)
-
-
AddBlockModifier(name, modifier)
-
-
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
|
|---|
-
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
|
|---|
-
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.
|
|---|
-
GetBond(type1, type2)
| Parameters: |
- type1 (
str) – Type of interacting particle 1
- type2 (
str) – Type of interacting particle 2
|
|---|
| Returns: | an Interaction with a bond FuncType
|
|---|
| Raises: | RuntimeError when no Interaction
matching given types can be found
|
|---|
-
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 FuncType
|
|---|
| Raises: | RuntimeError when no Interaction
matching given types can be found
|
|---|
-
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 of Interaction objects with dihedral
FuncType matching given types
|
|---|
| Raises: | RuntimeError when no Interaction
matching given types can be found
|
|---|
-
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 of Interaction objects with improper
FuncType matching given types
|
|---|
| Raises: | RuntimeError when no Interaction
matching given types can be found
|
|---|
-
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 FuncType
|
|---|
| Raises: | RuntimeError when no Interaction
matching given types can be found
|
|---|
-
GetImplicitGenborn(type)
| Parameters: | type (str) – Type of particle |
|---|
| Returns: | an Interaction with a gb FuncType |
|---|
| Raises: | RuntimeError when no Interaction
matching given type can be found |
|---|
-
GetLJ(type)
| Parameters: | type (str) – Type of particle |
|---|
| Returns: | an Interaction with a lj FuncType |
|---|
| Raises: | RuntimeError when no Interaction
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 no Interaction
matching given types can be found
or when pair is true and no
appropriate lj_pair is set
despite gen_pair flag being false.
|
|---|
-
GetConstraint(type1, type2)
| Parameters: |
- type1 (
str) – Type of interacting particle 1
- type2 (
str) – Type of interacting particle 2
|
|---|
| Returns: | an Interaction with a constraint FuncType
|
|---|
| Raises: | RuntimeError when no Interaction
matching given types can be found
|
|---|
-
GetMass(type)
| Parameters: | type (str) – Type of particle |
|---|
| Returns: | float - the mass |
|---|
| Raises: | 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 type
|
|---|
| Raises: | RuntimeError if forcefield has no such
BuildingBlock or when atom is not present
in that BuildingBlock
|
|---|
-
GetHydrogenConstructor(res_name)
| Parameters: | res_name (str) – Name of residue |
|---|
| Returns: | HydrogenConstructor for this name, invalid if it can’t
be found |
|---|
-
GetBuildingBlock(res_name)
| Parameters: | res_name (str) – Name of residue |
|---|
| Returns: | BuildingBlock for this name, invalid if it can’t be
found |
|---|
-
GetBuildingBlockNames()
| Returns: | list of all building block names present in that
forcefield |
|---|
-
GetBlockModifier(res_name)
| Parameters: | res_name (str) – Name of residue |
|---|
| Returns: | 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
|
|---|
-
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
|
|---|
|
Contents
Search
Enter search terms or a module, class or function name.
Previous topic
Blocks
Next topic
The Molecular Mechanics Settings
You are here
|