mstk.topology.Topology¶

class mstk.topology.Topology(molecules=None, numbers=None, cell=None)¶

A topology is a combination of molecules and unit cell.

Parameters:

molecules (list of Molecule, optional) – If molecules not provided, the topology should be initialized by calling update_molecules().
numbers (list of int, optional) – The number of each molecule you want to put in this topology.
cell (UnitCell, optional) – If cell not provided, a default cell with zero volume will be assumed.

Notes

All the molecules will be deep copied if there are identical molecules in the list, or if numbers is not None. The cell will always be deep copied if provided.

remark¶

A short remark for this topology. Only used for output topology file

Type:: str

cell¶

Unit cell of this topology. Required for output simulation files and guessing connectivity

Type:: UnitCell

Methods

`__init__`([molecules, numbers, cell])
`generate_angle_dihedral_improper`([dihedral, ...])	Generate angles, dihedrals and impropers from bonds.
`generate_drude_particles`(ff, **kwargs)	Generate Drude particles from DrudePolarTerms in a polarizable force field
`generate_virtual_sites`(ff, **kwargs)	Generate virtual sites from VirtualSiteTerms in a force field
`get_12_13_14_pairs`()	Retrieve all the 1-2, 1-3 and 1-4 pairs based on the bond information.
`get_drude_pairs`()	Retrieve all the Drude dipole pairs belong to this topology
`get_unique_molecules`([deepcopy])	Get the unique molecules and the number of molecules that are similar to these unique molecules.
`get_virtual_site_pairs`()	Retrieve all the virtual site pairs belong to this topology
`guess_bonds_from_ff`(ff[, bond_length_limit, ...])	Guess the connectivity between atoms from force field parameters.
`init_from_omm_topology`(omm_top)	Init the topology from OpenMM topology.
`open`(file, **kwargs)	Load topology from a file or smiles string
`register_format`(extension, cls)
`remove_drude_particles`()	Remove all the Drude particles from this topology
`remove_virtual_sites`()	Remove all the virtual sites from this topology
`save_to`(top, file, **kwargs)	This method should be implemented by subclasses
`scale_box`(scale[, rigid_group])	Scale the box and positions of atoms
`scale_with_packmol`(numbers[, packmol, seed, ...])	Enlarge the number of molecules in this topology with Packmol.
`set_positions`(positions)	Set the positions of all atoms in this topology
`to_omm_topology`()	Generate OpenMM topology from this topology
`update_molecules`(molecules[, numbers, deepcopy])	Update the molecules contained in this topology.
`write`(file, **kwargs)	Write topology to a file.

Attributes

`angles`	List of angles belong to this topology
`atoms`	List of atoms belong to this topology
`bonds`	List of bonds belong to this topology
`dihedrals`	List of dihedrals belong to this topology
`has_position`	Whether or not all the atoms in the topology have positions
`has_virtual_site`	Whether or not this topology contains virtual site
`impropers`	List of impropers belong to this topology
`is_drude`	Whether or not this topology represents a Drude model
`molecules`	List of molecules belong to this topology
`n_angle`	Number of angles belong to this topology
`n_atom`	Number of atoms belong to this topology
`n_bond`	Number of bonds belong to this topology
`n_dihedral`	Number of dihedrals belong to this topology
`n_improper`	Number of impropers belong to this topology
`n_molecule`	Number of molecules belong to this topology
`n_residue`	Number of residues belong to this topology
`positions`	Positions of all the atoms in this topology
`residues`	List of residues belonging to this topology
`virtual_site_classes`	A set of all the VirtualSite classes in the topology

static register_format(extension, cls)¶

update_molecules(molecules, numbers=None, deepcopy=False)¶

Update the molecules contained in this topology.

The index of molecules and atoms will be updated. Therefore, this method should be called as long as atoms or molecules are added to or removed from topology.

Parameters:

molecules (list of Molecule) –
numbers (list of int, Optional) –
deepcopy (bool) –

Notes

The molecules and atoms are deep copied if numbers is not None or deepcopy is True. The molecules and atoms are deep copied if there are identical molecules in the list.

set_positions(positions)¶

Set the positions of all atoms in this topology

Parameters:: positions (array_like) –

get_unique_molecules(deepcopy=True)¶

Get the unique molecules and the number of molecules that are similar to these unique molecules.

This is mainly used for exporting GROMACS topol file. By default, the unique molecules are deep copied.

Parameters:: deepcopy (bool) –
Returns:: molecule_number
Return type:: dict [Molecule, int]

scale_with_packmol(numbers, packmol=None, seed=1, tempdir=None)¶

Enlarge the number of molecules in this topology with Packmol.

It is used for building real simulation box from several molecules. It generates molecules with appropriate positions and adds them into the topology. The unit cell should already be defined, and it will not be touched during the scaling.

An input file for packmol and xyz files for molecules will be created under tempdir. If packmol is provided, then it will be invoked to pack the simulation box, and the generated positions will be loaded back to the topology, and the tempdir will be removed. Otherwise, the topology will be enlarged without correct positions, and the files under tempdir will be kept so that positions can be built manually and loaded back to the topology later.

Parameters:

numbers (int or list of int) – If numbers is a int, the topology will be scaled by this times. If numbers is a list of int, then each molecule will be scaled by corresponding times.
packmol (Packmol, Optional) – If is None, will generate input files for packmol.
seed (int) – Seed for random number for Packmol
tempdir (str, Optional) – The temporary directory to keep intermediate files for packmol. It should exist already If is None, will create a directory under system temporary directory

