11.3.2. Core Topology Objects — MDAnalysis.core.topologyobjects
¶
The building blocks for MDAnalysis’ description of topology

class
MDAnalysis.core.topologyobjects.
Angle
(ix, universe, type=None, guessed=False, order=None)[source]¶ An angle between three
Atom
instances. Atom 2 is the apex of the angleNew in version 0.8.
Changed in version 0.9.0: Now a subclass of
TopologyObject
; now uses__slots__
and stores atoms inatoms
attributeCreate a topology object
Parameters:  ix (numpy array) – indices of the Atoms
 universe (MDAnalysis.Universe) –
 type (optional) – Type of the bond
 guessed (optional) – If the Bond is guessed

angle
(pbc=True)[source]¶ Returns the angle in degrees of this Angle.
Angle between atoms 0 and 2 with apex at 1:
2 / / 10
Note
The numerical precision is typically not better than 4 decimals (and is only tested to 3 decimals).
New in version 0.9.0.
Changed in version 0.17.0: Fixed angles close to 180 giving NaN
Changed in version 0.19.0: Added pbc keyword, default True

value
(pbc=True)¶ Returns the angle in degrees of this Angle.
Angle between atoms 0 and 2 with apex at 1:
2 / / 10
Note
The numerical precision is typically not better than 4 decimals (and is only tested to 3 decimals).
New in version 0.9.0.
Changed in version 0.17.0: Fixed angles close to 180 giving NaN
Changed in version 0.19.0: Added pbc keyword, default True

class
MDAnalysis.core.topologyobjects.
Bond
(ix, universe, type=None, guessed=False, order=None)[source]¶ A bond between two
Atom
instances.Two
Bond
instances can be compared with the==
and!=
operators. A bond is equal to another if the same atom numbers are connected and they have the same bond order. The ordering of the two atom numbers is ignored as is the fact that a bond was guessed.The presence of a particular atom can also be queried:
>>> Atom in Bond
will return either
True
orFalse
.Changed in version 0.9.0: Now a subclass of
TopologyObject
. Changed class to use__slots__
and stores atoms inatoms
attribute.Create a topology object
Parameters:  ix (numpy array) – indices of the Atoms
 universe (MDAnalysis.Universe) –
 type (optional) – Type of the bond
 guessed (optional) – If the Bond is guessed

length
(pbc=True)[source]¶ Length of the bond.
Changed in version 0.11.0: Added pbc keyword
Changed in version 0.19.0: Changed default of pbc to True

value
(pbc=True)¶ Length of the bond.
Changed in version 0.11.0: Added pbc keyword
Changed in version 0.19.0: Changed default of pbc to True

class
MDAnalysis.core.topologyobjects.
CMap
(ix, universe, type=None, guessed=False, order=None)[source]¶ Coupledtorsion correction map term between five
Atom
instances.New in version 1.0.0.
Create a topology object
Parameters:  ix (numpy array) – indices of the Atoms
 universe (MDAnalysis.Universe) –
 type (optional) – Type of the bond
 guessed (optional) – If the Bond is guessed

class
MDAnalysis.core.topologyobjects.
Dihedral
(ix, universe, type=None, guessed=False, order=None)[source]¶ Dihedral (dihedral angle) between four
Atom
instances.The dihedral is defined as the angle between the planes formed by Atoms (1, 2, 3) and (2, 3, 4).
New in version 0.8.
Changed in version 0.9.0: Now a subclass of
TopologyObject
; now uses__slots__
and stores atoms inatoms
attribute.Changed in version 0.11.0: Renamed to Dihedral (was Torsion)
Create a topology object
Parameters:  ix (numpy array) – indices of the Atoms
 universe (MDAnalysis.Universe) –
 type (optional) – Type of the bond
 guessed (optional) – If the Bond is guessed

dihedral
(pbc=True)[source]¶ Calculate the dihedral angle in degrees.
Dihedral angle around axis connecting atoms 1 and 2 (i.e. the angle between the planes spanned by atoms (0,1,2) and (1,2,3)):
3  12 / 0
Note
The numerical precision is typically not better than 4 decimals (and is only tested to 3 decimals).
New in version 0.9.0.
Changed in version 0.19.0: Added pbc keyword, default True

value
(pbc=True)¶ Calculate the dihedral angle in degrees.
Dihedral angle around axis connecting atoms 1 and 2 (i.e. the angle between the planes spanned by atoms (0,1,2) and (1,2,3)):
3  12 / 0
Note
The numerical precision is typically not better than 4 decimals (and is only tested to 3 decimals).
New in version 0.9.0.
Changed in version 0.19.0: Added pbc keyword, default True

