Forcefields¶

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¶

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.

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.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)¶

Parameters:	name (str) – Name of residue this BuildingBlock is supposed to be related to block (BuildingBlock) – BuildingBlock to be added

AddHydrogenConstructor(name, h_constructor)¶

Parameters:	name (str) – Name of residue this HydrogenConstructor is supposed to be related to h_constructor (HydrogenConstructor) – HydrogenConstructor to be added

AddBlockModifier(name, modifier)¶

Parameters:	name (str) – Name of residue this BlockModifier is supposed to be related to modifier (BlockModifier) – BlockModifier to be added

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