# 12.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)

  An angle between three `Atom` instances. Atom 2 is the apex of the angle

  Added in version 0.8.

  Changed in version 0.9.0: Now a subclass of `TopologyObject`; now uses `__slots__` and stores atoms in `atoms` 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

  angle(pbc=True)

    Returns the angle in degrees of this Angle.

    Angle between atoms 0 and 2 with apex at 1:

           2
          /
         /
        1------0

    Note

    The numerical precision is typically not better than 4 decimals (and is only tested to 3 decimals).

    Added 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
          /
         /
        1------0

    Note

    The numerical precision is typically not better than 4 decimals (and is only tested to 3 decimals).

    Added 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)

  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` or `False`.

  Changed in version 0.9.0: Now a subclass of `TopologyObject`. Changed class to use `__slots__` and stores atoms in `atoms` 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)

    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

  partner(Atom)
    Returns:

      - the other `Atom` in this

      - bond

  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)

  Coupled-torsion correction map term between five `Atom` instances.

  Added 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)

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

  Added in version 0.8.

  Changed in version 0.9.0: Now a subclass of `TopologyObject`; now uses `__slots__` and stores atoms in `atoms` 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)

    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
                |
          1-----2
         /
        0

    Note

    The numerical precision is typically not better than 4 decimals (and is only tested to 3 decimals).

    Added 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
                |
          1-----2
         /
        0

    Note

    The numerical precision is typically not better than 4 decimals (and is only tested to 3 decimals).

    Added 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)

  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.

  Added 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

  improper()

    Improper dihedral angle in degrees.

    Note

    The numerical precision is typically not better than 4 decimals (and is only tested to 3 decimals).

class MDAnalysis.core.topologyobjects.TopologyDict(topologygroup)

  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. A `TopologyGroup` containing all of a given bond type can be made by querying with the appropriate key. The keys to the `TopologyDict` are a tuple of the atom types that the bond represents and can be viewed using the `keys()` 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 C-C-H angle is considered identical to a H-C-C 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` instances

  Added 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 within `TopologyGroup` instead of accessed from `AtomGroup`.

  keys()

    Returns a list of the different types of available bonds

class MDAnalysis.core.topologyobjects.TopologyGroup(bondidx, universe, btype=None, type=None, guessed=None, order=None)

  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 the `types()` method.

  Alternatively, all the bonds which are in a given `AtomGroup` can be extracted using `atomgroup_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()` and `dihedrals()` methods offer a “shortcut” to the Cython distance calculation functions in `MDAnalysis.lib.distances`.

  TopologyGroups can be combined with TopologyGroups of the same bond type (ie can combine two angle containing TopologyGroups).

  Added in version 0.8.

  Changed in version 0.9.0: Overhauled completely: (1) Added internal `TopologyDict` accessible by the `topDict` attribute. (2) `selectBonds()` allows the `topDict` to be queried with tuple of types. (3) Added `atomgroup_intersection()` to allow bonds which are in a given `AtomGroup` 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. Renamed `dump_contents()` to `to_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)

    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`)

  property atom1

    The first atom in each TopologyObject in this Group

  property atom2

    The second atom in each TopologyObject in this Group

  property atom3

    The third atom in each TopologyObject in this Group

  property atom4

    The fourth atom in each TopologyObject in this Group

  atomgroup_intersection(ag, **kwargs)

    Retrieve all bonds from within this TopologyGroup that are within the AtomGroup which is passed.

    Parameters:

      - ag (AtomGroup) – The :class:~MDAnalysis.core.groups.AtomGroup to intersect with.

      - strict (bool) – Only retrieve bonds which are completely contained within the AtomGroup. [`False`]

    Added in version 0.9.0.

  bonds(pbc=False, result=None)

    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)

    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”

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

  select_bonds(selection)

    Retrieves a selection from this topology group based on types.

  to_indices()

    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”

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

  types()

    Return a list of the bond types in this TopologyGroup

  property universe

    The Universe that we belong to

  values(**kwargs)

    Return the size of each object in this Group

    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

    Added in version 0.11.0.

class MDAnalysis.core.topologyobjects.TopologyObject(ix, universe, type=None, guessed=False, order=None)

  Base class for all Topology items.

  Defines the behaviour by which Bonds/Angles/etc in MDAnalysis should behave.

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

  Added in version 0.11.0: Added the value method to return the size of the object

  Changed in version 2.6.0: Updated Atom ID representation order to match that of AtomGroup indices

  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

  property atoms

    Atoms within this Bond

  property indices

    Tuple of indices describing this object

    Added in version 0.10.0.

  property 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)

  A Urey-Bradley angle between two `Atom` instances. Two `UreyBradley` instances can be compared with the `==` and `!=` operators. A UreyBradley angle is equal to another if the same atom numbers are involved.

  Added 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

  distance(pbc=True)

    Distance between the atoms.

  partner(Atom)
    Returns:

      - the other `Atom` in this

      - interaction

  value(pbc=True)

    Distance between the atoms.