class
MDAnalysis.core.topologyobjects.
ImproperDihedral
(ix, universe, type=None, guessed=False, order=None)[source]¶ Improper Dihedral (improper dihedral angle) between four
Atom
instances.MDAnalysis treats the improper dihedral angle as the angle between the planes formed by Atoms (1, 2, 3) and (2, 3, 4).
Warning
Definitions of Atom ordering in improper dihedrals can change. Check the definitions here against your software.
New in version 0.9.0.
Changed in version 0.11.0: Renamed to ImproperDihedral (was Improper_Torsion)
Create a topology object
Parameters:  ix (numpy array) – indices of the Atoms
 universe (MDAnalysis.Universe) –
 type (optional) – Type of the bond
 guessed (optional) – If the Bond is guessed

class
MDAnalysis.core.topologyobjects.
TopologyDict
(topologygroup)[source]¶ A customised dictionary designed for sorting the bonds, angles and dihedrals present in a group of atoms.
Usage:
topologydict = TopologyDict(members)
TopologyDicts are also built lazily from a
TopologyGroup.topDict
attribute.The
TopologyDict
collects all the selected topology type from the atoms and categorises them according to the types of the atoms within. ATopologyGroup
containing all of a given bond type can be made by querying with the appropriate key. The keys to theTopologyDict
are a tuple of the atom types that the bond represents and can be viewed using thekeys()
method.For example, from a system containing pure ethanol
>>> td = u.bonds.topDict >>> td.keys() [('C', 'C'), ('C', 'H'), ('O', 'H'), ('C', 'O')] >>> td['C', 'O'] < TopologyGroup containing 912 bonds >
Note
The key for a bond is taken from the type attribute of the atoms.
Getting and setting types of bonds is done smartly, so a CCH angle is considered identical to a HCC angle.
Duplicate entries are automatically removed upon creation and combination of different Dicts. This means a bond between atoms 1 and 2 will only ever appear once in a dict despite both atoms 1 and 2 having the bond in their
bond
attribute.Two
TopologyDict
instances can be combined using addition and it will not create any duplicate bonds in the process.Parameters: members – A list of TopologyObject
instancesNew in version 0.8.
Changed in version 0.9.0: Changed initialisation to use a list of
TopologyObject
instances instead of list of atoms; now used from withinTopologyGroup
instead of accessed fromAtomGroup
.

class
MDAnalysis.core.topologyobjects.
TopologyGroup
(bondidx, universe, btype=None, type=None, guessed=None, order=None)[source]¶ A container for a groups of bonds.
All bonds of a certain types can be retrieved from within the
TopologyGroup
by querying with a tuple of types:tg2 = tg.select_bonds([key])
Where key describes the desired bond as a tuple of the involved
Atom
types, as defined by the .type Atom attribute). A list of available keys can be displayed using thetypes()
method.Alternatively, all the bonds which are in a given
AtomGroup
can be extracted usingatomgroup_intersection()
:tg2 = tg.atomgroup_intersection(ag)
This allows the keyword strict to be given, which forces all members of all bonds to be inside the AtomGroup passed to it.
Finally, a TopologyGroup can be sliced similarly to AtomGroups:
tg2 = tg[5:10]
The
bonds()
,angles()
anddihedrals()
methods offer a “shortcut” to the Cython distance calculation functions inMDAnalysis.lib.distances
.TopologyGroups can be combined with TopologyGroups of the same bond type (ie can combine two angle containing TopologyGroups).
New in version 0.8.
Changed in version 0.9.0: Overhauled completely: (1) Added internal
TopologyDict
accessible by thetopDict
attribute. (2)selectBonds()
allows thetopDict
to be queried with tuple of types. (3) Addedatomgroup_intersection()
to allow bonds which are in a givenAtomGroup
to be retrieved.Changed in version 0.10.0: Added
from_indices()
constructor, allowing class to be created from indices. Can now create empty Group. Renameddump_contents()
toto_indices()
Changed in version 0.11.0: Added values method to return the size of each object in this group Deprecated selectBonds method in favour of select_bonds
Changed in version 0.19.0: Empty TopologyGroup now returns correctly shaped empty array via indices property and to_indices()

angles
(result=None, pbc=False)[source]¶ Calculates the angle in radians formed between a bond between atoms 1 and 2 and a bond between atoms 2 & 3
Parameters:  result (array_like) – allows a predefined results array to be used, note that this will be overwritten
 pbc (bool) – apply periodic boundary conditions when calculating angles
