mstk.forcefield.ForceField

class mstk.forcefield.ForceField

ForceField is a set of FFTerm objects describing the energy function of a Topology with regard to the positions of atoms.

atom_types

All the atom types in this force field. For each key value pair, the value is a AtomType object, the key is the name of the object.

Type:

dict, [str, AtomType]

bci_terms

All the charge increment terms. For each key value pair, the value is a ChargeIncrementTerm object, the key is the name of the object.

Type:

dict, [str, ChargeIncrementTerm]

vdw_terms

vdW terms between same types. For each key value pair, the value is a object of subclass of VdwTerm. the key is the name of the object. The term can be either LJ126Term or MieTerm, as long as it’s a subclass of VdwTerm. Because we are using name of the term as key, there can only be one term to describe the vdW interactions between two atom types. Which means, there cannot be a LJ126Term and a MieTerm with same name in a ForceField. However, you can have LJ126Term for one pair of atom types and MieTerm for another pairs.

Type:

dict, [str, subclass of VdwTerm]

pairwise_vdw_terms

Pairwise vdW terms between unlike types. For each key value pair, the value is a object of subclass of VdwTerm. the key is the name of the object. If a pair of unlike atom types is not included in this dict, then the vdW interactions between this pair will be generated from mixing rule.

Type:

dict, [str, subclass of VdwTerm]

polar_terms

Polarization terms for polarizable atom types. For each key value pair, the value is a object of subclass of PolarTerm. the key is the name of the object. Currently, isotropic Drude model is implemented.

Type:

dict, [str, subclass of PolarTerm]

virtual_site_terms

Virtual site terms for delocalized interaction center. For each key value pair, the value is a object of subclass of VirtualSiteTerm. the key is the name of the object. Currently, TIP4P model is implemented.

Type:

dict, [str, subclass of VirtualSiteTerm]

bond_terms

Bond terms between two atom types. For each key value pair, the value is a object of subclass of BondTerm. the key is the name of the object.

Type:

dict, [str, subclass of BondTerm]

angle_terms

Angle terms between three atom types. For each key value pair, the value is a object of subclass of AngleTerm. the key is the name of the object.

Type:

dict, [str, subclass of AngleTerm]

dihedral_terms

Dihedral terms between four atom types. For each key value pair, the value is a object of subclass of DihedralTerm. the key is the name of the object.

Type:

dict, [str, subclass of DihedralTerm]

improper_terms

Improper terms between four atom types. For each key value pair, the value is a object of subclass of ImproperTerm. the key is the name of the object.

Type:

dict, [str, subclass of ImproperTerm]

vdw_cutoff

Cutoff distance for vdW interactions. Will be ignored if periodic boundary condition is not used.

Type:

float

vdw_long_range

The method to handle the long-range vdW interactions. Optional values: VDW_LONGRANGE_CORRECT, VDW_LONGRANGE_SHIFT Will be ignored if periodic boundary condition is not used.

Type:

str

lj_mixing_rule

The rule to generate the pairwise LJ126 parameters if not provided. Optional values: LJ_MIXING_NONE, LJ_MIXING_LB, LJ_MIXING_GEOMETRIC

Type:

str

scale_14_vdw

The scaling factor for 1-4 vdW interactions

Type:

float

scale_14_coulomb

The scaling factor for 1-4 Coulomb interactions

Type:

float

comments

Comments describes misc information for this force field

Type:

list of str

Methods

__init__()
add_term(term[, replace])	Add a force field term into this force field.
assign_charge(top_or_mol)	Assign charges for all atoms in a topology or molecule from the force field.
assign_mass(top_or_mol)	Assign masses for all atoms in a topology or molecule from the force field.
get_all_terms()	Get all the FFTerms in this force field
get_angle_term(type1, type2, type3)	Get the angle term for the angle formed by three atom types.
get_bci_term(type1, type2)	Get the charge increment term for the bond formed by two atom types.
get_bond_term(type1, type2)	Get the bond term for the bond formed by two atom types.
get_dihedral_term(type1, type2, type3, type4)	Get the dihedral term for the dihedral formed by four atom types.
get_eqt_for_bci(bond)	Get the equivalent atom types for charge increment parameters of the two atoms in a bond.
get_eqt_for_bond(bond)	Get the equivalent atom types for bond parameters of the two atoms in a bond.
get_eqt_list_for_angle(angle)	Get the list of possible equivalent atom types for angle parameters of the three atoms in an angle.
get_eqt_list_for_dihedral(dihedral)	Get the list of possible equivalent atom types for dihedral parameters of the four atoms in a dihedral.
get_eqt_list_for_improper(improper)	Get the list of possible equivalent atom types for improper parameters of the four atoms in an improper.
get_improper_term(type1, type2, type3, type4)	Get the improper term for the improper formed by four atom types.
get_settings()	Get the settings of this force field.
get_vdw_term(type1, type2[, mixing])	Get the vdW term between two atom types.
open(*files)	Load ForceField from one or multiple files.
register_format(extension, cls)
restore_settings(d)	Restore the settings of this force field
write(file)	Write this force field into a file.