scale_box(scale, rigid_group='atom')¶

Scale the box and positions of atoms

Parameters:

scale (float or np.array of shape (3,)) –
rigid_group (['atom', 'molecule', 'residue']) – If set to atom, the positions of all atoms will be equally scaled If set to molecule, each molecule will be treated as a rigid body during scaling If set to residue, each residue will be treated as a rigid body during scaling

property n_molecule¶

Number of molecules belong to this topology

Returns:: n
Return type:: int

property n_atom¶

Number of atoms belong to this topology

Returns:: n
Return type:: int

property n_residue¶

Number of residues belong to this topology

Returns:: n
Return type:: int

property molecules¶

List of molecules belong to this topology

Returns:: molecules
Return type:: list of Molecule

property atoms¶

List of atoms belong to this topology

Returns:: atoms
Return type:: list of Atom

property residues¶

List of residues belonging to this topology

The residue list is generated on the fly because it is called irregularly. Therefore, the performance of this method is not of concern.

Returns:: residues
Return type:: list of Residue

property n_bond¶

Number of bonds belong to this topology

Returns:: n
Return type:: int

property n_angle¶

Number of angles belong to this topology

Returns:: n
Return type:: int

property n_dihedral¶

Number of dihedrals belong to this topology

Returns:: n
Return type:: int

property n_improper¶

Number of impropers belong to this topology

Returns:: n
Return type:: int

property bonds¶

List of bonds belong to this topology

Returns:: bonds
Return type:: list of Bond

property angles¶

List of angles belong to this topology

Returns:: angles
Return type:: list of Angle

property dihedrals¶

List of dihedrals belong to this topology

Returns:: dihedrals
Return type:: list of Dihedral

property impropers¶

List of impropers belong to this topology

Returns:: impropers
Return type:: list of Improper

property has_position¶

Whether or not all the atoms in the topology have positions

Returns:: has
Return type:: bool

property positions¶

Positions of all the atoms in this topology

Returns:: positions
Return type:: array_like

property is_drude¶

Whether or not this topology represents a Drude model

Returns:: is
Return type:: bool

property has_virtual_site¶

Whether or not this topology contains virtual site

Returns:: has
Return type:: bool

property virtual_site_classes¶

A set of all the VirtualSite classes in the topology

Returns:: classes
Return type:: set of subclass of VirtualSite

static open(file, **kwargs)¶

Load topology from a file or smiles string

The format will be determined from the extension of the file.

Parameters:: file (str) – If start with ‘:’, then it will be treated as SMLIES string. Otherwise, it is the file to be read.
Returns:: topology
Return type:: Topology

write(file, **kwargs)¶

Write topology to a file.

The format will be determined from the extension of the file.

Parameters:: file (str) –

static save_to(top, file, **kwargs)¶: This method should be implemented by subclasses

to_omm_topology()¶

Generate OpenMM topology from this topology

Returns:: omm_topology
Return type:: mm.app.Topology

init_from_omm_topology(omm_top)¶

Init the topology from OpenMM topology.

This is only used for write trajectory, therefore only the atomic symbol is loaded. It should not be used for other purpose.

Parameters:: omm_top (mm.app.Topology) –

get_drude_pairs()¶

Retrieve all the Drude dipole pairs belong to this topology

Returns:: pairs – [(parent, drude)]
Return type:: list of tuple of Atom

See also

Molecule.get_drude_pairs

get_virtual_site_pairs()¶

Retrieve all the virtual site pairs belong to this topology

TODO It assumes no more than one virtual site is attached to each atom

Returns:: pairs – [(parent, atom_virtual_site)]
Return type:: list of tuple of Atom

See also

Molecule.get_virtual_site_pairs

get_12_13_14_pairs()¶

Retrieve all the 1-2, 1-3 and 1-4 pairs based on the bond information.

The pairs only concerns real atoms. Drude particles will be ignored.

Returns:

pairs12 (list of tuple of Atom)
pairs13 (list of tuple of Atom)
pairs14 (list of tuple of Atom)

See also

Molecule.get_12_13_14_pairs

generate_angle_dihedral_improper(dihedral=True, improper=True)¶: Generate angles, dihedrals and impropers from bonds.

See also

Molecule.generate_angle_dihedral_improper

guess_bonds_from_ff(ff, bond_length_limit=None, tolerance=0.025, pbc=None)¶

Guess the connectivity between atoms from force field parameters.

Parameters:

ff (ForceField) –
bond_length_limit (float, optional) –
tolerance (float) –
pbc (str, optional) –

See also

Molecule.guess_bonds_from_ff

generate_drude_particles(ff, **kwargs)¶

Generate Drude particles from DrudePolarTerms in a polarizable force field

Parameters:

ff (ForceField) –
kwargs (dict) –

See also

Molecule.generate_drude_particles

remove_drude_particles()¶

Remove all the Drude particles from this topology

It is useful for build non-polarizable model from polarizable model

See also

Molecule.remove_drude_particles

generate_virtual_sites(ff, **kwargs)¶

Generate virtual sites from VirtualSiteTerms in a force field

Parameters:

ff (ForceField) –
kwargs (dict) –

See also

Molecule.generate_virtual_sites

remove_virtual_sites()¶

Remove all the virtual sites from this topology

It is useful for build non-virtual-site model from virtual-site model

See also

Molecule.remove_virtual_sites

mstk.topology.Topology¶

mstk

Navigation

Related Topics