mstk.simsys.System

class mstk.simsys.System(topology, ff, suppress_pbc_warning=False, allow_missing_terms=False)

System is a combination of topology and forcefield, ready for simulation.

When a system being initialized, a compressed set of force field is constructed with the terms required by the topology. Note that the terms in the compressed force field are references to the terms in the original force field. A series of data structures are also constructed to map the topological elements to force field terms. Unless you are certain, DO NOT make any modification to the topology and force field after a system is initialized, as it may corrupt the system.

During the initialization, all information in the topology will be kept untouched, which means:

  • The atom type of all atoms in the topology must have been correctly assigned, so that the force field terms can be matched.

  • The charges and masses of all atoms in the topology must have been assigned. You may need to call mstk.forcefield.ForceField.assign_charge() and mstk.forcefield.ForceField.assign_mass() before constructing the system to update the charges and masses of atoms in the topology.

  • If this is a Drude polarizable model, the Drude particles must be available in the topology, and the polarizability, thole screening and charges on Drude particles must have been correctly assigned. You may need to call mstk.topology.Topology.generate_drude_particles() to generate Drude particles.

  • If this is a virtual site model, the virtual site particles must be available in the topology.

The provided force field must be able to fully describe the energy of the topology. If any atom type from topology is not found in the FF, an Exception will be raised. If any vdw/bond/angle/dihedral/improper/polar term required by topology is not found in the FF, an Exception will be raised unless allow_missing_terms set to True. It won’t check charge increment terms and virtual site terms, because they are already represented by the topology itself.

Positions and unit cell should be included in the topology. If positions are not included in the topology, an Exception will be raised. Unit cell is optional. If unit cell is not provided, cutoff will not be used for non-bonded interactions.

Parameters:

  • topology (Topology) –

  • ff (ForceField) –

  • suppress_pbc_warning (bool) – Set to True if you intend to build a vacuum system and don’t want to hear warning about it.

  • allow_missing_terms (bool) – If set to True, won’t raise Exception if FF terms other than AtomType are missing. This is useful if you want to check which FF terms are missing.

charged

True if any atom in this system carries charge

Type:

bool

use_pbc

True if unit cell information provided and volume is not zero

Type:

bool

drude_pairs
Type:

dict, [Atom, Atom]

vsite_pairs
Type:

dict, [Atom, Atom]

constrain_bonds
Type:

dict, [Bond, float]

constrain_angles
Type:

dict, [Angle, float]

atom_vdw_terms
Type:

dict, [Atom, subclass of VdwTerm]

bond_terms
Type:

dict, [Bond, subclass of BondTerm]

angle_terms
Type:

dict, [Angle, subclass of AngleTerm]

dihedral_terms
Type:

dict, [Dihedral, subclass of DihedralTerm]

improper_terms
Type:

dict, [Improper, subclass of ImproperTerm]

polar_terms
Type:

dict, [Atom, subclass of PolarTerm]

missing_terms
Type:

list of FFTerm

Methods

__init__(topology, ff[, ...])

decompose_energy([disable_inter_mol, verbose])

Calculate the contribution of each energy term in this system

export_gromacs([gro_out, top_out, mdp_out])

Generate input files for GROMACS

export_lammps([data_out, in_out])

Generate input files for Lammps.

export_namd([pdb_out, psf_out, prm_out])

Generate input files for NAMD

get_TIP4P_linear_coeffs(atom)

Get the three linear coefficients to calculate the position of TIP4P virtual site from O, H and H positions

minimize_energy([disable_inter_mol, ...])

Perform energy minimization on this system.

to_omm_system([disable_inter_mol])

Export this system to OpenMM system

Attributes

ff

The compressed force field associated with the system

topology

The topology associated with the system
property topology

The topology associated with the system

Returns:

topology

Return type:

Topology

property ff

The compressed force field associated with the system

Returns:

ff

Return type:

ForceField

export_lammps(data_out='data.lmp', in_out='in.lmp', **kwargs)

Generate input files for Lammps.

Parameters:

  • data_out (str) –

  • in_out (str) –

export_gromacs(gro_out='conf.gro', top_out='topol.top', mdp_out='grompp.mdp', **kwargs)

Generate input files for GROMACS

Parameters:

  • gro_out (str or None) –

  • top_out (str or None) –

  • mdp_out (str or None) –

export_namd(pdb_out='conf.pdb', psf_out='top.psf', prm_out='ff.prm', **kwargs)

Generate input files for NAMD

Parameters:

  • pdb_out (str or None) –

  • psf_out (str or None) –

  • prm_out (str or None) –

to_omm_system(disable_inter_mol=False, **kwargs)

Export this system to OpenMM system

Parameters:

disable_inter_mol (bool) – Disable inter-molecular interactions. This is useful for optimizing a batch of molecules

Returns:

omm_system

Return type:

openmm.openmm.System

decompose_energy(disable_inter_mol=False, verbose=True)

Calculate the contribution of each energy term in this system

Parameters:

  • disable_inter_mol (bool) –

  • verbose (bool) –

Returns:

energies – The potential energies of different contributions

Return type:

Dict[str, float]

minimize_energy(disable_inter_mol=False, tolerance=100.0, verbose=True)

Perform energy minimization on this system.

The position of each atom in the topology will be updated.

Parameters:

  • disable_inter_mol (bool) –

  • tolerance (float) –

  • verbose (bool) –

get_TIP4P_linear_coeffs(atom)

Get the three linear coefficients to calculate the position of TIP4P virtual site from O, H and H positions

Parameters:

atom (Atom) – The virtual site atom in TIP4P water topology

Returns:

params

Return type:

tuple of float