Attributes

LJ_MIXING_GEOMETRIC	Geometric mixing rule for LJ126 parameters (used by OPLS)
LJ_MIXING_LB	Lorentz-Berthelot mixing rule for LJ126 parameters (used by CHARMM and AMBER)
LJ_MIXING_NONE	Do not use mixing rule for LJ126 parameters
SETTING_ATTRS
VDW_LONGRANGE_CORRECT	Truncated vdW interactions with long range continuum correction
VDW_LONGRANGE_SHIFT	Truncated vdW interactions with potential shifted so that vdW energy equal to zero at cutoff
angle_term_classes	The unique angle term classes
bond_term_classes	The unique bond term classes
dihedral_term_classes	The unique dihedral term classes
energy_term_classes	The unique vdw, bond, angle, dihedral, improper and polar classes.
has_virtual_site	Whether or not this force field contains virtual sites.
improper_term_classes	The unique improper term classes
is_polarizable	Whether or not this is a polarizable force field.
lj_mixing_rule
polar_term_classes	The unique polar classes
vdw_long_range
vdw_term_classes	The unique self and pairwise vdW term classes

VDW_LONGRANGE_CORRECT = 'correct'

Truncated vdW interactions with long range continuum correction

VDW_LONGRANGE_SHIFT = 'shift'

Truncated vdW interactions with potential shifted so that vdW energy equal to zero at cutoff

LJ_MIXING_NONE = 'none'

Do not use mixing rule for LJ126 parameters

LJ_MIXING_LB = 'lorentz-berthelot'

Lorentz-Berthelot mixing rule for LJ126 parameters (used by CHARMM and AMBER)

LJ_MIXING_GEOMETRIC = 'geometric'

Geometric mixing rule for LJ126 parameters (used by OPLS)

SETTING_ATTRS = {'lj_mixing_rule': <class 'str'>, 'scale_14_coulomb': <class 'float'>, 'scale_14_vdw': <class 'float'>, 'vdw_cutoff': <class 'float'>, 'vdw_long_range': <class 'str'>}

static register_format(extension, cls)

property vdw_term_classes

The unique self and pairwise vdW term classes

Returns:

classes

Return type:

set of subclass of VdwTerm

property bond_term_classes

The unique bond term classes

Returns:

classes

Return type:

set of subclass of BondTerm

property angle_term_classes

The unique angle term classes

Returns:

classes

Return type:

set of subclass of AngleTerm

property dihedral_term_classes

The unique dihedral term classes

Returns:

classes

Return type:

set of subclass of DihedralTerm

property improper_term_classes

The unique improper term classes

Returns:

classes

Return type:

set of subclass of ImproperTerm

property polar_term_classes

The unique polar classes

Returns:

classes

Return type:

set of subclass of PolarTerm

property energy_term_classes

The unique vdw, bond, angle, dihedral, improper and polar classes.

This property is mainly used for exporting input files for various MD engines. These FF terms determines whether the force field contains any potential function unsupported by the MD engine. AtomType, ChargeIncrementTerm and VirtualSiteTerm are not included because they are integrated into the topology before exporting to MD engines.

Returns:

classes

Return type:

set of subclass of FFTerm

property vdw_long_range

property lj_mixing_rule

static open(*files)

Load ForceField from one or multiple files.

If a file does not exist, will search it under directories defined by MSTK_FORCEFIELD_PATH. The parser will be determined from the extension of each file.

If multiple files are provided, they will be parsed in order and be combined into a single ForceField object. These force fields must share the same setting. Otherwise an Exception will be raised. If the force fields contain comments, only the ones from the first file will be kept. If the same parameters appeared in several files, the ones parsed later will override the ones parsed earlier.

Parameters:

files (str) –

