gaddlemaps.components package
Module contents
Molecular Simulation Components
This submodule contains useful objects to workaround with components from molecular dynamics simulations (molecules, atoms…). You can load the information of these components just from the coordinates files (.gro) or add information about atom types or how they are bonded loading the topologies.
To start, you can load an object with a .gro file of a simulation system with the class SystemGro. You can iterate through this object accessing the residues in the system which will be instances of Residue class. At the same time, you can iterate through the atoms (AtomGro instances) of a Residue instance.
If you want to include the information from topology files (up to now, just .itp files with gromacs format are compatible) to the system you can initialize an instance of the System class. In this case, the System is formed by Molecule objects (which are combinations of Residue and MoleculeTop objects) and the Molecule is formed by Atom objects (combination of AtomGro and AtomTop).
- class gaddlemaps.components.Atom(atom_top, atom_gro)[source]
Bases:
objectAn atom class that wraps the AtomTop and AtomGro classes.
You can access to the methods and attributes that both AtomGro and AtomItp have. To create the atom object, both input atoms should have the same resname and name attributes. On the other hand, only the attributes from the AtomGro can be changed (e.g. positions, velocities, …) excluding the resname and name.
- Parameters
- Raises
- Attributes
Methods
copy()Returns a copy of self.
- class gaddlemaps.components.AtomGro(parsed_gro_line)[source]
Bases:
objectIt contains the information of a .gro line corresponding to an atom.
You can add atoms with the same residue name and number to form a Residue instance.
- Parameters
parsed_gro_line (list) – A list returned by the GroFile.read_line method when a correct formatted .gro line is input.
- position
The coordinates of the atom.
- Type
np.ndarray(3)
- velocity
The velocity of the atom if it is specified in the .gro line. If not this attribute is set to None.
- Type
np.ndarray(3) or None
- Attributes
Methods
copy()Returns a copy of the atom.
gro_line([parsed])Returns the gro line corresponding to the atom.
- copy()[source]
Returns a copy of the atom.
You can safely change the attributes of the returned atom without changing the original one.
- Returns
new_atom – The copied atom.
- Return type
- property element: str
The element of the atom. It is obtained removing the non alphabetic character in the atom name.
- Type
string
- Return type
- class gaddlemaps.components.AtomTop(name, resname, resid, index)[source]
Bases:
objectAtom with information of its name, residue name and bonds.
It is also needed the index of the atom in the molecule. The bonds are initialized as empty set.
- Parameters
- bonds
A set with the hash of the atoms that are connected to self.
- Type
set of int
- Attributes
residnamestring: An identifier of the residue (resid+name)
Methods
closest_atoms([natoms])Returns a list with natoms index of bonded atoms to self.
connect(atom)Connects self with other atom setting the bond.
copy()Returns a copy of the current atom.
- closest_atoms(natoms=2)[source]
Returns a list with natoms index of bonded atoms to self.
If more than natoms are bonded self, the natoms with lower id_num are returned.
- Parameters
natoms (integer) – The number of atoms to return.
- Returns
bonded_atoms – The list with the index of natoms atoms bonded self.
- Return type
list of int
- connect(atom)[source]
Connects self with other atom setting the bond.
- Parameters
atom (AtomTop) – Atom to connect.
- class gaddlemaps.components.Molecule(molecule_top, residues)[source]
Bases:
ResidueLoads a molecule combining a MoleculeTop and a list of Residue.
This class wraps all the features of both MoleculeTop and Residues which conform the molecule. When an object is initialized a copy of the input residues is stored (to avoid undesired attribute changes). This class inherits from Residue so they have the same methods and properties (although most of them are reimplemented).
- Parameters
molecule_top (MoleculeTop) – The object with the bonds information of the molecule.
residues (List of Residue) – An list with the residues that constitute the molecule.
- Raises
- Attributes
atomslist of Atom: List with the copies of the atoms of the molecule.
atoms_idslist of int: A list with the ids of the atoms in the residues.
atoms_positionsnumpy.ndarray((N, 3)) : An array with the atoms positions.
atoms_velocitiesnumpy.ndarray((N, 3)) or None : An array with the atoms velocities.
bonds_distancedict of int to list of tuple(int, float): A complex data structure
distance_to_zerofloat : The distance between the geometric_center and (0, 0, 0)
geometric_centernumpy.ndarray(3): Coordinates of the geometric center of the residue.
molecule_topMoleculeTop : The object with the topology information of the molecule.
residint: Residue number of the residue.
residnamestring: An identifier of the residue (resid+name)
residsList of int: A list with the residues ids of the residues constituting the molecule.
residuesList of Residue : a list with the Residue objects that constitute the molecule.
resnamestring: Resname of the residue.
resnamesList of string: A list with the names of the residues constituting the molecule.
xfloat: The x coordinate of the geometric center of the residue.
yfloat: The y coordinate of the geometric center of the residue.
zfloat: The z coordinate of the geometric center of the residue.
Methods
copy([new_residues])Returns a copy of the molecule.
deep_copy([new_residues])Returns a deep copy of the molecule.
distance_to(residue[, box_vects, inv])Returns the distance between self and residue.
from_files(fgro, ftop)Loads the molecule from gro and a compatible topology file.
index(atom)Returns the index of the atom in the molecule.
move(displacement)Moves the residue a given displacement vector.
move_to(new_position)Moves the residue geometric_center to new_position.
remove_atom(atom)Removes a given atom from the residue.
rotate(rotation_matrix)Rotate the residue around its center of mass with a given rotation matrix.
update_from_molecule_top(mtop)Modifies the Residue atoms name to match the mtop.
write_gro(fout)Writes a .gro file with the residue conformation.
- property atoms_positions: ndarray
An array with the atoms positions.
- Type
numpy.ndarray((N, 3))
- Return type
- property atoms_velocities: Optional[ndarray]
An array with the atoms velocities. If one of the atoms has no velocity this returns None.
- Type
numpy.ndarray((N, 3)) or None
- property bonds_distance: Dict[int, List[Tuple[int, float]]]
A complex data structure that collect the information of the bond distances. The key of the property corresponds to the atom index in the molecule. The value is a list with tuples. For each tuple, the first value corresponds with the index of the bonded atom and the second is the length of the bond. This property is used in the alignment process in gaddle maps.
- copy(new_residues=None)[source]
Returns a copy of the molecule.
If new_molecule_gro is passed, the old residues will be replaced to update the positions. This is used in the extrapolation step.
NOTE: With this method, the molecule_top used for the Molecule initialization remains the same. This means that future changes in copied molecules may affect other parts of you code. If you want a completely independent new molecule use “deep_copy” method.
- deep_copy(new_residues=None)[source]
Returns a deep copy of the molecule.
If new_molecule_gro is passed, the old residues will be replaced to update the positions. This is used in the extrapolation step. This method generates a new molecule that is not linked to any attribute of the original one.
- distance_to(residue, box_vects=None, inv=False)
Returns the distance between self and residue.
residue can be a Residue instance or a 3D vector.
- Parameters
residue (Residue or numpy.ndarray) – The residue or a point to compute the distance.
box_vects (numpy.ndarray) – The box vectors to apply periodic boundary conditions.
inv (bool) – If it is True, box_vects are considered as the inverse matrix of the actual box_vects for a better performance.
- Returns
distance – The euclidean distance.
- Return type
- property distance_to_zero: float
The distance between the geometric_center and (0, 0, 0) without applying periodic boundary conditions.
- Type
- Return type
- classmethod from_files(fgro, ftop)[source]
Loads the molecule from gro and a compatible topology file.
- property geometric_center: ndarray
Coordinates of the geometric center of the residue.
- Type
- Return type
- property molecule_top: MoleculeTop
The object with the topology information of the molecule.
- Type
- Return type
- move(displacement)
Moves the residue a given displacement vector.
- Parameters
displacement (numpy.ndarray(3)) – An array with the displacement vector.
- move_to(new_position)
Moves the residue geometric_center to new_position.
- Parameters
new_position (numpy.ndarray(3)) – An array with the new position coordinates.
- remove_atom(atom)
Removes a given atom from the residue.
- Parameters
atom (AtomGro) – The atom you want to remove from the residue.
- property resids: List[int]
- A list with the residues ids of the residues
constituting the molecule.
To set this property, a list of int with the same length as the original must be passed. This will change each residue id. You can also pass just an int and this will set all the residue ids to the same value.
- Type
List of int
- property residues: List[Residue]
a list with the Residue objects that constitute the molecule.
- Type
List of Residue
- property resnames: List[str]
- A list with the names of the residues constituting the
molecule.
To set this property, a list of strings with the same length as the original must be passed. This will change each residue name. You can also pass just a string and this will set all the residue names to the same value.
- Type
List of string
- rotate(rotation_matrix)
Rotate the residue around its center of mass with a given rotation matrix.
- Parameters
rotation_matrix (numpy.ndarray) – 3x3 array with the rotation matrix. ADVICE: create the matrix with the help of “rotation_matrix” function placed in the root of the package.
- update_from_molecule_top(mtop)
Modifies the Residue atoms name to match the mtop.
This method is very useful when you have a miss-match between the atom names in the topology and gro files. This will modify the Residue atoms names to match the names in the topology. Make sure that all the atoms in the topology are in the Residue.
- Parameters
mtop (MoleculeTop) – The molecule to match.
- Raises
ValueError – If number of atoms in self and in mtop does not match.
- write_gro(fout)
Writes a .gro file with the residue conformation.
- Parameters
fout (str) – The path with the file to write the information.
- class gaddlemaps.components.MoleculeTop(ftop, file_format=None)[source]
Bases:
objectLoads molecules from a topology file.
This class behaves like a list of atoms which has bonds defined. The appropriate parser will be used based on the input file extension. The available parsers are summarized in the class attribute “PARSERS”. In this attribute, the keys are the files extensions and the values the corresponding functions that extracts the information from the files with that extensions. These functions should return:
The name of the molecule
A list with tuples with the atoms and residues names in order of
appearance in the file. - A list with tuples with atoms index (referred to the atoms_info indexes) that are bonded.
- Parameters
ftop (string or TextIOWrapper) – The path to the file (or the opened file) with the molecule name and bonds information.
file_format (str, Optional) – The file extension of ftop. If it is None this will be taken from ftop.
- Raises
ValueError – If the file format is not supported.
IOError – If the input file misses information.
- Attributes
residslist of str: Residue names of the atoms without consecutive
resname_len_listlist of tuple(str, int) :
resnameslist of str: Residue names of the atoms without consecutive
Methods
copy()Returns a copy of the molecule_top.
index(atom)Returns the index of the atom in the molecule.
- copy()[source]
Returns a copy of the molecule_top.
The atoms forming the copy are not the same objects as the original molecule so you do not have to worry about linked objects.
- Returns
molecule_top – The copy of the molecule.
- Return type
- property resids: List[int]
- Residue names of the atoms without consecutive
repetitions.
To set this property a list with the same length of residues must be passed.
- Type
list of str
- class gaddlemaps.components.Residue(atoms)[source]
Bases:
objectA class with the information of a residue in a .gro file.
This class creates objects that are enumerations of AtomGro instances. It has methods to manipulate atoms positions maintaining the shape of the residue. This class have to be initialized with non empty list of atoms.
You can add two residues if the atoms from both residues have the same residue name and number. This can also be done with just one atom and the same check will be done.
- Parameters
atoms (list of AtomGro) – A list with the atoms of the residue.
:raises ValueError : If the the input list of atoms is empty or they have different: residue number or name.
- Attributes
atomslist of AtomGro: List with a copy of the atoms of the residue.
atoms_idslist of int: A list with the ids of the atoms of the residue.
atoms_positionsnumpy.ndarray((N, 3)) : An array with the atoms positions.
atoms_velocitiesnumpy.ndarray((N, 3)) or None : An array with the atoms velocities.
distance_to_zerofloat : The distance between the geometric_center and (0, 0, 0)
geometric_centernumpy.ndarray(3): Coordinates of the geometric center of the residue.
residint: Residue number of the residue.
residnamestring: An identifier of the residue (resid+name)
resnamestring: Resname of the residue.
xfloat: The x coordinate of the geometric center of the residue.
yfloat: The y coordinate of the geometric center of the residue.
zfloat: The z coordinate of the geometric center of the residue.
Methods
copy()Returns a copy of the residue.
distance_to(residue[, box_vects, inv])Returns the distance between self and residue.
move(displacement)Moves the residue a given displacement vector.
move_to(new_position)Moves the residue geometric_center to new_position.
remove_atom(atom)Removes a given atom from the residue.
rotate(rotation_matrix)Rotate the residue around its center of mass with a given rotation matrix.
update_from_molecule_top(mtop)Modifies the Residue atoms name to match the mtop.
write_gro(fout)Writes a .gro file with the residue conformation.
- property atoms_positions: ndarray
An array with the atoms positions.
- Type
numpy.ndarray((N, 3))
- Return type
- property atoms_velocities: Optional[ndarray]
An array with the atoms velocities. If one of the atoms has no velocity this returns None.
- Type
numpy.ndarray((N, 3)) or None
- copy()[source]
Returns a copy of the residue.
- Returns
residue – The copy of the residue.
- Return type
- distance_to(residue, box_vects=None, inv=False)[source]
Returns the distance between self and residue.
residue can be a Residue instance or a 3D vector.
- Parameters
residue (Residue or numpy.ndarray) – The residue or a point to compute the distance.
box_vects (numpy.ndarray) – The box vectors to apply periodic boundary conditions.
inv (bool) – If it is True, box_vects are considered as the inverse matrix of the actual box_vects for a better performance.
- Returns
distance – The euclidean distance.
- Return type
- property distance_to_zero: float
The distance between the geometric_center and (0, 0, 0) without applying periodic boundary conditions.
- Type
- Return type
- property geometric_center: ndarray
Coordinates of the geometric center of the residue.
- Type
- Return type
- move(displacement)[source]
Moves the residue a given displacement vector.
- Parameters
displacement (numpy.ndarray(3)) – An array with the displacement vector.
- move_to(new_position)[source]
Moves the residue geometric_center to new_position.
- Parameters
new_position (numpy.ndarray(3)) – An array with the new position coordinates.
- remove_atom(atom)[source]
Removes a given atom from the residue.
- Parameters
atom (AtomGro) – The atom you want to remove from the residue.
- rotate(rotation_matrix)[source]
Rotate the residue around its center of mass with a given rotation matrix.
- Parameters
rotation_matrix (numpy.ndarray) – 3x3 array with the rotation matrix. ADVICE: create the matrix with the help of “rotation_matrix” function placed in the root of the package.
- update_from_molecule_top(mtop)[source]
Modifies the Residue atoms name to match the mtop.
This method is very useful when you have a miss-match between the atom names in the topology and gro files. This will modify the Residue atoms names to match the names in the topology. Make sure that all the atoms in the topology are in the Residue.
- Parameters
mtop (MoleculeTop) – The molecule to match.
- Raises
ValueError – If number of atoms in self and in mtop does not match.
- write_gro(fout)[source]
Writes a .gro file with the residue conformation.
- Parameters
fout (str) – The path with the file to write the information.
- class gaddlemaps.components.System(fgro, *ftops)[source]
Bases:
objectClass to manage simulation systems.
A System object is formed by Molecule objects. Only the molecules corresponding to the input ftops will be loaded. The input files can be paths to files or opened files.
- Parameters
fgro (string or TextIOWrapper) – Gromacs file with the system information.
*ftops (string or TextIOWrapper) – Paths with the files with the bonds information to load molecules.
- Raises
IOError – If one of the topology files do not match with any molecule in the system.
- Attributes
compositionCounter of str: int : For each molecule name (key), how many molecules there are (value).
- fgro
Methods
add_ftop(ftop)Adds and identifies the molecule from the ftop to the system.
add_molecule_top(mol_top)Adds a molecule to the system and find it in the gro file.
- add_ftop(ftop)[source]
Adds and identifies the molecule from the ftop to the system.
- Parameters
ftop (str or TextIOWrapper) – Path to the file (or opened file) with the topology of the molecule.
- class gaddlemaps.components.SystemGro(fgro)[source]
Bases:
objectClass to work with the information in gro files.
Basically this class acts like a list of Residue objects. Only one Residue instance of each type is loaded to afford memory for large systems. The positions of the rest of the residues are storage and they are generated when requested.
- Parameters
fgro (string or TextIOWrapper) – Gromacs file path or open file with the system information.
- Attributes
box_matrixnumpy.ndarray (3,3) : the 3 lattice vectors of the box.
comment_linestr: The comment line in the gro file.
compositionCounter of str: int : For each resname (key), how many molecules there are (value).
molecules_info_ordered_allgenerator of int: Returns the index of the molecules in the
molecules_resname_len_indexdict of tuple (string, int) to int: The keys of the dictionary are
n_atomsint : The number of atoms in the system.
- property box_matrix: ndarray
the 3 lattice vectors of the box.
- Type
numpy.ndarray (3,3)
- Return type
- property composition: Mapping[str, int]
For each resname (key), how many molecules there are (value).
- Type
Counter of str
- Type
- property molecules_info_ordered_all: Generator[int, None, None]
Returns the index of the molecules in the different_molecules attribute in order of appearance.
- Type
generator of int