[
False
] this is important when connecting vectors between atoms might require minimum image convention
Returns:  angles (ndarray)
 .. versionchanged :: 0.9.0 – Added pbc option (default
False
)

atom1
¶ The first atom in each TopologyObject in this Group

atom2
¶ The second atom in each TopologyObject in this Group

atom3
¶ The third atom in each TopologyObject in this Group

atom4
¶ The fourth atom in each TopologyObject in this Group

atomgroup_intersection
(ag, **kwargs)[source]¶ Retrieve all bonds from within this TopologyGroup that are within the AtomGroup which is passed.
Parameters: New in version 0.9.0.

bonds
(pbc=False, result=None)[source]¶ Calculates the distance between all bonds in this TopologyGroup
Keywords:  pbc
apply periodic boundary conditions when calculating distance [False]
 result
allows a predefined results array to be used, note that this will be overwritten
Uses cython implementation

dihedrals
(result=None, pbc=False)[source]¶ Calculate the dihedral angle in radians for this topology group.
Defined as the angle between a plane formed by atoms 1, 2 and 3 and a plane formed by atoms 2, 3 and 4.
Parameters:  result (array_like) – allows a predefined results array to be used, note that this will be overwritten
 pbc (bool) – apply periodic boundary conditions when calculating angles
[
False
] this is important when connecting vectors between atoms might require minimum image convention
Returns:  angles (ndarray)
 .. versionchanged:: 0.9.0 – Added pbc option (default
False
)

dump_contents
()¶ Return a data structure with atom indices describing the bonds.
This format should be identical to the original contents of the entries in universe._topology. Note that because bonds are sorted as they are initialised, the order that atoms are defined in each entry might be reversed.
Returns:  indices (tuple) – A tuple of tuples which define the contents of this TopologyGroup in terms of the atom numbers. (0 based index within u.atoms)
 .. versionadded:: 0.9.0
 .. versionchanged:: 0.10.0 – Renamed from “dump_contents” to “to_indices”

indices
¶ all bond indices
See also
to_indices
 function that just returns indices

selectBonds
(selection)¶ Retrieves a selection from this topology group based on types.

to_indices
()[source]¶ Return a data structure with atom indices describing the bonds.
This format should be identical to the original contents of the entries in universe._topology. Note that because bonds are sorted as they are initialised, the order that atoms are defined in each entry might be reversed.
Returns:  indices (tuple) – A tuple of tuples which define the contents of this TopologyGroup in terms of the atom numbers. (0 based index within u.atoms)
 .. versionadded:: 0.9.0
 .. versionchanged:: 0.10.0 – Renamed from “dump_contents” to “to_indices”

topDict
¶ Returns the TopologyDict for this topology group.
This is used for the select_bonds method when fetching a certain type of bond.
This is a cached property so will be generated the first time it is accessed.

universe
¶ The Universe that we belong to


class
MDAnalysis.core.topologyobjects.
TopologyObject
(ix, universe, type=None, guessed=False, order=None)[source]¶ Base class for all Topology items.
Defines the behaviour by which Bonds/Angles/etc in MDAnalysis should behave.
New in version 0.9.0.
Changed in version 0.10.0: All TopologyObject now keep track of if they were guessed or not via the
is_guessed
managed property.New in version 0.11.0: Added the value method to return the size of the object
Create a topology object
Parameters:  ix (numpy array) – indices of the Atoms
 universe (MDAnalysis.Universe) –
 type (optional) – Type of the bond
 guessed (optional) – If the Bond is guessed

atoms
¶ Atoms within this Bond

indices
¶ Tuple of indices describing this object
New in version 0.10.0.

type
¶ Type of the bond as a tuple
Note
When comparing types, it is important to consider the reverse of the type too, i.e.:
a.type == b.type or a.type == b.type[::1]

class
MDAnalysis.core.topologyobjects.
UreyBradley
(ix, universe, type=None, guessed=False, order=None)[source]¶ A UreyBradley angle between two
Atom
instances. TwoUreyBradley
instances can be compared with the==
and!=
operators. A UreyBradley angle is equal to another if the same atom numbers are involved.New in version 1.0.0.
Create a topology object
Parameters:  ix (numpy array) – indices of the Atoms
 universe (MDAnalysis.Universe) –
 type (optional) – Type of the bond
 guessed (optional) – If the Bond is guessed

value
(pbc=True)¶ Distance between the atoms.