The files to be read. The extension can be zff, zfp’, `ppf or ff.

• zff file is the default plain text format of mstk, and will be parsed by Zff.

• zfp file is the deprecated XML format of mstk, and will be parsed by Zfp.

• ppf file will be parsed as DFF format by Ppf.

• ff file will be parsed as fftool format by Padua.

Returns:

forcefield

Return type:

ForceField

write(file)

Write this force field into a file.

The format of the file will be determined by its extension

Parameters:

file (str) –

property is_polarizable

Whether or not this is a polarizable force field.

Return True as long as the polar_terms is not empty.

Returns:

is

Return type:

bool

property has_virtual_site

Whether or not this force field contains virtual sites.

Return True as long as the virtual_site_terms is not empty.

Returns:

is

Return type:

bool

get_settings()

Get the settings of this force field.

Returns:

settings

Return type:

dict, [str, str]

restore_settings(d)

Restore the settings of this force field

Parameters:

d (dict, [str, str]) –

add_term(term, replace=False)

Add a force field term into this force field.

If a terms already exists in the force field, the argument replace will determine the behavior. If replace is True, the one existed will be replaced by the new term. Otherwise, an Exception will be raised.

Parameters:

• term (subclass of FFTerm) –

• replace (bool) –

get_vdw_term(type1, type2, mixing=True)

Get the vdW term between two atom types.

If type1 and type2 are the same, then will search parameters in vdw_terms and return the reference of the term. If not found, an Exception will be raised. If type1 and type2 are not the same, then will search parameters in pairwise_vdw_terms and return the reference of the term. If not found and mixing is True and lj_mixing_rule does not equal to LJ_MIXING_NONE, then a vdw term will be constructed from the mixing rule and be returned. Otherwise, an Exception will be raised. The constructed vdw term will be LJ126Term if vdw for both type1 and type2 are LJ126Term, otherwise a MieTerm will be constructed.

Parameters:

• type1 (AtomType or str) – If type1 is a AtomType object, then will search for its equivalent type for vdW parameters. If type1 is a str, then will match exactly this type.

• type2 (AtomType or str) – If type2 is a AtomType object, then will search for its equivalent type for vdW parameters. If type2 is a str, them will match exactly this type.

• mixing (bool) – Whether to use mixing rule to construct a pairwise vdW term if not found from pairwise_vdw_terms. If set to False, and the pairwise vdW term not found, an Exception will be raised even if this force field supports mixing rule.

Returns:

term

Return type:

subclass of VdwTerm

get_eqt_for_bond(bond)

Get the equivalent atom types for bond parameters of the two atoms in a bond.

Parameters:

bond (Bond) –

Returns:

• type1 (str) – The equivalent atom type for bond parameters of the first atom in this bond.

• type2 (str) – The equivalent atom type for bond parameters of the second atom in this bond.

get_bond_term(type1, type2)

Get the bond term for the bond formed by two atom types.

If not found, an Exception will be raised.

Parameters:

• type1 (AtomType or str) – If type1 is a AtomType object, then will search for its equivalent type for bond parameters. If type1 is a str, then will match exactly this type.

• type2 (AtomType or str) – If type2 is a AtomType object, then will search for its equivalent type for bond parameters. If type2 is a str, them will match exactly this type.

Returns:

term

Return type:

subclass of BondTerm

get_eqt_list_for_angle(angle)

Get the list of possible equivalent atom types for angle parameters of the three atoms in an angle.

Because the wildcard (*) is allowed for the side atoms of an angle term, a list of possible equivalent atom types is returned. The first element of the returned list is the equivalent atom types of the three atoms. The following elements are the generalized atom types by replacing side atoms with wildcard.

Parameters:

angle (Angle) –

Returns:

types – Each element of the list is a tuple of three str (type1, type2, type3), which are the equivalent atom types for angle parameters of the three atoms in this angle.

Return type:

list of tuple of str

get_angle_term(type1, type2, type3)

Get the angle term for the angle formed by three atom types.

If not found, an Exception will be raised.

Parameters:

• type1 (AtomType or str) – If type1 is a AtomType object, then will search for its equivalent type for angle side parameters. If type1 is a str, then will match exactly this type.

• type2 (AtomType or str) – If type2 is a AtomType object, then will search for its equivalent type for angle center parameters. If type2 is a str, them will match exactly this type.

• type3 (AtomType or str) – If type3 is a AtomType object, then will search for its equivalent type for angle side parameters. If type3 is a str, them will match exactly this type.

Returns:

term

Return type:

subclass of AngleTerm

get_eqt_list_for_dihedral(dihedral)

Get the list of possible equivalent atom types for dihedral parameters of the four atoms in a dihedral.

Because the wildcard (*) is allowed for the side atoms of a dihedral term, a list of possible equivalent atom types is returned. The first element of the returned list is the equivalent atom types of the four atoms. The following elements are the generalized atom types by replacing side atoms with wildcard.

Parameters:

dihedral (Dihedral) –

Returns:

types – Each element of the list is a tuple of four str (type1, type2, type3, type4), which are the equivalent atom types for dihedral parameters of the four atoms in this dihedral.

Return type:

list of tuple of str

get_dihedral_term(type1, type2, type3, type4)

Get the dihedral term for the dihedral formed by four atom types.

If not found, an Exception will be raised.

Parameters:

• type1 (AtomType or str) – If type1 is a AtomType object, then will search for its equivalent type for dihedral side parameters. If type1 is a str, then will match exactly this type.

• type2 (AtomType or str) – If type2 is a AtomType object, then will search for its equivalent type for dihedral center parameters. If type2 is a str, them will match exactly this type.

• type3 (AtomType or str) – If type3 is a AtomType object, then will search for its equivalent type for dihedral center parameters. If type3 is a str, them will match exactly this type.

• type4 (AtomType or str) – If type4 is a AtomType object, then will search for its equivalent type for dihedral side parameters. If type4 is a str, them will match exactly this type.

Returns:

term

Return type:

subclass of DihedralTerm

get_eqt_list_for_improper(improper)

Get the list of possible equivalent atom types for improper parameters of the four atoms in an improper.

Because the wildcard (*) is allowed for the side atoms of an improper term, a list of possible equivalent atom types is returned. The first element of the returned list is the equivalent atom types of the four atoms. The following elements are the generalized atom types by replacing side atoms with wildcard.

Parameters:

improper (Improper) –

Returns:

types – Each element of the list is a tuple of four str (type1, type2, type3, type4), which are the equivalent atom types for improper parameters of the four atoms in this improper.

Return type:

list of tuple of str

get_improper_term(type1, type2, type3, type4) → ImproperTerm

Get the improper term for the improper formed by four atom types.

If not found, an Exception will be raised.

Parameters:

• type1 (AtomType or str) – If type1 is a AtomType object, then will search for its equivalent type for improper center parameters. If type1 is a str, then will match exactly this type.

• type2 (AtomType or str) – If type2 is a AtomType object, then will search for its equivalent type for improper side parameters. If type2 is a str, them will match exactly this type.

• type3 (AtomType or str) – If type3 is a AtomType object, then will search for its equivalent type for improper side parameters. If type3 is a str, them will match exactly this type.

• type4 (AtomType or str) – If type4 is a AtomType object, then will search for its equivalent type for improper side parameters. If type4 is a str, them will match exactly this type.

Returns:

term

Return type:

subclass of ImproperTerm

get_eqt_for_bci(bond)

Get the equivalent atom types for charge increment parameters of the two atoms in a bond.

Parameters:

bond (Bond) –

Returns:

• type1 (str) – The equivalent atom type for charge increment parameters of the first atom in this bond.

• type2 (str) – The equivalent atom type for charge increment parameters of the second atom in this bond.

get_bci_term(type1, type2)

Get the charge increment term for the bond formed by two atom types. A direction will also be returned, which equal to 1 if type1 in the charge increment term matches type1 in arguments, -1 otherwise.

If not found, an Exception will be raised.

Parameters:

• type1 (AtomType or str) – If type1 is a AtomType object, then will search for its equivalent type for charge increment parameters. If type1 is a str, then will match exactly this type.

• type2 (AtomType or str) – If type2 is a AtomType object, then will search for its equivalent type for charge increment parameters. If type2 is a str, them will match exactly this type.

Returns:

• term (subclass of BondTerm)

• direction ([1, -1])

get_all_terms()

Get all the FFTerms in this force field

Returns:

terms

Return type:

list of FFTerm

assign_mass(top_or_mol)

Assign masses for all atoms in a topology or molecule from the force field.

The atom types should have been defined, and the AtomType in FF should carry mass information. The masses of Drude particles will be determined ONLY from the DrudePolarTerm, and the the same amount of mass will be subtracted from the parent atoms. That is, if there is an AtomType for Drude particles, the mass attribute of this AtomType will be simply ignored.

Parameters:

top_or_mol (Topology or Molecule) –

assign_charge(top_or_mol)

Assign charges for all atoms in a topology or molecule from the force field.

The atom types should have been defined. The charge of corresponding AtomType in FF will be assigned to the atoms first. Then if there are ChargeIncrementTerm, the charge will be transferred between bonded atoms. The charge of Drude particles will be determined ONLY from the DrudePolarTerm, and the same amount of charge will be subtracted from the parent atoms. That is, if there is an AtomType for Drude particles, the charge attribute of this AtomType will be simply ignored.

Parameters:

top_or_mol (Topology or Molecule) –