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]

qinc_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]

polarizable_terms¶

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

Type:: dict, [str, subclass of PolarizableTerm]

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

Methods

`__init__`()
`add_term`(term[, replace])	Add a force field term into this force field.
`assign_charge`(top_or_mol[, transfer_qinc_terms])	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_angle_term`(type1, type2, type3)	Get the angle term for the angle formed by three 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_angle`(angle)	Get the equivalent atom types for angle parameters of the three atoms in a angle.
`get_eqt_for_bond`(bond)	Get the equivalent atom types for bond parameters of the two atoms in a bond.
`get_eqt_for_dihedral`(dihedral)	Get the list of possible equivalent atom types for dihedral parameters of the four atoms in a dihedral.
`get_eqt_for_improper`(improper)	Get the list of possible equivalent atom types for improper parameters of the four atoms in a improper.
`get_eqt_for_qinc`(bond)	Get the equivalent atom types for charge increment parameters of the two atoms in a bond.
`get_improper_term`(type1, type2, type3, type4)	Get the improper term for the improper formed by four atom types.
`get_qinc_term`(type1, type2)	Get the charge increment term for the bond formed by two 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 files.
`registor_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
`has_virtual_site`	Whether or not this force field contains virtual sites.
`is_polarizable`	Whether or not this is a polarizable force field.
`lj_mixing_rule`
`vdw_long_range`

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 registor_format(extension, cls)¶

property vdw_long_range¶

property lj_mixing_rule¶

static open(*files)¶

Load ForceField from files.

If a file does not exist, will search it under directories defined by MSTK_FORCEFIELD_PATH.

The parser for reading the files will be determined from the extension of the first file. Therefore, all the files should be in the same format.

Parameters:

files (str) –

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

zfp file is the native XML format of mstk, and will be parsed by Zfp.
zff file is the plain text format of mstk, and will be parsed by Zff.
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 polarizable_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 or not using combination rule for LJ126Term.

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_for_angle(angle)¶

Get the equivalent atom types for angle parameters of the three atoms in a angle.

Parameters:

angle (Angle) –

Returns:

type1 (str) – The equivalent atom type for angle parameters of the first atom in this angle.
type2 (str) – The equivalent atom type for angle parameters of the second atom in this angle.
type3 (str) – The equivalent atom type for angle parameters of the third atom in this angle.

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_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.

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 atom 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_for_improper(improper)¶

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

Because the wildcard (*) is allowed for the side atoms of a improper term, a list of possible equivalent atom types is returned.

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 atom 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_qinc(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_qinc_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])

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 DrudeTerm, 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, transfer_qinc_terms=False)¶

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 DrudePolarizableTerm, and the 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.

If charge increment parameters required by the topology are not found in the force field, mstk can try to transfer parameters from more general terms in the force field. e.g. if charge increment term between ‘c_4o2’ and ‘n_3’ is not found, the term between ‘c_4’ and ‘n_3’ will be used. This mechanism is initially designed for TEAM force field. It is disabled by default, and can be enabled by setting argument transfer_qinc_terms to True.

Parameters:

top_or_mol (Topology or Molecule) –
transfer_qinc_terms (bool, optional) –

mstk.forcefield.ForceField¶

mstk

Navigation

Related Topics