# 12.2.2. Core objects: Containers — `MDAnalysis.core.groups`

The `Universe` instance contains all the particles in the system (which MDAnalysis calls `Atom`). Groups of `atoms` are handled as `AtomGroup` instances. The `AtomGroup` is probably the most important object in MDAnalysis because virtually everything can be accessed through it. `AtomGroup` instances can be easily created (e.g., from an `AtomGroup.select_atoms()` selection or simply by slicing).

For convenience, chemically meaningful groups of `Atoms` such as a `Residue` or a `Segment` (typically a whole molecule or all of the solvent) also exist as containers, as well as groups of these units (`ResidueGroup`, `SegmentGroup`).

## 12.2.2.1. Classes

### 12.2.2.1.1. Collections

class MDAnalysis.core.groups.AtomGroup(*args, **kwargs)

  An ordered array of atoms.

  Can be initiated from an iterable of `Atoms`:

      ag = AtomGroup([Atom1, Atom2, Atom3])

  Or from providing a list of indices and the `Universe` it should belong to:

      ag = AtomGroup([72, 14, 25], u)

  Alternatively, an `AtomGroup` is generated by indexing/slicing another `AtomGroup`, such as the group of all `Atoms` in the `Universe` at `MDAnalysis.core.universe.Universe.atoms`.

  An `AtomGroup` can be indexed and sliced like a list:

      ag[0], ag[-1]

  will return the first and the last `Atom` in the group whereas the slice:

      ag[0:6:2]

  returns an `AtomGroup` of every second element, corresponding to indices 0, 2, and 4.

  It also supports “advanced slicing” when the argument is a `numpy.ndarray` or a `list`:

      aslice = [0, 3, -1, 10, 3]
      ag[aslice]

  will return a new `AtomGroup` of `Atoms` with those indices in the old `AtomGroup`.

  Finally, `AtomGroups` can be created from a selection. See `select_atoms()`.

  Note

  `AtomGroups` originating from a selection are sorted and duplicate elements are removed. This is not true for `AtomGroups` produced by slicing. Thus, slicing can be used when the order of atoms is crucial (for instance, in order to define angles or dihedrals).

  `AtomGroups` can be compared and combined using group operators. For instance, `AtomGroups` can be concatenated using + or `concatenate()`:

      ag_concat = ag1 + ag2  # or ag_concat = ag1.concatenate(ag2)

  When groups are concatenated, the order of the `Atoms` is conserved. If `Atoms` appear several times in one of the groups, the duplicates are kept in the resulting group. On the contrary to `concatenate()`, `union()` treats the `AtomGroups` as sets so that duplicates are removed from the resulting group, and `Atoms` are ordered. The | operator is synomymous to `union()`:

      ag_union = ag1 | ag2  # or ag_union = ag1.union(ag2)

  The opposite operation to `concatenate()` is `subtract()`. This method creates a new group with all the `Atoms` of the group that are not in a given other group; the order of the `Atoms` is kept, and so are duplicates. `difference()` is the set version of `subtract()`. The resulting group is sorted and deduplicated.

  All set methods are listed in the table below. These methods treat the groups as sorted and deduplicated sets of `Atoms`.

  Operation | Equivalent | Result
  --- | --- | ---
  `s.isdisjoint(t)` |  | `True` if `s` and `t` do not share elements
  `s.issubset(t)` |  | test if all elements of `s` are part of `t`
  `s.is_strict_subset(t)` |  | test if all elements of `s` are part of `t`, and `s != t`
  `s.issuperset(t)` |  | test if all elements of `t` are part of `s`
  `s.is_strict_superset(t)` |  | test if all elements of `t` are part of `s`, and `s != t`
  `s.union(t)` | `s | t` | new Group with elements from both `s` and `t`
  `s.intersection(t)` | `s & t` | new Group with elements common to `s` and `t`
  `s.difference(t)` | `s - t` | new Group with elements of `s` that are not in `t`
  `s.symmetric_difference(t)` | `s ^ t` | new Group with elements that are part of `s` or `t` but not both

  The following methods keep the order of the atoms as well as duplicates.

  Operation | Equivalent | Result
  --- | --- | ---
  `len(s)` |  | number of elements (atoms, residues or segment) in the group
  `s == t` |  | test if `s` and `t` contain the same elements in the same order
  `s.concatenate(t)` | `s + t` | new Group with elements from `s` and from `t`
  `s.subtract(t)` |  | new Group with elements from `s` that are not in `t`

  The in operator allows to test if an `Atom` is in the `AtomGroup`.

  `AtomGroup` instances are always bound to a `MDAnalysis.core.universe.Universe`. They cannot exist in isolation.

  During serialization, `AtomGroup` will be pickled with its bound `MDAnalysis.core.universe.Universe` which means after unpickling, a new `MDAnalysis.core.universe.Universe` will be created and be attached by the new `AtomGroup`. If the Universe is serialized with its `AtomGroup`, they will still be bound together afterwards:

      >>> import pickle

      >>> u = mda.Universe(PSF, DCD)
      >>> g = u.atoms

      >>> g_pickled = pickle.loads(pickle.dumps(g))
      >>> print("g_pickled.universe is u: ", u is g_pickled.universe)
      g_pickled.universe is u:  False

      >>> g_pickled, u_pickled = pickle.loads(pickle.dumps((g, u)))
      >>> print("g_pickled.universe is u_pickled: ",
      ...       u_pickled is g_pickled.universe)
      g_pickled.universe is u_pickled:  True

  If multiple `AtomGroup` are bound to the same `MDAnalysis.core.universe.Universe`, they will bound to the same one after serialization:

      >>> import pickle

      >>> u = mda.Universe(PSF, DCD)
      >>> g = u.atoms
      >>> h = u.atoms

      >>> g_pickled = pickle.loads(pickle.dumps(g))
      >>> h_pickled = pickle.loads(pickle.dumps(h))
      >>> print("g_pickled.universe is h_pickled.universe: ",
      ...       g_pickled.universe is h_pickled.universe)
      g_pickled.universe is h_pickled.universe:  False

      >>> g_pickled, h_pickled = pickle.loads(pickle.dumps((g, h)))
      >>> print("g_pickled.universe is h_pickled.universe: ",
      ...       g_pickled.universe is h_pickled.universe)
      g_pickled.universe is h_pickled.universe:  True

  The aforementioned two cases are useful for implementation of parallel analysis base classes. First, you always get an independent `MDAnalysis.core.universe.Universe` in the new process; you don’t have to worry about detaching and reattaching Universe with `AtomGroup`. It also means the state of the new pickled AtomGroup will not be changed with the old Universe, So either the Universe has to pickled together with the AtomGroup (e.g. as a tuple, or as attributes of the object to be pickled), or the implicit new Universe (AtomGroup.Universe) needs to be used. Second, When multiple AtomGroup need to be pickled, they will recognize if they belong to the same Univese or not. Also keep in mind that they need to be pickled together.

  See also

  `MDAnalysis.core.universe.Universe`

  Deprecated since version 0.16.2: Instant selectors of `AtomGroup` will be removed in the 1.0 release.

  Changed in version 1.0.0: Removed instant selectors, use select_atoms(‘name …’) to select atoms by name.

  Changed in version 2.0.0: `AtomGroup` can always be pickled with or without its universe, instead of failing when not finding its anchored universe.

  Changed in version 2.1.0: Indexing an AtomGroup with `None` raises a `TypeError`.

  accumulate(attribute, function=<function sum>, compound='group')

    Accumulates the attribute associated with (compounds of) the group.

    Accumulates the attribute of `Atoms` in the group. The accumulation per `Residue`, `Segment`, molecule, or fragment can be obtained by setting the compound parameter accordingly. By default, the method sums up all attributes per compound, but any function that takes an array and returns an acuumulation over a given axis can be used. For multi-dimensional input arrays, the accumulation is performed along the first axis.

    Parameters:

      - attribute (str or array_like) – Attribute or array of values to accumulate. If a `numpy.ndarray` (or compatible) is provided, its first dimension must have the same length as the total number of atoms in the group.

      - function (callable, optional) – The function performing the accumulation. It must take the array of attribute values to accumulate as its only positional argument and accept an (optional) keyword argument `axis` allowing to specify the axis along which the accumulation is performed.

      - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'},) – optional If `'group'`, the accumulation of all attributes associated with atoms in the group will be returned as a single value. Otherwise, the accumulation of the attributes per `Segment`, `Residue`, molecule, or fragment will be returned as a 1d array. Note that, in any case, only the `Atoms` belonging to the group will be taken into account.

    Returns:

      Acuumulation of the attribute. If compound is set to `'group'`, the first dimension of the attribute array will be contracted to a single value. If compound is set to `'segments'`, `'residues'`, `'molecules'`, or `'fragments'`, the length of the first dimension will correspond to the number of compounds. In all cases, the other dimensions of the returned array will be of the original shape (without the first dimension).

    Return type:

      float or numpy.ndarray

    Raises:

      - ValueError – If the length of a provided attribute array does not correspond to the number of atoms in the group.

      - ValueError – If compound is not one of `'group'`, `'segments'`, `'residues'`, `'molecules'`, or `'fragments'`.

      - NoDataError – If compound is `'molecule'` but the topology doesn’t contain molecule information (molnums), or if compound is `'fragments'` but the topology doesn’t contain bonds.

    Examples

    To find the total charge of a given `AtomGroup`:

        >>> sel = u.select_atoms('prop mass > 4.0')
        >>> sel.accumulate('charges')
        -251.68500316143036

    To find the total mass per residue of all CA `Atoms`:

         >>> sel = u.select_atoms('name CA')
         >>> sel.accumulate('masses', compound='residues')
         array([12.011, 12.011, 12.011, 12.011, 12.011, 12.011, 12.011, 12.011,
                12.011, 12.011, 12.011, 12.011, 12.011, 12.011, 12.011, 12.011,
                12.011, 12.011, 12.011, 12.011, 12.011, 12.011, 12.011, 12.011,
                12.011, 12.011, 12.011, 12.011, 12.011, 12.011, 12.011, 12.011,
                12.011, 12.011, 12.011, 12.011, 12.011, 12.011, 12.011, 12.011,
                ...

    To find the maximum atomic charge per fragment of a given `AtomGroup`:

        >>> import numpy as np
        >>> sel.accumulate('charges', compound="fragments", function=np.max)
        array([0.20999999])

    Added in version 0.20.0.

  align_principal_axis(axis, vector)

    Align principal axis with index axis with vector.

    Parameters:

      - axis ({0, 1, 2}) – Index of the principal axis (0, 1, or 2), as produced by `principal_axes()`.

      - vector (array_like) – Vector to align principal axis with.

    Notes

    To align the long axis of a channel (the first principal axis, i.e. axis = 0) with the z-axis:

        u.atoms.align_principal_axis(0, [0,0,1])
        u.atoms.write("aligned.pdb")

    Note

    This requires the underlying topology to have masses. Otherwise, a `NoDataError` is raised.

  property angle

    This `AtomGroup` represented as an `MDAnalysis.core.topologyobjects.Angle` object

    Raises:

      ValueError – If the `AtomGroup` is not length 3

    Added in version 0.11.0.

  asphericity(wrap=False, unwrap=False, compound='group')

    Asphericity.

    See [Dima2004b] for background information.

    Parameters:

      - wrap (bool, optional) – If `True`, move all atoms within the primary unit cell before calculation. [`False`]

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers.

      - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – Which type of component to keep together during unwrapping.

    Added in version 0.7.7.

    Changed in version 0.8: Added pbc keyword

    Changed in version 0.20.0: Added unwrap and compound parameter

    Changed in version 2.1.0: Renamed pbc kwarg to wrap. pbc is still accepted but is deprecated and will be removed in version 3.0.

    Changed in version 2.5.0: Added calculation for any compound type

    Note

    This requires the underlying topology to have masses. Otherwise, a `NoDataError` is raised.

  asunique(sorted=False)

    Return a `AtomGroup` containing unique `Atoms` only, with optional sorting.

    If the `AtomGroup` is unique, this is the group itself.

    Parameters:

      sorted (bool (optional)) – Whether or not the returned AtomGroup should be sorted by index.

    Returns:

      Unique `AtomGroup`

    Return type:

      `AtomGroup`

    Examples

        >>> import MDAnalysis as mda
        >>> from MDAnalysis.tests.datafiles import PSF, DCD
        >>> u = mda.Universe(PSF, DCD)
        >>> ag = u.atoms[[2, 1, 0]]
        >>> ag2 = ag.asunique(sorted=False)
        >>> ag2 is ag
        True
        >>> ag2.ix
        array([2, 1, 0])
        >>> ag3 = ag.asunique(sorted=True)
        >>> ag3 is ag
        False
        >>> ag3.ix
        array([0, 1, 2])
        >>> u.atoms[[2, 1, 1, 0, 1]].asunique(sorted=False).ix
        array([2, 1, 0])

    Added in version 2.0.0.

  property atoms

    The `AtomGroup` itself.

    See also

    `copy`

      return a true copy of the `AtomGroup`

    Changed in version 0.19.0: In previous versions, this returned a copy, but now the `AtomGroup` itself is returned. This should not affect any code but only speed up calculations.

  bbox(wrap=False)

    Return the bounding box of the selection.

    The lengths A,B,C of the orthorhombic enclosing box are

        L = AtomGroup.bbox()
        A,B,C = L[1] - L[0]

    Parameters:

      wrap (bool, optional) – If `True`, move all `Atoms` to the primary unit cell before calculation. [`False`]

    Returns:

      corners – 2x3 array giving corners of bounding box as `[[xmin, ymin, zmin], [xmax, ymax, zmax]]`.

    Return type:

      numpy.ndarray

    Added in version 0.7.2.

    Changed in version 0.8: Added pbc keyword

    Changed in version 1.0.0: Removed flags affecting default behaviour

    Changed in version 2.1.0: Renamed pbc kwarg to wrap. pbc is still accepted but is deprecated and will be removed in version 3.0.

  property bfactors

    Bfactor alias with warning

    Note

    This requires the underlying topology to have tempfactors. Otherwise, a `NoDataError` is raised.

  property bond

    This `AtomGroup` represented as a `MDAnalysis.core.topologyobjects.Bond` object

    Raises:

      ValueError – If the `AtomGroup` is not length 2

    Added in version 0.11.0.

  bsphere(wrap=False)

    Return the bounding sphere of the selection.

    The sphere is calculated relative to the `center of geometry`.

    Parameters:

      wrap (bool, optional) – If `True`, move all atoms to the primary unit cell before calculation. [`False`]

    Returns:

      - R (float) – Radius of the bounding sphere.

      - center (numpy.ndarray) – Coordinates of the sphere center as `[xcen, ycen, zcen]`.

    Added in version 0.7.3.

    Changed in version 0.8: Added pbc keyword

    Changed in version 2.1.0: Renamed pbc kwarg to wrap. pbc is still accepted but is deprecated and will be removed in version 3.0.

  center(weights, wrap=False, unwrap=False, compound='group')

    Weighted center of (compounds of) the group

    Computes the weighted center of `Atoms` in the group. Weighted centers per `Residue`, `Segment`, molecule, or fragment can be obtained by setting the compound parameter accordingly. If the weights of a compound sum up to zero, the coordinates of that compound’s weighted center will be `nan` (not a number).

    Parameters:

      - weights (array_like or None) – Weights to be used. Setting weights=None is equivalent to passing identical weights for all atoms of the group.

      - wrap (bool, optional) – If `True` and compound is `'group'`, move all atoms to the primary unit cell before calculation. If `True` and compound is not `'group'` the center of each compound will be calculated without moving any `Atoms` to keep the compounds intact. Instead, the resulting position vectors will be moved to the primary unit cell after calculation. Default [`False`].

      - unwrap (bool, optional) –

        If `True`, compounds will be unwrapped before computing their

          centers.

      - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – If `'group'`, the weighted center of all atoms in the group will be returned as a single position vector. Else, the weighted centers of each `Segment`, `Residue`, molecule, or fragment will be returned as an array of position vectors, i.e. a 2d array. Note that, in any case, only the positions of `Atoms` belonging to the group will be taken into account.

    Returns:

      center – Position vector(s) of the weighted center(s) of the group. If compound was set to `'group'`, the output will be a single position vector. If compound was set to `'segments'`, `'residues'`, `'molecules'`, or `'fragments'`, the output will be a 2d array of shape `(n, 3)` where `n` is the number of compounds.

    Return type:

      numpy.ndarray

    Raises:

      - ValueError – If compound is not one of `'group'`, `'segments'`, `'residues'`, `'molecules'`, or `'fragments'`.

      - ValueError – If both ‘wrap’ and ‘unwrap’ set to true.

      - NoDataError – If compound is `'molecule'` but the topology doesn’t contain molecule information (molnums) or if compound is `'fragments'` but the topology doesn’t contain bonds.

    Examples

    To find the center of charge of a given `AtomGroup`:

        >>> sel = u.select_atoms('prop mass > 4.0')
        >>> sel.center(sel.charges)
        array([-0.22925091, -0.04771193, -0.16728489])

    To find the centers of mass per residue of all CA `Atoms`:

         >>> sel = u.select_atoms('name CA')
         >>> sel.center(sel.masses, compound='residues')
         array([[ 11.66462231,   8.39347267,  -8.98323059],
               [ 11.41483879,   5.43442154,  -6.51348448],
               [  8.95975494,   5.61292315,  -3.61323047],
               [  8.29006767,   3.07599092,  -0.79665166],
               [  5.01112604,   3.76389837,   1.130355  ],
               ...

    Changed in version 0.19.0: Added compound parameter

    Changed in version 0.20.0: Added `'molecules'` and `'fragments'` compounds

    Changed in version 0.20.0: Added unwrap parameter

    Changed in version 1.0.0: Removed flags affecting default behaviour

    Changed in version 2.1.0: Renamed pbc kwarg to wrap. pbc is still accepted but is deprecated and will be removed in version 3.0.

  center_of_charge(wrap=False, unwrap=False, compound='group')

    Center of (absolute) charge of (compounds of) the group

    \[\boldsymbol R = \frac{\sum_i \vert q_i \vert \boldsymbol r_i} {\sum_i \vert q_i \vert}\]

    where \(q_i\) is the charge and \(\boldsymbol r_i\) the position of atom \(i\) in the given `MDAnalysis.core.groups.AtomGroup`. Centers of charge per `Residue`, `Segment`, molecule, or fragment can be obtained by setting the compound parameter accordingly. If the charges of a compound sum up to zero, the center of mass coordinates of that compound will be `nan` (not a number).

    Parameters:

      - wrap (bool, optional) – If `True` and compound is `'group'`, move all atoms to the primary unit cell before calculation. If `True` and compound is not `group`, the centers of mass of each compound will be calculated without moving any atoms to keep the compounds intact. Instead, the resulting center-of-mass position vectors will be moved to the primary unit cell after calculation.

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers.

      - compound ({'group', 'segments', 'residues', 'molecules', ) – ‘fragments’}, optional If `'group'`, the center of mass of all atoms in the group will be returned as a single position vector. Otherwise, the centers of mass of each `Segment`, `Residue`, molecule, or fragment will be returned as an array of position vectors, i.e. a 2d array. Note that, in any case, only the positions of `Atoms` belonging to the group will be taken into account.

    Returns:

      center – Position vector(s) of the center(s) of charge of the group. If compound was set to `'group'`, the output will be a single position vector. If compound was set to `'segments'` or `'residues'`, the output will be a 2d coordinate array of shape `(n, 3)` where `n` is the number of compounds.

    Return type:

      numpy.ndarray

    Note

    This method can only be accessed if the underlying topology has information about atomic charges.

    Added in version 2.2.0.

    Note

    This requires the underlying topology to have charges. Otherwise, a `NoDataError` is raised.

  center_of_geometry(wrap=False, unwrap=False, compound='group')

    Center of geometry of (compounds of) the group

    \[\boldsymbol R = \frac{\sum_i \boldsymbol r_i}{\sum_i 1}\]

    where \(\boldsymbol r_i\) of `Atoms` \(i\). Centers of geometry per `Residue` or per `Segment` can be obtained by setting the compound parameter accordingly.

    Parameters:

      - wrap (bool, optional) – If `True` and compound is `'group'`, move all atoms to the primary unit cell before calculation. If `True` and compound is `'segments'` or `'residues'`, the center of each compound will be calculated without moving any `Atoms` to keep the compounds intact. Instead, the resulting position vectors will be moved to the primary unit cell after calculation. Default False.

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers.

      - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – If `'group'`, the center of geometry of all `Atoms` in the group will be returned as a single position vector. Else, the centers of geometry of each `Segment` or `Residue` will be returned as an array of position vectors, i.e. a 2d array. Note that, in any case, only the positions of `Atoms` belonging to the group will be taken into account.

    Returns:

      center – Position vector(s) of the geometric center(s) of the group. If compound was set to `'group'`, the output will be a single position vector. If compound was set to `'segments'` or `'residues'`, the output will be a 2d array of shape `(n, 3)` where `n` is the number of compounds.

    Return type:

      numpy.ndarray

    Changed in version 0.8: Added pbc keyword

    Changed in version 0.19.0: Added compound parameter

    Changed in version 0.20.0: Added `'molecules'` and `'fragments'` compounds

    Changed in version 0.20.0: Added unwrap parameter

    Changed in version 1.0.0: Removed flags affecting default behaviour

    Changed in version 2.1.0: Renamed pbc kwarg to wrap. pbc is still accepted but is deprecated and will be removed in version 3.0.

  center_of_mass(wrap=False, unwrap=False, compound='group')

    Center of mass of (compounds of) the group

    \[\boldsymbol R = \frac{\sum_i m_i \boldsymbol r_i}{\sum m_i}\]

    where \(m_i\) is the mass and \(\boldsymbol r_i\) the position of atom \(i\) in the given `MDAnalysis.core.groups.AtomGroup`. Centers of mass per `Residue`, `Segment`, molecule, or fragment can be obtained by setting the compound parameter accordingly. If the masses of a compound sum up to zero, the center of mass coordinates of that compound will be `nan` (not a number).

    Parameters:

      - wrap (bool, optional) – If `True` and compound is `'group'`, move all atoms to the primary unit cell before calculation. If `True` and compound is not `group`, the centers of mass of each compound will be calculated without moving any atoms to keep the compounds intact. Instead, the resulting center-of-mass position vectors will be moved to the primary unit cell after calculation.

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers.

      - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'},) – optional If `'group'`, the center of mass of all atoms in the group will be returned as a single position vector. Otherwise, the centers of mass of each `Segment`, `Residue`, molecule, or fragment will be returned as an array of position vectors, i.e. a 2d array. Note that, in any case, only the positions of `Atoms` belonging to the group will be taken into account.

    Returns:

      center – Position vector(s) of the center(s) of mass of the group. If compound was set to `'group'`, the output will be a single position vector. If compound was set to `'segments'` or `'residues'`, the output will be a 2d coordinate array of shape `(n, 3)` where `n` is the number of compounds.

    Return type:

      numpy.ndarray

    Note

    This method can only be accessed if the underlying topology has information about atomic masses.

    Changed in version 0.8: Added pbc parameter

    Changed in version 0.19.0: Added compound parameter

    Changed in version 0.20.0: Added `'molecules'` and `'fragments'` compounds; added unwrap parameter

    Changed in version 2.1.0: Renamed pbc kwarg to wrap. pbc is still accepted but is deprecated and will be removed in version 3.0.

    Note

    This requires the underlying topology to have masses. Otherwise, a `NoDataError` is raised.

  centroid(wrap=False, unwrap=False, compound='group')

    Center of geometry of (compounds of) the group

    \[\boldsymbol R = \frac{\sum_i \boldsymbol r_i}{\sum_i 1}\]

    where \(\boldsymbol r_i\) of `Atoms` \(i\). Centers of geometry per `Residue` or per `Segment` can be obtained by setting the compound parameter accordingly.

    Parameters:

      - wrap (bool, optional) – If `True` and compound is `'group'`, move all atoms to the primary unit cell before calculation. If `True` and compound is `'segments'` or `'residues'`, the center of each compound will be calculated without moving any `Atoms` to keep the compounds intact. Instead, the resulting position vectors will be moved to the primary unit cell after calculation. Default False.

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers.

      - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – If `'group'`, the center of geometry of all `Atoms` in the group will be returned as a single position vector. Else, the centers of geometry of each `Segment` or `Residue` will be returned as an array of position vectors, i.e. a 2d array. Note that, in any case, only the positions of `Atoms` belonging to the group will be taken into account.

    Returns:

      center – Position vector(s) of the geometric center(s) of the group. If compound was set to `'group'`, the output will be a single position vector. If compound was set to `'segments'` or `'residues'`, the output will be a 2d array of shape `(n, 3)` where `n` is the number of compounds.

    Return type:

      numpy.ndarray

    Changed in version 0.8: Added pbc keyword

    Changed in version 0.19.0: Added compound parameter

    Changed in version 0.20.0: Added `'molecules'` and `'fragments'` compounds

    Changed in version 0.20.0: Added unwrap parameter

    Changed in version 1.0.0: Removed flags affecting default behaviour

    Changed in version 2.1.0: Renamed pbc kwarg to wrap. pbc is still accepted but is deprecated and will be removed in version 3.0.

  property cmap

    This `AtomGroup` represented as an `MDAnalysis.core.topologyobjects.CMap` object

    Raises:

      ValueError – If the `AtomGroup` is not length 5

    Added in version 1.0.0.

  concatenate(other)

    Concatenate with another Group or Component of the same level.

    Duplicate entries and original order is preserved. It is synomymous to the + operator.

    Parameters:

      other (Group or Component) – Group or Component with other.level same as self.level

    Returns:

      Group with elements of self and other concatenated

    Return type:

      Group

    Example

    The order of the original contents (including duplicates) are preserved when performing a concatenation.

        >>> ag1 = u.select_atoms('name O')
        >>> ag2 = u.select_atoms('name N')
        >>> ag3 = ag1 + ag2  # or ag1.concatenate(ag2)
        >>> ag3[:3].names
        array(['O', 'O', 'O'], dtype=object)
        >>> ag3[-3:].names
        array(['N', 'N', 'N'], dtype=object)

    Added in version 0.16.0.

  convert_to

    alias of `ConverterWrapper`

  copy()

    Get another group identical to this one.

    Added in version 0.19.0.

  difference(other)

    Elements from this Group that do not appear in another

    This method removes duplicate elements and sorts the result. As such, it is different from `subtract()`. `difference()` is synomymous to the - operator.

    Parameters:

      other (Group or Component) – Group or Component with other.level same as self.level

    Returns:

      Group with the elements of self that are not in other, without duplicate elements

    Return type:

      Group

    See also

    `subtract`, `symmetric_difference`

    Added in version 0.16.

  property dihedral

    This `AtomGroup` represented as a `Dihedral` object

    Raises:

      ValueError – If the `AtomGroup` is not length 4

    Added in version 0.11.0.

  property dimensions

    Obtain a copy of the dimensions of the currently loaded Timestep

  dipole_moment(**kwargs)

    Dipole moment of the group or compounds in a group.

    \[\mu = |\boldsymbol{\mu}| = \sqrt{ \sum_{i=1}^{D} \mu^2 }\]

    Where \(D\) is the number of dimensions, in this case 3.

    Computes the dipole moment of `Atoms` in the group. Dipole per `Residue`, `Segment`, molecule, or fragment can be obtained by setting the compound parameter accordingly.

    Note that when there is a net charge, the magnitude of the dipole moment is dependent on the center chosen. See `dipole_vector()`.

    Parameters:

      - wrap (bool, optional) – If `True` and compound is `'group'`, move all atoms to the primary unit cell before calculation. If `True` and compound is not `group`, the centers of mass of each compound will be calculated without moving any atoms to keep the compounds intact.

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers.

      - compound ({'group', 'segments', 'residues', 'molecules', ) – ‘fragments’}, optional If `'group'`, a single dipole vector returns. Otherwise, an array of each `Segment`, `Residue`, molecule, or fragment will be returned as an array of position vectors, i.e. a 2d array. Note that, in any case, only the positions of `Atoms` belonging to the group will be taken into account.

      - center ({'mass', 'charge'}, optional) – Choose whether the dipole vector is calculated at the center of “mass” or the center of “charge”, default is “mass”.

    Returns:

      Dipole moment(s) of (compounds of) the group in \(eÅ\). If compound was set to `'group'`, the output will be a single value. Otherwise, the output will be a 1d array of shape `(n,)` where `n` is the number of compounds.

    Return type:

      numpy.ndarray

    Added in version 2.4.0.

    Note

    This requires the underlying topology to have charges. Otherwise, a `NoDataError` is raised.

  dipole_vector(wrap=False, unwrap=False, compound='group', center='mass')

    Dipole vector of the group.

    \[\boldsymbol{\mu} = \sum_{i=1}^{N} q_{i} ( \mathbf{r}_{i} - \mathbf{r}_{COM} )\]

    Computes the dipole vector of `Atoms` in the group. Dipole vector per `Residue`, `Segment`, molecule, or fragment can be obtained by setting the compound parameter accordingly.

    Note that the magnitude of the dipole moment is independent of the `center` chosen unless the species has a net charge. In the case of a charged group the dipole moment can be later adjusted with:

    \[\boldsymbol{\mu}_{COC} = \boldsymbol{\mu}_{COM} + q_{ag}\mathbf{r}_{COM} - q_{ag}\boldsymbol{r}_{COC}\]

    Where \(\mathbf{r}_{COM}\) is the center of mass and \(\mathbf{r}_{COC}\) is the center of charge.

    Parameters:

      - wrap (bool, optional) – If `True` and compound is `'group'`, move all atoms to the primary unit cell before calculation. If `True` and compound is not `group`, the centers of mass of each compound will be calculated without moving any atoms to keep the compounds intact.

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers.

      - compound ({'group', 'segments', 'residues', 'molecules', ) – ‘fragments’}, optional If `'group'`, a single dipole vector returns. Otherwise, an array of each `Segment`, `Residue`, molecule, or fragment will be returned as an array of position vectors, i.e. a 2d array. Note that, in any case, only the positions of `Atoms` belonging to the group will be taken into account.

      - center ({'mass', 'charge'}, optional) – Choose whether the dipole vector is calculated at the center of “mass” or the center of “charge”, default is “mass”.

    Returns:

      Dipole vector(s) of (compounds of) the group in \(eÅ\). If compound was set to `'group'`, the output will be a single value. Otherwise, the output will be a 1d array of shape `(n,3)` where `n` is the number of compounds.

    Return type:

      numpy.ndarray

    Added in version 2.4.0.

    Note

    This requires the underlying topology to have charges. Otherwise, a `NoDataError` is raised.

  property forces

    Forces on each `Atom` in the `AtomGroup`.

    A `numpy.ndarray` with `shape``=(``n_atoms``, 3)` and `dtype``=numpy.float32`.

    The forces can be changed by assigning an array of the appropriate shape, i.e. either `(``n_atoms``, 3)` to assign individual forces or `(3,)` to assign the same force to all `Atoms` (e.g. `ag.forces = array([0,0,0])` will give all `Atoms` a zero `force`).

    Raises:

      NoDataError – If the `Timestep` does not contain `forces`.

  property fragindices

    The `fragment indices` of all `Atoms` in this `AtomGroup`.

    A `numpy.ndarray` with `shape``=(``n_atoms``,)` and `dtype``=numpy.int64`.

    Added in version 0.20.0.

    Note

    This requires the underlying topology to have bonds. Otherwise, a `NoDataError` is raised.

  property fragments

    Read-only `tuple` of `fragments`.

    Contains all fragments that any `Atom` in this `AtomGroup` is part of.

    A fragment is a `group of atoms` which are interconnected by `Bonds`, i.e., there exists a path along one or more `Bonds` between any pair of `Atoms` within a fragment. Thus, a fragment typically corresponds to a molecule.

    Note

    - The contents of the fragments may extend beyond the contents of this `AtomGroup`.

    Added in version 0.9.0.

    Note

    This requires the underlying topology to have bonds. Otherwise, a `NoDataError` is raised.

  get_connections(typename, outside=True)

    Get bonded connections between atoms as a `TopologyGroup`.

    Parameters:

      - typename (str) – group name. One of {“bonds”, “angles”, “dihedrals”, “impropers”, “ureybradleys”, “cmaps”}

      - outside (bool (optional)) – Whether to include connections involving atoms outside this group.

    Returns:

      - TopologyGroup – containing the bonded group of choice, i.e. bonds, angles, dihedrals, impropers, ureybradleys or cmaps.

      - .. versionadded:: 1.1.0

  groupby(topattrs)

    Group together items in this group according to values of topattr

    Parameters:

      topattrs (str or list) – One or more topology attributes to group components by. Single arguments are passed as a string. Multiple arguments are passed as a list.

    Returns:

      Unique values of the multiple combinations of topology attributes as keys, Groups as values.

    Return type:

      dict

    Example

    To group atoms with the same mass together:

         >>> ag.groupby('masses')
         {32.06: <AtomGroup with 7 atoms>,
          1.008: <AtomGroup with 1685 atoms>,
          12.011: <AtomGroup with 1040 atoms>,
          14.007: <AtomGroup with 289 atoms>,
          15.999: <AtomGroup with 320 atoms>}

    To group atoms with the same residue name and mass together:

         >>> group_dict = ag.groupby(['resnames', 'masses'])
         >>> dict(sorted(group_dict.items()))
         {('ALA', 1.008): <AtomGroup with 95 atoms>,
          ('ALA', 12.011): <AtomGroup with 57 atoms>,
          ('ALA', 14.007): <AtomGroup with 19 atoms>,
          ('ALA', 15.999): <AtomGroup with 19 atoms>,
          ('ARG', 1.008): <AtomGroup with 169 atoms>,
          ...

        >>> ag.groupby(['resnames', 'masses'])['ALA', 15.999]
        <AtomGroup with 19 atoms>

    Added in version 0.16.0.

    Changed in version 0.18.0: The function accepts multiple attributes

  guess_bonds(vdwradii=None, fudge_factor=0.55, lower_bound=0.1)

    Guess bonds, angles, and dihedrals between the atoms in this `AtomGroup` and add them to the underlying `universe`.

    Parameters:

      - vdwradii (dict, optional) – Dict relating atom types: vdw radii

      - fudge_factor (float, optional) – The factor by which atoms must overlap each other to be considered a bond. Larger values will increase the number of bonds found. [0.55]

      - lower_bound (float, optional) – The minimum bond length. All bonds found shorter than this length will be ignored. This is useful for parsing PDB with altloc records where atoms with altloc A and B may be very close together and there should be no chemical bond between them. [0.1]

    See also

    `MDAnalysis.topology.guessers.guess_bonds()`, `MDAnalysis.topology.guessers.guess_angles()`, `MDAnalysis.topology.guessers.guess_dihedrals()`

    Added in version 0.10.0.

    Changed in version 0.20.2: Now applies periodic boundary conditions when guessing bonds.

    Changed in version 2.5.0: Corrected misleading docs, and now allows passing of fudge_factor and lower_bound arguments.

  gyration_moments(wrap=False, unwrap=False, compound='group')

    Moments of the gyration tensor.

    The moments are defined as the eigenvalues of the gyration tensor.

    \[\mathsf{T} = \frac{1}{N} \sum_{i=1}^{N} (\mathbf{r}_\mathrm{i} - \mathbf{r}_\mathrm{COM})(\mathbf{r}_\mathrm{i} - \mathbf{r}_\mathrm{COM})\]

    Where \(\mathbf{r}_\mathrm{COM}\) is the center of mass.

    See [Dima2004a] for background information.

    Parameters:

      - wrap (bool, optional) – If `True`, move all atoms within the primary unit cell before calculation. [`False`]

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers.

      - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – Which type of component to keep together during unwrapping.

    Returns:

      principle_moments_of_gyration – Gyration vector(s) of (compounds of) the group in \(Å^2\). If compound was set to `'group'`, the output will be a single vector of length 3. Otherwise, the output will be a 2D array of shape `(n,3)` where `n` is the number of compounds.

    Return type:

      numpy.ndarray

    Added in version 2.5.0.

    Note

    This requires the underlying topology to have masses. Otherwise, a `NoDataError` is raised.

  property improper

    This `AtomGroup` represented as an `MDAnalysis.core.topologyobjects.ImproperDihedral` object

    Raises:

      ValueError – If the `AtomGroup` is not length 4

    Added in version 0.11.0.

  intersection(other)

    Group of elements which are in both this Group and another

    This method removes duplicate elements and sorts the result. It is synomymous to the & operator.

    Parameters:

      other (Group or Component) – Group or Component with other.level same as self.level

    Returns:

      Group with the common elements of self and other, without duplicate elements

    Return type:

      Group

    Example

    Intersections can be used when the select atoms string would become too complicated. For example to find the water atoms which are within 4.0A of two segments:

        >>> shell1 = u.select_atoms('resname SOL and around 4.0 segid 1')
        >>> shell2 = u.select_atoms('resname SOL and around 4.0 segid 2')
        >>> common = shell1 & shell2  # or shell1.intersection(shell2)

    See also

    `union`

    Added in version 0.16.

  is_strict_subset(other)

    If this Group is a subset of another Group but not identical

    Parameters:

      other (Group or Component) – Group or Component with other.level same as self.level

    Returns:

      `True` if this Group is a strict subset of the other one

    Return type:

      bool

    Added in version 0.16.

  is_strict_superset(other)

    If this Group is a superset of another Group but not identical

    Parameters:

      other (Group or Component) – Group or Component with other.level same as self.level

    Returns:

      `True` if this Group is a strict superset of the other one

    Return type:

      bool

    Added in version 0.16.

  isdisjoint(other)

    If the Group has no elements in common with the other Group

    Parameters:

      other (Group or Component) – Group or Component with other.level same as self.level

    Returns:

      `True` if the two Groups do not have common elements

    Return type:

      bool

    Added in version 0.16.

  issubset(other)

    If all elements of this Group are part of another Group

    Note that an empty group is a subset of any group of the same level.

    Parameters:

      other (Group or Component) – Group or Component with other.level same as self.level

    Returns:

      `True` if this Group is a subset of the other one

    Return type:

      bool

    Added in version 0.16.

  issuperset(other)

    If all elements of another Group are part of this Group

    Parameters:

      other (Group or Component) – Group or Component with other.level same as self.level

    Returns:

      `True` if this Group is a subset of the other one

    Return type:

      bool

    Added in version 0.16.

  property isunique

    Boolean indicating whether all components of the group are unique, i.e., the group contains no duplicates.

    Examples

        >>> ag = u.atoms[[2, 1, 2, 2, 1, 0]]
        >>> ag
        <AtomGroup with 6 atoms>
        >>> ag.isunique
        False
        >>> ag2 = ag.unique
        >>> ag2
        <AtomGroup with 3 atoms>
        >>> ag2.isunique
        True

    See also

    `asunique`

    Added in version 0.19.0.

  property ix

    Unique indices of the components in the Group.

    - If this Group is an `AtomGroup`, these are the indices of the `Atom` instances.

    - If it is a `ResidueGroup`, these are the indices of the `Residue` instances.

    - If it is a `SegmentGroup`, these are the indices of the `Segment` instances.

  property ix_array

    Unique indices of the components in the Group.

    For a Group, `ix_array` is the same as `ix`. This method gives a consistent API between components and groups.

    See also

    `ix`

  moment_of_inertia(wrap=False, unwrap=False, compound='group')

    Moment of inertia tensor relative to center of mass.

    Parameters:

      - wrap (bool, optional) – If `True` and compound is `'group'`, move all atoms to the primary unit cell before calculation. If `True` and compound is not `group`, the centers of mass of each compound will be calculated without moving any atoms to keep the compounds intact. Instead, the resulting center-of-mass position vectors will be moved to the primary unit cell after calculation.

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers and tensor of inertia.

      - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'},) – optional compound determines the behavior of wrap. Note that, in any case, only the positions of `Atoms` belonging to the group will be taken into account.

    Returns:

      moment_of_inertia – Moment of inertia tensor as a 3 x 3 numpy array.

    Return type:

      numpy.ndarray

    Notes

    The moment of inertia tensor \(\mathsf{I}\) is calculated for a group of \(N\) atoms with coordinates \(\mathbf{r}_i,\ 1 \le i \le N\) relative to its center of mass from the relative coordinates

    \[\mathbf{r}'_i = \mathbf{r}_i - \frac{1}{\sum_{i=1}^{N} m_i} \sum_{i=1}^{N} m_i \mathbf{r}_i\]

    as

    \[\mathsf{I} = \sum_{i=1}^{N} m_i \Big[(\mathbf{r}'_i\cdot\mathbf{r}'_i) \sum_{\alpha=1}^{3} \hat{\mathbf{e}}_\alpha \otimes \hat{\mathbf{e}}_\alpha - \mathbf{r}'_i \otimes \mathbf{r}'_i\Big]\]

    where \(\hat{\mathbf{e}}_\alpha\) are Cartesian unit vectors, or in Cartesian coordinates

    \[I_{\alpha,\beta} = \sum_{k=1}^{N} m_k \Big(\big(\sum_{\gamma=1}^3 (x'^{(k)}_{\gamma})^2 \big)\delta_{\alpha,\beta} - x'^{(k)}_{\alpha} x'^{(k)}_{\beta} \Big).\]

    where \(x'^{(k)}_{\alpha}\) are the Cartesian coordinates of the relative coordinates \(\mathbf{r}'_k\).

    Changed in version 0.8: Added pbc keyword

    Changed in version 0.20.0: Added unwrap parameter

    Changed in version 2.1.0: Renamed pbc kwarg to wrap. pbc is still accepted but is deprecated and will be removed in version 3.0.

    Note

    This requires the underlying topology to have masses. Otherwise, a `NoDataError` is raised.

  property n_atoms

    Number of atoms in the `AtomGroup`.

    Equivalent to `len(self)`.

  property n_fragments

    The number of unique `fragments` the `Atoms` of this `AtomGroup` are part of.

    Added in version 0.20.0.

    Note

    This requires the underlying topology to have bonds. Otherwise, a `NoDataError` is raised.

  property n_residues

    Number of unique `Residues` present in the `AtomGroup`.

    Equivalent to `len(self.residues)`.

  property n_segments

    Number of unique segments present in the `AtomGroup`.

    Equivalent to `len(self.segments)`.

  pack_into_box(box=None, inplace=True)

    Shift all `Atoms` in this group to the primary unit cell.

    Parameters:

      - box (array_like) – Box dimensions, can be either orthogonal or triclinic information. Cell dimensions must be in an identical to format to those returned by `MDAnalysis.coordinates.timestep.Timestep.dimensions`, `[lx, ly, lz, alpha, beta, gamma]`. If `None`, uses these timestep dimensions.

      - inplace (bool) – `True` to change coordinates in place.

    Returns:

      coords – Shifted atom coordinates.

    Return type:

      numpy.ndarray

    Notes

    All atoms will be moved so that they lie between 0 and boxlength \(L_i\) in all dimensions, i.e. the lower left corner of the simulation box is taken to be at (0,0,0):

    \[x_i' = x_i - \left\lfloor\frac{x_i}{L_i}\right\rfloor\]

    The default is to take unit cell information from the underlying `Timestep` instance. The optional argument box can be used to provide alternative unit cell information (in the MDAnalysis standard format `[Lx, Ly, Lz, alpha, beta, gamma]`).

    Works with either orthogonal or triclinic box types.

    Note

    `pack_into_box()` is identical to `wrap()` with all default keywords.

    Note

    `AtomGroup.pack_into_box()` is currently faster than `ResidueGroup.pack_into_box()` or `SegmentGroup.pack_into_box()`.

    Added in version 0.8.

  property positions

    Coordinates of the `Atoms` in the `AtomGroup`.

    A `numpy.ndarray` with `shape``=(``n_atoms``, 3)` and `dtype``=numpy.float32`.

    The positions can be changed by assigning an array of the appropriate shape, i.e., either `(``n_atoms``, 3)` to assign individual coordinates, or `(3,)` to assign the same coordinate to all `Atoms` (e.g., `ag.positions = array([0,0,0])` will move all `Atoms` to the origin).

    Note

    Changing positions is not reflected in any files; reading any frame from the `trajectory` will replace the change with that from the file except if the `trajectory` is held in memory, e.g., when the `transfer_to_memory()` method was used.

    Raises:

      NoDataError – If the underlying `Timestep` does not contain `positions`.

  principal_axes(wrap=False)

    Calculate the principal axes from the moment of inertia.

    e1,e2,e3 = AtomGroup.principal_axes()

    The eigenvectors are sorted by eigenvalue, i.e. the first one corresponds to the highest eigenvalue and is thus the first principal axes.

    The eigenvectors form a right-handed coordinate system.

    Parameters:

      wrap (bool, optional) – If `True`, move all atoms within the primary unit cell before calculation. [`False`]

    Returns:

      axis_vectors – 3 x 3 array with `v[0]` as first, `v[1]` as second, and `v[2]` as third eigenvector.

    Return type:

      array

    Changed in version 0.8: Added pbc keyword

    Changed in version 1.0.0: Always return principal axes in right-hand convention.

    Changed in version 2.1.0: Renamed pbc kwarg to wrap. pbc is still accepted but is deprecated and will be removed in version 3.0.

    Note

    This requires the underlying topology to have masses. Otherwise, a `NoDataError` is raised.

  quadrupole_moment(**kwargs)

    Quadrupole moment of the group according to [1].

    \[Q = \sqrt{\frac{2}{3}{\hat{\mathsf{Q}}}:{\hat{\mathsf{Q}}}}\]

    where the quadrupole moment is calculated from the tensor double contraction of the traceless quadropole tensor \(\hat{\mathsf{Q}}\)

    Computes the quadrupole moment of `Atoms` in the group. Quadrupole per `Residue`, `Segment`, molecule, or fragment can be obtained by setting the compound parameter accordingly.

    Note that when there is an unsymmetrical plane in the molecule or group, the magnitude of the quadrupole moment is dependant on the `center` chosen and cannot be translated.

    Parameters:

      - wrap (bool, optional) – If `True` and compound is `'group'`, move all atoms to the primary unit cell before calculation. If `True` and compound is not `group`, the centers of mass of each compound will be calculated without moving any atoms to keep the compounds intact.

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers.

      - compound ({'group', 'segments', 'residues', 'molecules', ) – ‘fragments’}, optional If `'group'`, a single quadrupole value returns. Otherwise, an array of each `Segment`, `Residue`, molecule, or fragment will be returned as an array of position vectors, i.e. a 1d array. Note that, in any case, only the positions of `Atoms` belonging to the group will be taken into account.

      - center ({'mass', 'charge'}, optional) – Choose whether the dipole vector is calculated at the center of “mass” or the center of “charge”, default is “mass”.

    Returns:

      Quadrupole moment(s) of (compounds of) the group in \(eÅ^2\). If compound was set to `'group'`, the output will be a single value. Otherwise, the output will be a 1d array of shape `(n,)` where `n` is the number of compounds.

    Return type:

      numpy.ndarray

    Added in version 2.4.0.

    Note

    This requires the underlying topology to have charges. Otherwise, a `NoDataError` is raised.

  quadrupole_tensor(wrap=False, unwrap=False, compound='group', center='mass')

    Traceless quadrupole tensor of the group or compounds.

    This tensor is first computed as the outer product of vectors from a reference point to some atom, and multiplied by the atomic charge. The tensor of each atom is then summed to produce the quadrupole tensor of the group:

    \[\mathsf{Q} = \sum_{i=1}^{N} q_{i} ( \mathbf{r}_{i} - \mathbf{r}_{COM} ) \otimes ( \mathbf{r}_{i} - \mathbf{r}_{COM} )\]

    The traceless quadrupole tensor, \(\hat{\mathsf{Q}}\), is then taken from:

    \[\hat{\mathsf{Q}} = \frac{3}{2} \mathsf{Q} - \frac{1}{2} tr(\mathsf{Q})\]

    Computes the quadrupole tensor of `Atoms` in the group. Tensor per `Residue`, `Segment`, molecule, or fragment can be obtained by setting the compound parameter accordingly.

    Note that when there is an unsymmetrical plane in the molecule or group, the magnitude of the quadrupole tensor is dependent on the `center` (e.g., \(\mathbf{r}_{COM}\)) chosen and cannot be translated.

    Parameters:

      - wrap (bool, optional) – If `True` and compound is `'group'`, move all atoms to the primary unit cell before calculation. If `True` and compound is not `group`, the centers of mass of each compound will be calculated without moving any atoms to keep the compounds intact.

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers.

      - compound ({'group', 'segments', 'residues', 'molecules', ) – ‘fragments’}, optional If `'group'`, a single quadrupole value returns. Otherwise, an array of each `Segment`, `Residue`, molecule, or fragment will be returned as an array of position vectors, i.e. a 1d array. Note that, in any case, only the positions of `Atoms` belonging to the group will be taken into account.

      - center ({'mass', 'charge'}, optional) – Choose whether the dipole vector is calculated at the center of “mass” or the center of “charge”, default is “mass”.

    Returns:

      Quadrupole tensor(s) of (compounds of) the group in \(eÅ^2\). If compound was set to `'group'`, the output will be a single tensor of shape `(3,3)`. Otherwise, the output will be a 1d array of shape `(n,3,3)` where `n` is the number of compounds.

    Return type:

      numpy.ndarray

    Added in version 2.4.0.

    Note

    This requires the underlying topology to have charges. Otherwise, a `NoDataError` is raised.

  radius_of_gyration(wrap=False, **kwargs)

    Radius of gyration.

    Parameters:

      wrap (bool, optional) – If `True`, move all atoms within the primary unit cell before calculation. [`False`]

    Changed in version 0.8: Added pbc keyword

    Changed in version 2.1.0: Renamed pbc kwarg to wrap. pbc is still accepted but is deprecated and will be removed in version 3.0.

    Note

    This requires the underlying topology to have masses. Otherwise, a `NoDataError` is raised.

  property residues

    A sorted `ResidueGroup` of the unique `Residues` present in the `AtomGroup`.

  rotate(R, point=(0, 0, 0))

    Apply a rotation matrix R to the selection’s coordinates. \(\mathsf{R}\) is a 3x3 orthogonal matrix that transforms a vector \(\mathbf{x} \rightarrow \mathbf{x}'\):

    \[\mathbf{x}' = \mathsf{R}\mathbf{x}\]

    `Atom` coordinates are rotated in-place.

    Parameters:

      - R (array_like) – 3x3 rotation matrix

      - point (array_like, optional) – Center of rotation

    Return type:

      self

    Notes

    By default, rotates about the origin `point=(0, 0, 0)`. To rotate a group `g` around its center of geometry, use `g.rotate(R, point=g.center_of_geometry())`.

    See also

    `rotateby`

      rotate around given axis and angle

    `MDAnalysis.lib.transformations`

      module of all coordinate transforms

  rotateby(angle, axis, point=None)

    Apply a rotation to the selection’s coordinates.

    Parameters:

      - angle (float) – Rotation angle in degrees.

      - axis (array_like) – Rotation axis vector.

      - point (array_like, optional) – Center of rotation. If `None` then the center of geometry of this group is used.

    Return type:

      self

    Notes

    The transformation from current coordinates \(\mathbf{x}\) to new coordinates \(\mathbf{x}'\) is

    \[\mathbf{x}' = \mathsf{R}\,(\mathbf{x}-\mathbf{p}) + \mathbf{p}\]

    where \(\mathsf{R}\) is the rotation by angle around the axis going through point \(\mathbf{p}\).

    See also

    `MDAnalysis.lib.transformations.rotation_matrix`

    `calculate`

      math:mathsf{R}

  property segments

    A sorted `SegmentGroup` of the unique segments present in the `AtomGroup`.

  select_atoms(sel, *othersel, periodic=True, rtol=1e-05, atol=1e-08, updating=False, sorted=True, rdkit_kwargs=None, smarts_kwargs=None, **selgroups)

    Select atoms from within this Group using a selection string.

    Returns an `AtomGroup` sorted according to their index in the topology (this is to ensure that there are no duplicates, which can happen with complicated selections).

    Parameters:

      - sel (str) – string of the selection, eg “name Ca”, see below for possibilities.

      - othersel (iterable of str) – further selections to perform. The results of these selections will be appended onto the results of the first.

      - periodic (bool (optional)) – for geometric selections, whether to account for atoms in different periodic images when searching

      - atol (float, optional) – The absolute tolerance parameter for float comparisons. Passed to :func:`numpy.isclose`.

      - rtol (float, optional) – The relative tolerance parameter for float comparisons. Passed to :func:`numpy.isclose`.

      - updating (bool (optional)) – force the selection to be re evaluated each time the Timestep of the trajectory is changed. See section on Dynamic selections below. [`True`]

      - sorted (bool, optional) – Whether to sort the output AtomGroup by index.

      - rdkit_kwargs (dict (optional)) – Arguments passed to the `RDKitConverter` when using selection based on SMARTS queries

      - smarts_kwargs (dict (optional)) – Arguments passed internally to RDKit’s GetSubstructMatches.

      - **selgroups (keyword arguments of str: AtomGroup (optional)) – when using the “group” keyword in selections, groups are defined by passing them as keyword arguments. See section on preexisting selections below.

    Raises:

      TypeError – If the arbitrary groups passed are not of type `MDAnalysis.core.groups.AtomGroup`

    Examples

    All simple selection listed below support multiple arguments which are implicitly combined with an or operator. For example

        >>> sel = universe.select_atoms('resname MET GLY')
        >>> sel
        <AtomGroup with 245 atoms>

    is equivalent to

        >>> sel = universe.select_atoms('resname MET or resname GLY')
        >>> sel
        <AtomGroup with 245 atoms>

    Will select all atoms with a residue name of either MET or GLY.

    Subselections can be grouped with parentheses.

        >>> sel = universe.select_atoms("segid 4AKE and not ( name H* O* )")
        >>> sel
        <AtomGroup with 1336 atoms>

    Existing `AtomGroup` objects can be passed as named arguments, which will then be available to the selection parser.

        >>> universe.select_atoms("around 10 group notHO", notHO=sel)
        <AtomGroup with 2005 atoms>

    Selections can be set to update automatically on frame change, by setting the updating keyword argument to True. This will return a `UpdatingAtomGroup` which can represent the solvation shell around another object.

         >>> universe.select_atoms("resname SOL and around 2.0 protein",
         ...       updating=True)
         <AtomGroup with 454 atoms, with selection
         'resname SOL and around 2.0 protein' on the entire Universe.>

    Notes

    If exact ordering of atoms is required (for instance, for `angle()` or `dihedral()` calculations) then one supplies selections separately in the required order. Also, when multiple `AtomGroup` instances are concatenated with the `+` operator, then the order of `Atom` instances is preserved and duplicates are not removed.

    See also

    Selection commands

    Selection syntax

    The selection parser understands the following CASE SENSITIVE keywords:

    Simple selections

    > protein, backbone, nucleic, nucleicbackbone

    >   selects all atoms that belong to a standard set of residues; a protein is identfied by a hard-coded set of residue names so it may not work for esoteric residues.

    > segid seg-name

    >   select by segid (as given in the topology), e.g. `segid 4AKE` or `segid DMPC`

    > resid residue-number-range

    >   resid can take a single residue number or a range of numbers. A range consists of two numbers separated by a colon (inclusive) such as `resid 1:5`. A residue number (“resid”) is taken directly from the topology. If icodes are present in the topology, then these will be taken into account. Ie ‘resid 163B’ will only select resid 163 with icode B while ‘resid 163’ will select only residue 163. Range selections will also respect icodes, so ‘resid 162-163B’ will select all residues in 162 and those in 163 up to icode B.

    > resnum resnum-number-range

    >   resnum is the canonical residue number; typically it is set to the residue id in the original PDB structure.

    > resname residue-name

    >   select by residue name, e.g. `resname LYS`

    > name atom-name

    >   select by atom name (as given in the topology). Often, this is force field dependent. Example: `name CA` (for C&alpha; atoms) or `name OW` (for SPC water oxygen)

    > type atom-type

    >   select by atom type; this is either a string or a number and depends on the force field; it is read from the topology file (e.g. the CHARMM PSF file contains numeric atom types). It has non-sensical values when a PDB or GRO file is used as a topology

    > atom seg-name residue-number atom-name

    >   a selector for a single atom consisting of segid resid atomname, e.g. `DMPC 1 C2` selects the C2 carbon of the first residue of the DMPC segment

    > altloc alternative-location

    >   a selection for atoms where alternative locations are available, which is often the case with high-resolution crystal structures e.g. resid 4 and resname ALA and altloc B selects only the atoms of ALA-4 that have an altloc B record.

    > moltype molecule-type

    >   select by molecule type, e.g. `moltype Protein_A`. At the moment, only the TPR format defines the molecule type.

    > record_type record_type

    >   for selecting either ATOM or HETATM from PDB-like files. e.g. `select_atoms('name CA and not record_type HETATM')`

    > smarts SMARTS-query

    >   select atoms using Daylight’s SMARTS queries, e.g. `smarts [#7;R]` to find nitrogen atoms in rings. Requires RDKit. All matches are combined as a single unique match. The smarts selection accepts two sets of key word arguments from select_atoms(): the `rdkit_kwargs` are passed internally to RDKitConverter.convert() and the `smarts_kwargs` are passed to RDKit’s GetSubstructMatches. By default, the useChirality kwarg in `rdkit_kwargs` is set to true and maxMatches in `smarts_kwargs` is `max(1000, 10 * n_atoms)`, where `n_atoms` is either `len(AtomGroup)` or `len(Universe.atoms)`, whichever is applicable. Note that the number of matches can occasionally exceed the default value of maxMatches, causing too few atoms to be returned. If this occurs, a warning will be issued. The problem can be fixed by increasing the value of maxMatches. This behavior may be updated in the future.

    >       >>> universe.select_atoms("smarts C", smarts_kwargs={"maxMatches": 100})
    >       <AtomGroup with 100 atoms>

    > chiral R | S

    >   select a particular stereocenter. e.g. `name C and chirality S` to select only S-chiral carbon atoms. Only `R` and `S` will be possible options but other values will not raise an error.

    > formalcharge formal-charge

    >   select atoms based on their formal charge, e.g. `name O and formalcharge -1` to select all oxygens with a negative 1 formal charge.

    Boolean

    > not

    >   all atoms not in the selection, e.g. `not protein` selects all atoms that aren’t part of a protein

    > and, or

    >   combine two selections according to the rules of boolean algebra, e.g. `protein and not resname ALA LYS` selects all atoms that belong to a protein, but are not in a lysine or alanine residue

    Geometric

    > around distance selection

    >   selects all atoms a certain cutoff away from another selection, e.g. `around 3.5 protein` selects all atoms not belonging to protein that are within 3.5 Angstroms from the protein

    > point x y z distance

    >   selects all atoms within a cutoff of a point in space, make sure coordinate is separated by spaces, e.g. `point 5.0 5.0 5.0 3.5` selects all atoms within 3.5 Angstroms of the coordinate (5.0, 5.0, 5.0)

    > prop [abs] property operator value

    >   selects atoms based on position, using property x, y, or z coordinate. Supports the abs keyword (for absolute value) and the following operators: <, >, <=, >=, ==, !=. For example, `prop z >= 5.0` selects all atoms with z coordinate greater than 5.0; `prop abs z <= 5.0` selects all atoms within -5.0 <= z <= 5.0.

    > sphzone radius selection

    >   Selects all atoms that are within radius of the center of geometry of selection

    > sphlayer inner radius outer radius selection

    >   Similar to sphzone, but also excludes atoms that are within inner radius of the selection COG

    > isolayer inner radius outer radius selection

    >   Similar to sphlayer, but will find layer around all reference layer, creating an iso-surface.

    > cyzone externalRadius zMax zMin selection

    >   selects all atoms within a cylindric zone centered in the center of geometry (COG) of a given selection, e.g. `cyzone 15 4 -8 protein and resid 42` selects the center of geometry of protein and resid 42, and creates a cylinder of external radius 15 centered on the COG. In z, the cylinder extends from 4 above the COG to 8 below. Positive values for zMin, or negative ones for zMax, are allowed.

    > cylayer innerRadius externalRadius zMax zMin selection

    >   selects all atoms within a cylindric layer centered in the center of geometry (COG) of a given selection, e.g. `cylayer 5 10 10 -8 protein` selects the center of geometry of protein, and creates a cylindrical layer of inner radius 5, external radius 10 centered on the COG. In z, the cylinder extends from 10 above the COG to 8 below. Positive values for zMin, or negative ones for zMax, are allowed.

    Connectivity

    > byres selection

    >   selects all atoms that are in the same segment and residue as selection, e.g. specify the subselection after the byres keyword

    > bonded selection

    >   selects all atoms that are bonded to selection eg: `select name H and bonded name O` selects only hydrogens bonded to oxygens

    Index

    > bynum index-range

    >   selects all atoms within a range of (1-based) inclusive indices, e.g. `bynum 1` selects the first atom in the universe; `bynum 5:10` selects atoms 5 through 10 inclusive. All atoms in the `Universe` are consecutively numbered, and the index runs from 1 up to the total number of atoms.

    > index index-range

    >   selects all atoms within a range of (0-based) inclusive indices, e.g. `index 0` selects the first atom in the universe; `index 5:10` selects atoms 6 through 11 inclusive. All atoms in the `Universe` are consecutively numbered, and the index runs from 0 up to the total number of atoms - 1.

    Preexisting selections

    > group group-name

    >   selects the atoms in the `AtomGroup` passed to the function as a keyword argument named group-name. Only the atoms common to group-name and the instance `select_atoms()` was called from will be considered, unless `group` is preceded by the `global` keyword. group-name will be included in the parsing just by comparison of atom indices. This means that it is up to the user to make sure the group-name group was defined in an appropriate `Universe`.

    > global selection

    >   by default, when issuing `select_atoms()` from an `AtomGroup`, selections and subselections are returned intersected with the atoms of that instance. Prefixing a selection term with `global` causes its selection to be returned in its entirety. As an example, the `global` keyword allows for `lipids.select_atoms("around 10 global protein")` — where `lipids` is a group that does not contain any proteins. Were `global` absent, the result would be an empty selection since the `protein` subselection would itself be empty. When issuing `select_atoms()` from a `Universe`, `global` is ignored.

    Dynamic selections

      If `select_atoms()` is invoked with named argument updating set to True, an `UpdatingAtomGroup` instance will be returned, instead of a regular `AtomGroup`. It behaves just like the latter, with the difference that the selection expressions are re-evaluated every time the trajectory frame changes (this happens lazily, only when the `UpdatingAtomGroup` is accessed so that there is no redundant updating going on). Issuing an updating selection from an already updating group will cause later updates to also reflect the updating of the base group. A non-updating selection or a slicing operation made on an `UpdatingAtomGroup` will return a static `AtomGroup`, which will no longer update across frames.

    Changed in version 0.7.4: Added resnum selection.

    Changed in version 0.8.1: Added group and fullgroup selections.

    Changed in version 0.13.0: Added bonded selection.

    Changed in version 0.16.0: Resid selection now takes icodes into account where present.

    Changed in version 0.16.0: Updating selections now possible by setting the updating argument.

    Changed in version 0.17.0: Added moltype and molnum selections.

    Changed in version 0.19.0: Added strict type checking for passed groups. Added periodic kwarg (default True)

    Changed in version 0.19.2: Empty sel string now returns an empty Atom group.

    Changed in version 1.0.0: The `fullgroup` selection has now been removed in favor of the equivalent `global group` selection. Removed flags affecting default behaviour for periodic selections; periodic are now on by default (as with default flags)

    Changed in version 2.0.0: Added the smarts selection. Added atol and rtol keywords to select float values. Added the `sort` keyword. Added rdkit_kwargs to pass parameters to the RDKitConverter.

    Changed in version 2.2.0: Added smarts_kwargs to pass parameters to the RDKit GetSubstructMatch for smarts selection.

  shape_parameter(wrap=False, unwrap=False, compound='group')

    Shape parameter.

    See [Dima2004a] for background information.

    Parameters:

      - wrap (bool, optional) – If `True`, move all atoms within the primary unit cell before calculation. [`False`]

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers.

      - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – Which type of component to keep together during unwrapping.

    Added in version 0.7.7.

    Changed in version 0.8: Added pbc keyword

    Changed in version 2.1.0: Renamed pbc kwarg to wrap. pbc is still accepted but is deprecated and will be removed in version 3.0. Superfluous kwargs were removed.

    Changed in version 2.5.0: Added calculation for any compound type

    Note

    This requires the underlying topology to have masses. Otherwise, a `NoDataError` is raised.

  sort(key='ix', keyfunc=None)

    Returns a sorted `AtomGroup` using a specified attribute as the key.

    Parameters:

      - key (str, optional) – The name of the `AtomGroup` attribute to sort by (e.g. `ids`, `ix`. default= `ix` ).

      - keyfunc (callable, optional) – A function to convert multidimensional arrays to a single dimension. This 1D array will be used as the sort key and is required when sorting with an `AtomGroup` attribute key which has multiple dimensions. Note: this argument is ignored when the attribute is one dimensional.

    Returns:

      Sorted `AtomGroup`.

    Return type:

      `AtomGroup`

    Example

        >>> import MDAnalysis as mda
        >>> from MDAnalysisTests.datafiles import PDB_small
        >>> u = mda.Universe(PDB_small)
        >>> ag = u.atoms[[3, 2, 1, 0]]
        >>> ag.ix
        array([3, 2, 1, 0])
        >>> ag = ag.sort()
        >>> ag.ix
        array([0, 1, 2, 3])
        >>> ag.positions
        array([[-11.921,  26.307,  10.41 ],
               [-11.447,  26.741,   9.595],
               [-12.44 ,  27.042,  10.926],
               [-12.632,  25.619,  10.046]], dtype=float32)
        >>> ag = ag.sort("positions", lambda x: x[:, 1])
        >>> ag.positions
        array([[-12.632,  25.619,  10.046],
               [-11.921,  26.307,  10.41 ],
               [-11.447,  26.741,   9.595],
               [-12.44 ,  27.042,  10.926]], dtype=float32)

    Note

    This uses a stable sort as implemented by numpy.argsort(kind=’stable’).

    Added in version 2.0.0.

  split(level)

    Split `AtomGroup` into a `list` of `AtomGroups` by level.

    Parameters:

      level ({'atom', 'residue', 'molecule', 'segment'})

    Added in version 0.9.0.

    Changed in version 0.17.0: Added the ‘molecule’ level.

  subtract(other)

    Group with elements from this Group that don’t appear in other

    The original order of this group is kept, as well as any duplicate elements. If an element of this Group is duplicated and appears in the other Group or Component, then all the occurences of that element are removed from the returned Group.

    Parameters:

      other (Group or Component) – Group or Component with other.level same as self.level

    Returns:

      Group with the elements of self that are not in other, conserves order and duplicates.

    Return type:

      Group

    Example

    Unlike `difference()` this method will not sort or remove duplicates.

        >>> ag1 = u.atoms[[3, 3, 2, 2, 1, 1]]
        >>> ag2 = u.atoms[2]
        >>> ag3 = ag1.subtract(ag2)
        >>> ag3.indices
        array([3, 3, 1, 1])

    See also

    `concatenate`, `difference`

    Added in version 0.16.

  symmetric_difference(other)

    Group of elements which are only in one of this Group or another

    This method removes duplicate elements and the result is sorted. It is synomym to the ^ operator.

    Parameters:

      other (Group or Component) – Group or Component with other.level same as self.level

    Returns:

      Group with the elements that are in self or in other but not in both, without duplicate elements

    Return type:

      Group

    Example

        >>> ag1 = u.atoms[[0, 1, 5, 3, 3, 2]]
        >>> ag2 = u.atoms[[4, 4, 6, 2, 3, 5]]
        >>> ag3 = ag1 ^ ag2  # or ag1.symmetric_difference(ag2)
        >>> ag3.indices  # 0 and 1 are only in ag1, 4 and 6 are only in ag2
        array([0, 1, 4, 6])

    See also

    `difference`

    Added in version 0.16.

  total_charge(compound='group')

    Total charge of (compounds of) the group.

    Computes the total charge of `Atoms` in the group. Total charges per `Residue`, `Segment`, molecule, or fragment can be obtained by setting the compound parameter accordingly.

    Parameters:

      compound ({'group', 'segments', 'residues', 'molecules', 'fragments'},) – optional If ‘group’, the total charge of all atoms in the group will be returned as a single value. Otherwise, the total charges per `Segment`, `Residue`, molecule, or fragment will be returned as a 1d array. Note that, in any case, only the charges of `Atoms` belonging to the group will be taken into account.

    Returns:

      Total charge of (compounds of) the group. If compound was set to `'group'`, the output will be a single value. Otherwise, the output will be a 1d array of shape `(n,)` where `n` is the number of compounds.

    Return type:

      float or numpy.ndarray

    Changed in version 0.20.0: Added compound parameter

    Note

    This requires the underlying topology to have charges. Otherwise, a `NoDataError` is raised.

  total_mass(compound='group')

    Total mass of (compounds of) the group.

    Computes the total mass of `Atoms` in the group. Total masses per `Residue`, `Segment`, molecule, or fragment can be obtained by setting the compound parameter accordingly.

    Parameters:

      compound ({'group', 'segments', 'residues', 'molecules', 'fragments'},) – optional If `'group'`, the total mass of all atoms in the group will be returned as a single value. Otherwise, the total masses per `Segment`, `Residue`, molecule, or fragment will be returned as a 1d array. Note that, in any case, only the masses of `Atoms` belonging to the group will be taken into account.

    Returns:

      Total mass of (compounds of) the group. If compound was set to `'group'`, the output will be a single value. Otherwise, the output will be a 1d array of shape `(n,)` where `n` is the number of compounds.

    Return type:

      float or numpy.ndarray

    Changed in version 0.20.0: Added compound parameter

    Note

    This requires the underlying topology to have masses. Otherwise, a `NoDataError` is raised.

  transform(M)

    Apply homogenous transformation matrix M to the coordinates.

    `Atom` coordinates are rotated and translated in-place.

    Parameters:

      M (array_like) – 4x4 matrix with the rotation in `R = M[:3, :3]` and the translation in `t = M[:3, 3]`.

    Return type:

      self

    See also

    `MDAnalysis.lib.transformations`

      module of all coordinate transforms

    Notes

    The rotation \(\mathsf{R}\) is about the origin and is applied before the translation \(\mathbf{t}\):

    \[\mathbf{x}' = \mathsf{R}\mathbf{x} + \mathbf{t}\]
  translate(t)

    Apply translation vector t to the selection’s coordinates.

    `Atom` coordinates are translated in-place.

    Parameters:

      t (array_like) – vector to translate coordinates with

    Return type:

      self

    See also

    `MDAnalysis.lib.transformations`

      module of all coordinate transforms

    Notes

    The method applies a translation to the `AtomGroup` from current coordinates \(\mathbf{x}\) to new coordinates \(\mathbf{x}'\):

    \[\mathbf{x}' = \mathbf{x} + \mathbf{t}\]
  property ts

    Temporary Timestep that contains the selection coordinates.

    A `Timestep` instance, which can be passed to a trajectory writer.

    If `ts` is modified then these modifications will be present until the frame number changes (which typically happens when the underlying `trajectory` frame changes).

    It is not possible to assign a new `Timestep` to the `AtomGroup.ts` attribute; change attributes of the object.

  union(other)

    Group of elements either in this Group or another

    On the contrary to concatenation, this method sort the elements and removes duplicate ones. It is synomymous to the | operator.

    Parameters:

      other (Group or Component) – Group or Component with other.level same as self.level

    Returns:

      Group with the combined elements of self and other, without duplicate elements

    Return type:

      Group

    Example

    In contrast to `concatenate()`, any duplicates are dropped and the result is sorted.

        >>> ag1 = u.select_atoms('name O')
        >>> ag2 = u.select_atoms('name N')
        >>> ag3 = ag1 | ag2  # or ag1.union(ag2)
        >>> ag3[:3].names
        array(['N', 'O', 'N'], dtype=object)

    See also

    `concatenate`, `intersection`

    Added in version 0.16.

  property unique

    An `AtomGroup` containing sorted and unique `Atoms` only.

    Examples

        >>> import MDAnalysis as mda
        >>> from MDAnalysis.tests.datafiles import PSF, DCD
        >>> u = mda.Universe(PSF, DCD)
        >>> ag = u.atoms[[2, 1, 2, 2, 1, 0]]
        >>> ag
        <AtomGroup with 6 atoms>
        >>> ag.ix
        array([2, 1, 2, 2, 1, 0])
        >>> ag2 = ag.unique
        >>> ag2
        <AtomGroup with 3 atoms>
        >>> ag2.ix
        array([0, 1, 2])
        >>> ag2.unique is ag2
        False

    See also

    `asunique`, ``, ``

    ``

      This function now always returns a copy.

  property universe

    The underlying `Universe` the group belongs to.

  unwrap(compound='fragments', reference='com', inplace=True)

    Move atoms of this group so that bonds within the group’s compounds aren’t split across periodic boundaries.

    This function is most useful when atoms have been packed into the primary unit cell, causing breaks mid-molecule, with the molecule then appearing on either side of the unit cell. This is problematic for operations such as calculating the center of mass of the molecule.

        +-----------+       +-----------+
        |           |       |           |
        | 6       3 |       |         3 | 6
        | !       ! |       |         ! | !
        |-5-8   1-2-|  ==>  |       1-2-|-5-8
        | !       ! |       |         ! | !
        | 7       4 |       |         4 | 7
        |           |       |           |
        +-----------+       +-----------+

    Parameters:

      - compound ({'group', 'segments', 'residues', 'molecules', ) – ‘fragments’}, optional Which type of compound to unwrap. Note that, in any case, all atoms within each compound must be interconnected by bonds, i.e., compounds must correspond to (parts of) molecules.

      - reference ({'com', 'cog', None}, optional) – If `'com'` (center of mass) or `'cog'` (center of geometry), the unwrapped compounds will be shifted so that their individual reference point lies within the primary unit cell. If `None`, no such shift is performed.

      - inplace (bool, optional) – If `True`, coordinates are modified in place.

    Returns:

      coords – Unwrapped atom coordinate array of shape `(n, 3)`.

    Return type:

      numpy.ndarray

    Raises:

      - NoDataError – If compound is `'molecules'` but the underlying topology does not contain molecule information, or if reference is `'com'` but the topology does not contain masses.

      - ValueError – If reference is not one of `'com'`, `'cog'`, or `None`, or if reference is `'com'` and the total mass of any compound is zero.

    Note

    Be aware of the fact that only atoms belonging to the group will be unwrapped! If you want entire molecules to be unwrapped, make sure that all atoms of these molecules are part of the group. An AtomGroup containing all atoms of all fragments in the group `ag` can be created with:

        all_frag_atoms = sum(ag.fragments)

    See also

    `make_whole()`, `wrap()`, `pack_into_box()`, `apply_PBC()`

    Added in version 0.20.0.

  property ureybradley

    This `AtomGroup` represented as an `MDAnalysis.core.topologyobjects.UreyBradley` object

    Raises:

      ValueError – If the `AtomGroup` is not length 2

    Added in version 1.0.0.

  property velocities

    Velocities of the `Atoms` in the `AtomGroup`.

    A `numpy.ndarray` with `shape``=(``n_atoms``, 3)` and `dtype``=numpy.float32`.

    The velocities can be changed by assigning an array of the appropriate shape, i.e. either `(``n_atoms``, 3)` to assign individual velocities or `(3,)` to assign the same velocity to all `Atoms` (e.g. `ag.velocities = array([0,0,0])` will give all `Atoms` zero `velocity`).

    Raises:

      NoDataError – If the underlying `Timestep` does not contain `velocities`.

  wrap(compound='atoms', center='com', box=None, inplace=True)

    Shift the contents of this group back into the primary unit cell according to periodic boundary conditions.

    Specifying a compound will keep the `Atoms` in each compound together during the process. If compound is different from `'atoms'`, each compound as a whole will be shifted so that its center lies within the primary unit cell.

    Parameters:

      - compound ({'atoms', 'group', 'segments', 'residues', 'molecules', ) – ‘fragments’}, optional Which type of compound to keep together during wrapping. Note that, in any case, only the positions of `Atoms` belonging to the group will be taken into account.

      - center ({'com', 'cog'}) – How to define the center of a given group of atoms. If compound is `'atoms'`, this parameter is meaningless and therefore ignored.

      - box (array_like, optional) – The unitcell dimensions of the system, which can be orthogonal or triclinic and must be provided in the same format as returned by `MDAnalysis.coordinates.timestep.Timestep.dimensions`: `[lx, ly, lz, alpha, beta, gamma]`. If `None`, uses the dimensions of the current time step.

      - inplace (bool, optional) – If `True`, coordinates will be changed in place.

    Returns:

      Array of wrapped atom coordinates of dtype np.float32 and shape `(len(self.atoms.n_atoms), 3)`

    Return type:

      numpy.ndarray

    Raises:

      - ValueError – If compound is not one of `'atoms'`, `'group'`, `'segments'`, `'residues'`, `'molecules'`, or `'fragments'`.

      - NoDataError – If compound is `'molecule'` but the topology doesn’t contain molecule information (molnums) or if compound is `'fragments'` but the topology doesn’t contain bonds or if center is `'com'` but the topology doesn’t contain masses.

    Notes

    All atoms of the group will be moved so that the centers of its compounds lie within the primary periodic image. For orthorhombic unit cells, the primary periodic image is defined as the half-open interval \([0,L_i)\) between \(0\) and boxlength \(L_i\) in all dimensions \(i\in\{x,y,z\}\), i.e., the origin of the of the simulation box is taken to be at the origin \((0,0,0)\) of the euclidian coordinate system. A compound center residing at position \(x_i\) in dimension \(i\) will be shifted to \(x_i'\) according to

    \[x_i' = x_i - \left\lfloor\frac{x_i}{L_i}\right\rfloor\,.\]

    When specifying a compound, the translation is calculated based on each compound. The same translation is applied to all atoms within this compound, meaning it will not be broken by the shift. This might however mean that not all atoms of a compound will be inside the unit cell after wrapping, but rather will be the center of the compound. Be aware of the fact that only atoms belonging to the group will be taken into account!

    center allows to define how the center of each group is computed. This can be either `'com'` for center of mass, or `'cog'` for center of geometry.

    box allows a unit cell to be given for the transformation. If not specified, the `dimensions` information from the current `Timestep` will be used.

    Note

    `AtomGroup.wrap()` is currently faster than `ResidueGroup.wrap()` or `SegmentGroup.wrap()`.

    See also

    `pack_into_box()`, `unwrap()`, `MDAnalysis.lib.distances.apply_PBC()`

    Added in version 0.9.2.

    Changed in version 0.20.0: The method only acts on atoms belonging to the group and returns the wrapped positions as a `numpy.ndarray`. Added optional argument inplace.

  write(filename=None, file_format=None, filenamefmt='{trjname}_{frame}', frames=None, **kwargs)

    Write AtomGroup to a file.

    The output can either be a coordinate file or a selection, depending on the format.

    Examples

        >>> ag = u.atoms
        >>> ag.write('selection.ndx')  # Write a gromacs index file
        >>> ag.write('coordinates.pdb')  # Write the current frame as PDB
        >>> # Write the trajectory in XTC format
        >>> ag.write('trajectory.xtc', frames='all')
        >>> # Write every other frame of the trajectory in PBD format
        >>> ag.write('trajectory.pdb', frames=u.trajectory[::2])

    Parameters:

      - filename (str, optional) – `None`: create TRJNAME_FRAME.FORMAT from filenamefmt [`None`]

      - file_format (str, optional) – The name or extension of a coordinate, trajectory, or selection file format such as PDB, CRD, GRO, VMD (tcl), PyMol (pml), Gromacs (ndx) CHARMM (str) or Jmol (spt); case-insensitive [PDB]

      - filenamefmt (str, optional) – format string for default filename; use substitution tokens ‘trjname’ and ‘frame’ [“%(trjname)s_%(frame)d”]

      - bonds (str, optional) – how to handle bond information, especially relevant for PDBs. `"conect"`: write only the CONECT records defined in the original file. `"all"`: write out all bonds, both the original defined and those guessed by MDAnalysis. `None`: do not write out bonds. Default is `"conect"`.

      - frames (array-like or slice or FrameIteratorBase or str, optional) – An ensemble of frames to write. The ensemble can be an list or array of frame indices, a mask of booleans, an instance of `slice`, or the value returned when a trajectory is indexed. By default, frames is set to `None` and only the current frame is written. If frames is set to “all”, then all the frame from trajectory are written.

    Changed in version 0.9.0: Merged with write_selection. This method can now write both selections out.

    Changed in version 0.19.0: Can write multiframe trajectories with the ‘frames’ argument.

class MDAnalysis.core.groups.ResidueGroup(*args, **kwargs)

  ResidueGroup base class.

  This class is used by a `Universe` for generating its Topology-specific `ResidueGroup` class. All the `TopologyAttr` components are obtained from `GroupBase`, so this class only includes ad-hoc methods specific to `ResidueGroups`.

  ResidueGroups can be compared and combined using group operators. See the list of these operators on `GroupBase`.

  Deprecated since version 0.16.2: Instant selectors of Segments will be removed in the 1.0 release.

  Changed in version 1.0.0: Removed instant selectors, use select_atoms instead

  Changed in version 2.1.0: Indexing an ResidueGroup with `None` raises a `TypeError`.

  accumulate(attribute, function=<function sum>, compound='group')

    Accumulates the attribute associated with (compounds of) the group.

    Accumulates the attribute of `Atoms` in the group. The accumulation per `Residue`, `Segment`, molecule, or fragment can be obtained by setting the compound parameter accordingly. By default, the method sums up all attributes per compound, but any function that takes an array and returns an acuumulation over a given axis can be used. For multi-dimensional input arrays, the accumulation is performed along the first axis.

    Parameters:

      - attribute (str or array_like) – Attribute or array of values to accumulate. If a `numpy.ndarray` (or compatible) is provided, its first dimension must have the same length as the total number of atoms in the group.

      - function (callable, optional) – The function performing the accumulation. It must take the array of attribute values to accumulate as its only positional argument and accept an (optional) keyword argument `axis` allowing to specify the axis along which the accumulation is performed.

      - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'},) – optional If `'group'`, the accumulation of all attributes associated with atoms in the group will be returned as a single value. Otherwise, the accumulation of the attributes per `Segment`, `Residue`, molecule, or fragment will be returned as a 1d array. Note that, in any case, only the `Atoms` belonging to the group will be taken into account.

    Returns:

      Acuumulation of the attribute. If compound is set to `'group'`, the first dimension of the attribute array will be contracted to a single value. If compound is set to `'segments'`, `'residues'`, `'molecules'`, or `'fragments'`, the length of the first dimension will correspond to the number of compounds. In all cases, the other dimensions of the returned array will be of the original shape (without the first dimension).

    Return type:

      float or numpy.ndarray

    Raises:

      - ValueError – If the length of a provided attribute array does not correspond to the number of atoms in the group.

      - ValueError – If compound is not one of `'group'`, `'segments'`, `'residues'`, `'molecules'`, or `'fragments'`.

      - NoDataError – If compound is `'molecule'` but the topology doesn’t contain molecule information (molnums), or if compound is `'fragments'` but the topology doesn’t contain bonds.

    Examples

    To find the total charge of a given `AtomGroup`:

        >>> sel = u.select_atoms('prop mass > 4.0')
        >>> sel.accumulate('charges')
        -251.68500316143036

    To find the total mass per residue of all CA `Atoms`:

         >>> sel = u.select_atoms('name CA')
         >>> sel.accumulate('masses', compound='residues')
         array([12.011, 12.011, 12.011, 12.011, 12.011, 12.011, 12.011, 12.011,
                12.011, 12.011, 12.011, 12.011, 12.011, 12.011, 12.011, 12.011,
                12.011, 12.011, 12.011, 12.011, 12.011, 12.011, 12.011, 12.011,
                12.011, 12.011, 12.011, 12.011, 12.011, 12.011, 12.011, 12.011,
                12.011, 12.011, 12.011, 12.011, 12.011, 12.011, 12.011, 12.011,
                ...

    To find the maximum atomic charge per fragment of a given `AtomGroup`:

        >>> import numpy as np
        >>> sel.accumulate('charges', compound="fragments", function=np.max)
        array([0.20999999])

    Added in version 0.20.0.

  align_principal_axis(axis, vector)

    Align principal axis with index axis with vector.

    Parameters:

      - axis ({0, 1, 2}) – Index of the principal axis (0, 1, or 2), as produced by `principal_axes()`.

      - vector (array_like) – Vector to align principal axis with.

    Notes

    To align the long axis of a channel (the first principal axis, i.e. axis = 0) with the z-axis:

        u.atoms.align_principal_axis(0, [0,0,1])
        u.atoms.write("aligned.pdb")

    Note

    This requires the underlying topology to have masses. Otherwise, a `NoDataError` is raised.

  asphericity(wrap=False, unwrap=False, compound='group')

    Asphericity.

    See [Dima2004b] for background information.

    Parameters:

      - wrap (bool, optional) – If `True`, move all atoms within the primary unit cell before calculation. [`False`]

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers.

      - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – Which type of component to keep together during unwrapping.

    Added in version 0.7.7.

    Changed in version 0.8: Added pbc keyword

    Changed in version 0.20.0: Added unwrap and compound parameter

    Changed in version 2.1.0: Renamed pbc kwarg to wrap. pbc is still accepted but is deprecated and will be removed in version 3.0.

    Changed in version 2.5.0: Added calculation for any compound type

    Note

    This requires the underlying topology to have masses. Otherwise, a `NoDataError` is raised.

  asunique(sorted=False)

    Return a `ResidueGroup` containing unique `Residues` only, with optional sorting.

    If the `ResidueGroup` is unique, this is the group itself.

    Parameters:

      sorted (bool (optional)) – Whether or not the returned ResidueGroup should be sorted by resindex.

    Returns:

      Unique `ResidueGroup`

    Return type:

      `ResidueGroup`

    Examples

        >>> rg = u.residues[[2, 1, 2, 2, 1, 0]]
        >>> rg
        <ResidueGroup with 6 residues>
        >>> rg.ix
        array([2, 1, 2, 2, 1, 0])
        >>> rg2 = rg.asunique(sorted=True)
        >>> rg2
        <ResidueGroup with 3 residues>
        >>> rg2.ix
        array([0, 1, 2])
        >>> rg2.asunique() is rg2
        True

    Added in version 2.0.0.

  property atoms

    An `AtomGroup` of `Atoms` present in this `ResidueGroup`.

    The `Atoms` are ordered locally by `Residue` in the `ResidueGroup`. Duplicates are not removed.

  bbox(wrap=False)

    Return the bounding box of the selection.

    The lengths A,B,C of the orthorhombic enclosing box are

        L = AtomGroup.bbox()
        A,B,C = L[1] - L[0]

    Parameters:

      wrap (bool, optional) – If `True`, move all `Atoms` to the primary unit cell before calculation. [`False`]

    Returns:

      corners – 2x3 array giving corners of bounding box as `[[xmin, ymin, zmin], [xmax, ymax, zmax]]`.

    Return type:

      numpy.ndarray

    Added in version 0.7.2.

    Changed in version 0.8: Added pbc keyword

    Changed in version 1.0.0: Removed flags affecting default behaviour

    Changed in version 2.1.0: Renamed pbc kwarg to wrap. pbc is still accepted but is deprecated and will be removed in version 3.0.

  property bfactors

    Bfactor alias with warning

    Note

    This requires the underlying topology to have tempfactors. Otherwise, a `NoDataError` is raised.

  bsphere(wrap=False)

    Return the bounding sphere of the selection.

    The sphere is calculated relative to the `center of geometry`.

    Parameters:

      wrap (bool, optional) – If `True`, move all atoms to the primary unit cell before calculation. [`False`]

    Returns:

      - R (float) – Radius of the bounding sphere.

      - center (numpy.ndarray) – Coordinates of the sphere center as `[xcen, ycen, zcen]`.

    Added in version 0.7.3.

    Changed in version 0.8: Added pbc keyword

    Changed in version 2.1.0: Renamed pbc kwarg to wrap. pbc is still accepted but is deprecated and will be removed in version 3.0.

  center(weights, wrap=False, unwrap=False, compound='group')

    Weighted center of (compounds of) the group

    Computes the weighted center of `Atoms` in the group. Weighted centers per `Residue`, `Segment`, molecule, or fragment can be obtained by setting the compound parameter accordingly. If the weights of a compound sum up to zero, the coordinates of that compound’s weighted center will be `nan` (not a number).

    Parameters:

      - weights (array_like or None) – Weights to be used. Setting weights=None is equivalent to passing identical weights for all atoms of the group.

      - wrap (bool, optional) – If `True` and compound is `'group'`, move all atoms to the primary unit cell before calculation. If `True` and compound is not `'group'` the center of each compound will be calculated without moving any `Atoms` to keep the compounds intact. Instead, the resulting position vectors will be moved to the primary unit cell after calculation. Default [`False`].

      - unwrap (bool, optional) –

        If `True`, compounds will be unwrapped before computing their

          centers.

      - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – If `'group'`, the weighted center of all atoms in the group will be returned as a single position vector. Else, the weighted centers of each `Segment`, `Residue`, molecule, or fragment will be returned as an array of position vectors, i.e. a 2d array. Note that, in any case, only the positions of `Atoms` belonging to the group will be taken into account.

    Returns:

      center – Position vector(s) of the weighted center(s) of the group. If compound was set to `'group'`, the output will be a single position vector. If compound was set to `'segments'`, `'residues'`, `'molecules'`, or `'fragments'`, the output will be a 2d array of shape `(n, 3)` where `n` is the number of compounds.

    Return type:

      numpy.ndarray

    Raises:

      - ValueError – If compound is not one of `'group'`, `'segments'`, `'residues'`, `'molecules'`, or `'fragments'`.

      - ValueError – If both ‘wrap’ and ‘unwrap’ set to true.

      - NoDataError – If compound is `'molecule'` but the topology doesn’t contain molecule information (molnums) or if compound is `'fragments'` but the topology doesn’t contain bonds.

    Examples

    To find the center of charge of a given `AtomGroup`:

        >>> sel = u.select_atoms('prop mass > 4.0')
        >>> sel.center(sel.charges)
        array([-0.22925091, -0.04771193, -0.16728489])

    To find the centers of mass per residue of all CA `Atoms`:

         >>> sel = u.select_atoms('name CA')
         >>> sel.center(sel.masses, compound='residues')
         array([[ 11.66462231,   8.39347267,  -8.98323059],
               [ 11.41483879,   5.43442154,  -6.51348448],
               [  8.95975494,   5.61292315,  -3.61323047],
               [  8.29006767,   3.07599092,  -0.79665166],
               [  5.01112604,   3.76389837,   1.130355  ],
               ...

    Changed in version 0.19.0: Added compound parameter

    Changed in version 0.20.0: Added `'molecules'` and `'fragments'` compounds

    Changed in version 0.20.0: Added unwrap parameter

    Changed in version 1.0.0: Removed flags affecting default behaviour

    Changed in version 2.1.0: Renamed pbc kwarg to wrap. pbc is still accepted but is deprecated and will be removed in version 3.0.

  center_of_charge(wrap=False, unwrap=False, compound='group')

    Center of (absolute) charge of (compounds of) the group

    \[\boldsymbol R = \frac{\sum_i \vert q_i \vert \boldsymbol r_i} {\sum_i \vert q_i \vert}\]

    where \(q_i\) is the charge and \(\boldsymbol r_i\) the position of atom \(i\) in the given `MDAnalysis.core.groups.AtomGroup`. Centers of charge per `Residue`, `Segment`, molecule, or fragment can be obtained by setting the compound parameter accordingly. If the charges of a compound sum up to zero, the center of mass coordinates of that compound will be `nan` (not a number).

    Parameters:

      - wrap (bool, optional) – If `True` and compound is `'group'`, move all atoms to the primary unit cell before calculation. If `True` and compound is not `group`, the centers of mass of each compound will be calculated without moving any atoms to keep the compounds intact. Instead, the resulting center-of-mass position vectors will be moved to the primary unit cell after calculation.

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers.

      - compound ({'group', 'segments', 'residues', 'molecules', ) – ‘fragments’}, optional If `'group'`, the center of mass of all atoms in the group will be returned as a single position vector. Otherwise, the centers of mass of each `Segment`, `Residue`, molecule, or fragment will be returned as an array of position vectors, i.e. a 2d array. Note that, in any case, only the positions of `Atoms` belonging to the group will be taken into account.

    Returns:

      center – Position vector(s) of the center(s) of charge of the group. If compound was set to `'group'`, the output will be a single position vector. If compound was set to `'segments'` or `'residues'`, the output will be a 2d coordinate array of shape `(n, 3)` where `n` is the number of compounds.

    Return type:

      numpy.ndarray

    Note

    This method can only be accessed if the underlying topology has information about atomic charges.

    Added in version 2.2.0.

    Note

    This requires the underlying topology to have charges. Otherwise, a `NoDataError` is raised.

  center_of_geometry(wrap=False, unwrap=False, compound='group')

    Center of geometry of (compounds of) the group

    \[\boldsymbol R = \frac{\sum_i \boldsymbol r_i}{\sum_i 1}\]

    where \(\boldsymbol r_i\) of `Atoms` \(i\). Centers of geometry per `Residue` or per `Segment` can be obtained by setting the compound parameter accordingly.

    Parameters:

      - wrap (bool, optional) – If `True` and compound is `'group'`, move all atoms to the primary unit cell before calculation. If `True` and compound is `'segments'` or `'residues'`, the center of each compound will be calculated without moving any `Atoms` to keep the compounds intact. Instead, the resulting position vectors will be moved to the primary unit cell after calculation. Default False.

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers.

      - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – If `'group'`, the center of geometry of all `Atoms` in the group will be returned as a single position vector. Else, the centers of geometry of each `Segment` or `Residue` will be returned as an array of position vectors, i.e. a 2d array. Note that, in any case, only the positions of `Atoms` belonging to the group will be taken into account.

    Returns:

      center – Position vector(s) of the geometric center(s) of the group. If compound was set to `'group'`, the output will be a single position vector. If compound was set to `'segments'` or `'residues'`, the output will be a 2d array of shape `(n, 3)` where `n` is the number of compounds.

    Return type:

      numpy.ndarray

    Changed in version 0.8: Added pbc keyword

    Changed in version 0.19.0: Added compound parameter

    Changed in version 0.20.0: Added `'molecules'` and `'fragments'` compounds

    Changed in version 0.20.0: Added unwrap parameter

    Changed in version 1.0.0: Removed flags affecting default behaviour

    Changed in version 2.1.0: Renamed pbc kwarg to wrap. pbc is still accepted but is deprecated and will be removed in version 3.0.

  center_of_mass(wrap=False, unwrap=False, compound='group')

    Center of mass of (compounds of) the group

    \[\boldsymbol R = \frac{\sum_i m_i \boldsymbol r_i}{\sum m_i}\]

    where \(m_i\) is the mass and \(\boldsymbol r_i\) the position of atom \(i\) in the given `MDAnalysis.core.groups.AtomGroup`. Centers of mass per `Residue`, `Segment`, molecule, or fragment can be obtained by setting the compound parameter accordingly. If the masses of a compound sum up to zero, the center of mass coordinates of that compound will be `nan` (not a number).

    Parameters:

      - wrap (bool, optional) – If `True` and compound is `'group'`, move all atoms to the primary unit cell before calculation. If `True` and compound is not `group`, the centers of mass of each compound will be calculated without moving any atoms to keep the compounds intact. Instead, the resulting center-of-mass position vectors will be moved to the primary unit cell after calculation.

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers.

      - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'},) – optional If `'group'`, the center of mass of all atoms in the group will be returned as a single position vector. Otherwise, the centers of mass of each `Segment`, `Residue`, molecule, or fragment will be returned as an array of position vectors, i.e. a 2d array. Note that, in any case, only the positions of `Atoms` belonging to the group will be taken into account.

    Returns:

      center – Position vector(s) of the center(s) of mass of the group. If compound was set to `'group'`, the output will be a single position vector. If compound was set to `'segments'` or `'residues'`, the output will be a 2d coordinate array of shape `(n, 3)` where `n` is the number of compounds.

    Return type:

      numpy.ndarray

    Note

    This method can only be accessed if the underlying topology has information about atomic masses.

    Changed in version 0.8: Added pbc parameter

    Changed in version 0.19.0: Added compound parameter

    Changed in version 0.20.0: Added `'molecules'` and `'fragments'` compounds; added unwrap parameter

    Changed in version 2.1.0: Renamed pbc kwarg to wrap. pbc is still accepted but is deprecated and will be removed in version 3.0.

    Note

    This requires the underlying topology to have masses. Otherwise, a `NoDataError` is raised.

  centroid(wrap=False, unwrap=False, compound='group')

    Center of geometry of (compounds of) the group

    \[\boldsymbol R = \frac{\sum_i \boldsymbol r_i}{\sum_i 1}\]

    where \(\boldsymbol r_i\) of `Atoms` \(i\). Centers of geometry per `Residue` or per `Segment` can be obtained by setting the compound parameter accordingly.

    Parameters:

      - wrap (bool, optional) – If `True` and compound is `'group'`, move all atoms to the primary unit cell before calculation. If `True` and compound is `'segments'` or `'residues'`, the center of each compound will be calculated without moving any `Atoms` to keep the compounds intact. Instead, the resulting position vectors will be moved to the primary unit cell after calculation. Default False.

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers.

      - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – If `'group'`, the center of geometry of all `Atoms` in the group will be returned as a single position vector. Else, the centers of geometry of each `Segment` or `Residue` will be returned as an array of position vectors, i.e. a 2d array. Note that, in any case, only the positions of `Atoms` belonging to the group will be taken into account.

    Returns:

      center – Position vector(s) of the geometric center(s) of the group. If compound was set to `'group'`, the output will be a single position vector. If compound was set to `'segments'` or `'residues'`, the output will be a 2d array of shape `(n, 3)` where `n` is the number of compounds.

    Return type:

      numpy.ndarray

    Changed in version 0.8: Added pbc keyword

    Changed in version 0.19.0: Added compound parameter

    Changed in version 0.20.0: Added `'molecules'` and `'fragments'` compounds

    Changed in version 0.20.0: Added unwrap parameter

    Changed in version 1.0.0: Removed flags affecting default behaviour

    Changed in version 2.1.0: Renamed pbc kwarg to wrap. pbc is still accepted but is deprecated and will be removed in version 3.0.

  chi1_selections(n_name='N', ca_name='CA', cb_name='CB', cg_name='CG CG1 OG OG1 SG')

    Select list of AtomGroups corresponding to the chi1 sidechain dihedral N-CA-CB-CG.

    Parameters:

      - c_name (str (optional)) – name for the backbone C atom

      - ca_name (str (optional)) – name for the alpha-carbon atom

      - cb_name (str (optional)) – name for the beta-carbon atom

      - cg_name (str (optional)) – name for the gamma-carbon atom

    Returns:

      - List of AtomGroups – 4-atom selections in the correct order. If no CB and/or CG is found then the corresponding item in the list is `None`.

      - .. versionadded:: 1.0.0

    Note

    This requires the underlying topology to have names. Otherwise, a `NoDataError` is raised.

  concatenate(other)

    Concatenate with another Group or Component of the same level.

    Duplicate entries and original order is preserved. It is synomymous to the + operator.

    Parameters:

      other (Group or Component) – Group or Component with other.level same as self.level

    Returns:

      Group with elements of self and other concatenated

    Return type:

      Group

    Example

    The order of the original contents (including duplicates) are preserved when performing a concatenation.

        >>> ag1 = u.select_atoms('name O')
        >>> ag2 = u.select_atoms('name N')
        >>> ag3 = ag1 + ag2  # or ag1.concatenate(ag2)
        >>> ag3[:3].names
        array(['O', 'O', 'O'], dtype=object)
        >>> ag3[-3:].names
        array(['N', 'N', 'N'], dtype=object)

    Added in version 0.16.0.

  copy()

    Get another group identical to this one.

    Added in version 0.19.0.

  difference(other)

    Elements from this Group that do not appear in another

    This method removes duplicate elements and sorts the result. As such, it is different from `subtract()`. `difference()` is synomymous to the - operator.

    Parameters:

      other (Group or Component) – Group or Component with other.level same as self.level

    Returns:

      Group with the elements of self that are not in other, without duplicate elements

    Return type:

      Group

    See also

    `subtract`, `symmetric_difference`

    Added in version 0.16.

  property dimensions

    Obtain a copy of the dimensions of the currently loaded Timestep

  dipole_moment(**kwargs)

    Dipole moment of the group or compounds in a group.

    \[\mu = |\boldsymbol{\mu}| = \sqrt{ \sum_{i=1}^{D} \mu^2 }\]

    Where \(D\) is the number of dimensions, in this case 3.

    Computes the dipole moment of `Atoms` in the group. Dipole per `Residue`, `Segment`, molecule, or fragment can be obtained by setting the compound parameter accordingly.

    Note that when there is a net charge, the magnitude of the dipole moment is dependent on the center chosen. See `dipole_vector()`.

    Parameters:

      - wrap (bool, optional) – If `True` and compound is `'group'`, move all atoms to the primary unit cell before calculation. If `True` and compound is not `group`, the centers of mass of each compound will be calculated without moving any atoms to keep the compounds intact.

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers.

      - compound ({'group', 'segments', 'residues', 'molecules', ) – ‘fragments’}, optional If `'group'`, a single dipole vector returns. Otherwise, an array of each `Segment`, `Residue`, molecule, or fragment will be returned as an array of position vectors, i.e. a 2d array. Note that, in any case, only the positions of `Atoms` belonging to the group will be taken into account.

      - center ({'mass', 'charge'}, optional) – Choose whether the dipole vector is calculated at the center of “mass” or the center of “charge”, default is “mass”.

    Returns:

      Dipole moment(s) of (compounds of) the group in \(eÅ\). If compound was set to `'group'`, the output will be a single value. Otherwise, the output will be a 1d array of shape `(n,)` where `n` is the number of compounds.

    Return type:

      numpy.ndarray

    Added in version 2.4.0.

    Note

    This requires the underlying topology to have charges. Otherwise, a `NoDataError` is raised.

  dipole_vector(wrap=False, unwrap=False, compound='group', center='mass')

    Dipole vector of the group.

    \[\boldsymbol{\mu} = \sum_{i=1}^{N} q_{i} ( \mathbf{r}_{i} - \mathbf{r}_{COM} )\]

    Computes the dipole vector of `Atoms` in the group. Dipole vector per `Residue`, `Segment`, molecule, or fragment can be obtained by setting the compound parameter accordingly.

    Note that the magnitude of the dipole moment is independent of the `center` chosen unless the species has a net charge. In the case of a charged group the dipole moment can be later adjusted with:

    \[\boldsymbol{\mu}_{COC} = \boldsymbol{\mu}_{COM} + q_{ag}\mathbf{r}_{COM} - q_{ag}\boldsymbol{r}_{COC}\]

    Where \(\mathbf{r}_{COM}\) is the center of mass and \(\mathbf{r}_{COC}\) is the center of charge.

    Parameters:

      - wrap (bool, optional) – If `True` and compound is `'group'`, move all atoms to the primary unit cell before calculation. If `True` and compound is not `group`, the centers of mass of each compound will be calculated without moving any atoms to keep the compounds intact.

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers.

      - compound ({'group', 'segments', 'residues', 'molecules', ) – ‘fragments’}, optional If `'group'`, a single dipole vector returns. Otherwise, an array of each `Segment`, `Residue`, molecule, or fragment will be returned as an array of position vectors, i.e. a 2d array. Note that, in any case, only the positions of `Atoms` belonging to the group will be taken into account.

      - center ({'mass', 'charge'}, optional) – Choose whether the dipole vector is calculated at the center of “mass” or the center of “charge”, default is “mass”.

    Returns:

      Dipole vector(s) of (compounds of) the group in \(eÅ\). If compound was set to `'group'`, the output will be a single value. Otherwise, the output will be a 1d array of shape `(n,3)` where `n` is the number of compounds.

    Return type:

      numpy.ndarray

    Added in version 2.4.0.

    Note

    This requires the underlying topology to have charges. Otherwise, a `NoDataError` is raised.

  get_connections(typename, outside=True)

    Get bonded connections between atoms as a `TopologyGroup`.

    Parameters:

      - typename (str) – group name. One of {“bonds”, “angles”, “dihedrals”, “impropers”, “ureybradleys”, “cmaps”}

      - outside (bool (optional)) – Whether to include connections involving atoms outside this group.

    Returns:

      - TopologyGroup – containing the bonded group of choice, i.e. bonds, angles, dihedrals, impropers, ureybradleys or cmaps.

      - .. versionadded:: 1.1.0

  groupby(topattrs)

    Group together items in this group according to values of topattr

    Parameters:

      topattrs (str or list) – One or more topology attributes to group components by. Single arguments are passed as a string. Multiple arguments are passed as a list.

    Returns:

      Unique values of the multiple combinations of topology attributes as keys, Groups as values.

    Return type:

      dict

    Example

    To group atoms with the same mass together:

         >>> ag.groupby('masses')
         {32.06: <AtomGroup with 7 atoms>,
          1.008: <AtomGroup with 1685 atoms>,
          12.011: <AtomGroup with 1040 atoms>,
          14.007: <AtomGroup with 289 atoms>,
          15.999: <AtomGroup with 320 atoms>}

    To group atoms with the same residue name and mass together:

         >>> group_dict = ag.groupby(['resnames', 'masses'])
         >>> dict(sorted(group_dict.items()))
         {('ALA', 1.008): <AtomGroup with 95 atoms>,
          ('ALA', 12.011): <AtomGroup with 57 atoms>,
          ('ALA', 14.007): <AtomGroup with 19 atoms>,
          ('ALA', 15.999): <AtomGroup with 19 atoms>,
          ('ARG', 1.008): <AtomGroup with 169 atoms>,
          ...

        >>> ag.groupby(['resnames', 'masses'])['ALA', 15.999]
        <AtomGroup with 19 atoms>

    Added in version 0.16.0.

    Changed in version 0.18.0: The function accepts multiple attributes

  gyration_moments(wrap=False, unwrap=False, compound='group')

    Moments of the gyration tensor.

    The moments are defined as the eigenvalues of the gyration tensor.

    \[\mathsf{T} = \frac{1}{N} \sum_{i=1}^{N} (\mathbf{r}_\mathrm{i} - \mathbf{r}_\mathrm{COM})(\mathbf{r}_\mathrm{i} - \mathbf{r}_\mathrm{COM})\]

    Where \(\mathbf{r}_\mathrm{COM}\) is the center of mass.

    See [Dima2004a] for background information.

    Parameters:

      - wrap (bool, optional) – If `True`, move all atoms within the primary unit cell before calculation. [`False`]

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers.

      - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – Which type of component to keep together during unwrapping.

    Returns:

      principle_moments_of_gyration – Gyration vector(s) of (compounds of) the group in \(Å^2\). If compound was set to `'group'`, the output will be a single vector of length 3. Otherwise, the output will be a 2D array of shape `(n,3)` where `n` is the number of compounds.

    Return type:

      numpy.ndarray

    Added in version 2.5.0.

    Note

    This requires the underlying topology to have masses. Otherwise, a `NoDataError` is raised.

  intersection(other)

    Group of elements which are in both this Group and another

    This method removes duplicate elements and sorts the result. It is synomymous to the & operator.

    Parameters:

      other (Group or Component) – Group or Component with other.level same as self.level

    Returns:

      Group with the common elements of self and other, without duplicate elements

    Return type:

      Group

    Example

    Intersections can be used when the select atoms string would become too complicated. For example to find the water atoms which are within 4.0A of two segments:

        >>> shell1 = u.select_atoms('resname SOL and around 4.0 segid 1')
        >>> shell2 = u.select_atoms('resname SOL and around 4.0 segid 2')
        >>> common = shell1 & shell2  # or shell1.intersection(shell2)

    See also

    `union`

    Added in version 0.16.

  is_strict_subset(other)

    If this Group is a subset of another Group but not identical

    Parameters:

      other (Group or Component) – Group or Component with other.level same as self.level

    Returns:

      `True` if this Group is a strict subset of the other one

    Return type:

      bool

    Added in version 0.16.

  is_strict_superset(other)

    If this Group is a superset of another Group but not identical

    Parameters:

      other (Group or Component) – Group or Component with other.level same as self.level

    Returns:

      `True` if this Group is a strict superset of the other one

    Return type:

      bool

    Added in version 0.16.

  isdisjoint(other)

    If the Group has no elements in common with the other Group

    Parameters:

      other (Group or Component) – Group or Component with other.level same as self.level

    Returns:

      `True` if the two Groups do not have common elements

    Return type:

      bool

    Added in version 0.16.

  issubset(other)

    If all elements of this Group are part of another Group

    Note that an empty group is a subset of any group of the same level.

    Parameters:

      other (Group or Component) – Group or Component with other.level same as self.level

    Returns:

      `True` if this Group is a subset of the other one

    Return type:

      bool

    Added in version 0.16.

  issuperset(other)

    If all elements of another Group are part of this Group

    Parameters:

      other (Group or Component) – Group or Component with other.level same as self.level

    Returns:

      `True` if this Group is a subset of the other one

    Return type:

      bool

    Added in version 0.16.

  property isunique

    Boolean indicating whether all components of the group are unique, i.e., the group contains no duplicates.

    Examples

        >>> ag = u.atoms[[2, 1, 2, 2, 1, 0]]
        >>> ag
        <AtomGroup with 6 atoms>
        >>> ag.isunique
        False
        >>> ag2 = ag.unique
        >>> ag2
        <AtomGroup with 3 atoms>
        >>> ag2.isunique
        True

    See also

    `asunique`

    Added in version 0.19.0.

  property ix

    Unique indices of the components in the Group.

    - If this Group is an `AtomGroup`, these are the indices of the `Atom` instances.

    - If it is a `ResidueGroup`, these are the indices of the `Residue` instances.

    - If it is a `SegmentGroup`, these are the indices of the `Segment` instances.

  property ix_array

    Unique indices of the components in the Group.

    For a Group, `ix_array` is the same as `ix`. This method gives a consistent API between components and groups.

    See also

    `ix`

  moment_of_inertia(wrap=False, unwrap=False, compound='group')

    Moment of inertia tensor relative to center of mass.

    Parameters:

      - wrap (bool, optional) – If `True` and compound is `'group'`, move all atoms to the primary unit cell before calculation. If `True` and compound is not `group`, the centers of mass of each compound will be calculated without moving any atoms to keep the compounds intact. Instead, the resulting center-of-mass position vectors will be moved to the primary unit cell after calculation.

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers and tensor of inertia.

      - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'},) – optional compound determines the behavior of wrap. Note that, in any case, only the positions of `Atoms` belonging to the group will be taken into account.

    Returns:

      moment_of_inertia – Moment of inertia tensor as a 3 x 3 numpy array.

    Return type:

      numpy.ndarray

    Notes

    The moment of inertia tensor \(\mathsf{I}\) is calculated for a group of \(N\) atoms with coordinates \(\mathbf{r}_i,\ 1 \le i \le N\) relative to its center of mass from the relative coordinates

    \[\mathbf{r}'_i = \mathbf{r}_i - \frac{1}{\sum_{i=1}^{N} m_i} \sum_{i=1}^{N} m_i \mathbf{r}_i\]

    as

    \[\mathsf{I} = \sum_{i=1}^{N} m_i \Big[(\mathbf{r}'_i\cdot\mathbf{r}'_i) \sum_{\alpha=1}^{3} \hat{\mathbf{e}}_\alpha \otimes \hat{\mathbf{e}}_\alpha - \mathbf{r}'_i \otimes \mathbf{r}'_i\Big]\]

    where \(\hat{\mathbf{e}}_\alpha\) are Cartesian unit vectors, or in Cartesian coordinates

    \[I_{\alpha,\beta} = \sum_{k=1}^{N} m_k \Big(\big(\sum_{\gamma=1}^3 (x'^{(k)}_{\gamma})^2 \big)\delta_{\alpha,\beta} - x'^{(k)}_{\alpha} x'^{(k)}_{\beta} \Big).\]

    where \(x'^{(k)}_{\alpha}\) are the Cartesian coordinates of the relative coordinates \(\mathbf{r}'_k\).

    Changed in version 0.8: Added pbc keyword

    Changed in version 0.20.0: Added unwrap parameter

    Changed in version 2.1.0: Renamed pbc kwarg to wrap. pbc is still accepted but is deprecated and will be removed in version 3.0.

    Note

    This requires the underlying topology to have masses. Otherwise, a `NoDataError` is raised.

  property n_atoms

    Number of `Atoms` present in this `ResidueGroup`, including duplicate residues (and thus, duplicate atoms).

    Equivalent to `len(self.atoms)`.

  property n_residues

    Number of residues in the `ResidueGroup`.

    Equivalent to `len(self)`.

  property n_segments

    Number of unique segments present in the ResidueGroup.

    Equivalent to `len(self.segments)`.

  omega_selections(c_name='C', n_name='N', ca_name='CA')

    Select list of AtomGroups corresponding to the omega protein backbone dihedral CA-C-N’-CA’.

    omega describes the -C-N- peptide bond. Typically, it is trans (180 degrees) although cis-bonds (0 degrees) are also occasionally observed (especially near Proline).

    Parameters:

      - c_name (str (optional)) – name for the backbone C atom

      - n_name (str (optional)) – name for the backbone N atom

      - ca_name (str (optional)) – name for the alpha-carbon atom

    Returns:

      - List of AtomGroups – 4-atom selections in the correct order. If no C’ found in the previous residue (by resid) then the corresponding item in the list is `None`.

      - .. versionadded:: 1.0.0

    Note

    This requires the underlying topology to have names. Otherwise, a `NoDataError` is raised.

  pack_into_box(box=None, inplace=True)

    Shift all `Atoms` in this group to the primary unit cell.

    Parameters:

      - box (array_like) – Box dimensions, can be either orthogonal or triclinic information. Cell dimensions must be in an identical to format to those returned by `MDAnalysis.coordinates.timestep.Timestep.dimensions`, `[lx, ly, lz, alpha, beta, gamma]`. If `None`, uses these timestep dimensions.

      - inplace (bool) – `True` to change coordinates in place.

    Returns:

      coords – Shifted atom coordinates.

    Return type:

      numpy.ndarray

    Notes

    All atoms will be moved so that they lie between 0 and boxlength \(L_i\) in all dimensions, i.e. the lower left corner of the simulation box is taken to be at (0,0,0):

    \[x_i' = x_i - \left\lfloor\frac{x_i}{L_i}\right\rfloor\]

    The default is to take unit cell information from the underlying `Timestep` instance. The optional argument box can be used to provide alternative unit cell information (in the MDAnalysis standard format `[Lx, Ly, Lz, alpha, beta, gamma]`).

    Works with either orthogonal or triclinic box types.

    Note

    `pack_into_box()` is identical to `wrap()` with all default keywords.

    Note

    `AtomGroup.pack_into_box()` is currently faster than `ResidueGroup.pack_into_box()` or `SegmentGroup.pack_into_box()`.

    Added in version 0.8.

  phi_selections(c_name='C', n_name='N', ca_name='CA')

    Select list of AtomGroups corresponding to the phi protein backbone dihedral C’-N-CA-C.

    Parameters:

      - c_name (str (optional)) – name for the backbone C atom

      - n_name (str (optional)) – name for the backbone N atom

      - ca_name (str (optional)) – name for the alpha-carbon atom

    Returns:

      - list of AtomGroups – 4-atom selections in the correct order. If no C’ found in the previous residue (by resid) then corresponding item in the list is `None`.

      - .. versionadded:: 1.0.0

    Note

    This requires the underlying topology to have names. Otherwise, a `NoDataError` is raised.

  principal_axes(wrap=False)

    Calculate the principal axes from the moment of inertia.

    e1,e2,e3 = AtomGroup.principal_axes()

    The eigenvectors are sorted by eigenvalue, i.e. the first one corresponds to the highest eigenvalue and is thus the first principal axes.

    The eigenvectors form a right-handed coordinate system.

    Parameters:

      wrap (bool, optional) – If `True`, move all atoms within the primary unit cell before calculation. [`False`]

    Returns:

      axis_vectors – 3 x 3 array with `v[0]` as first, `v[1]` as second, and `v[2]` as third eigenvector.

    Return type:

      array

    Changed in version 0.8: Added pbc keyword

    Changed in version 1.0.0: Always return principal axes in right-hand convention.

    Changed in version 2.1.0: Renamed pbc kwarg to wrap. pbc is still accepted but is deprecated and will be removed in version 3.0.

    Note

    This requires the underlying topology to have masses. Otherwise, a `NoDataError` is raised.

  psi_selections(c_name='C', n_name='N', ca_name='CA')

    Select list of AtomGroups corresponding to the psi protein backbone dihedral N-CA-C-N’.

    Parameters:

      - c_name (str (optional)) – name for the backbone C atom

      - n_name (str (optional)) – name for the backbone N atom

      - ca_name (str (optional)) – name for the alpha-carbon atom

    Returns:

      - List of AtomGroups – 4-atom selections in the correct order. If no N’ found in the following residue (by resid) then the corresponding item in the list is `None`.

      - .. versionadded:: 1.0.0

    Note

    This requires the underlying topology to have names. Otherwise, a `NoDataError` is raised.

  quadrupole_moment(**kwargs)

    Quadrupole moment of the group according to [1].

    \[Q = \sqrt{\frac{2}{3}{\hat{\mathsf{Q}}}:{\hat{\mathsf{Q}}}}\]

    where the quadrupole moment is calculated from the tensor double contraction of the traceless quadropole tensor \(\hat{\mathsf{Q}}\)

    Computes the quadrupole moment of `Atoms` in the group. Quadrupole per `Residue`, `Segment`, molecule, or fragment can be obtained by setting the compound parameter accordingly.

    Note that when there is an unsymmetrical plane in the molecule or group, the magnitude of the quadrupole moment is dependant on the `center` chosen and cannot be translated.

    Parameters:

      - wrap (bool, optional) – If `True` and compound is `'group'`, move all atoms to the primary unit cell before calculation. If `True` and compound is not `group`, the centers of mass of each compound will be calculated without moving any atoms to keep the compounds intact.

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers.

      - compound ({'group', 'segments', 'residues', 'molecules', ) – ‘fragments’}, optional If `'group'`, a single quadrupole value returns. Otherwise, an array of each `Segment`, `Residue`, molecule, or fragment will be returned as an array of position vectors, i.e. a 1d array. Note that, in any case, only the positions of `Atoms` belonging to the group will be taken into account.

      - center ({'mass', 'charge'}, optional) – Choose whether the dipole vector is calculated at the center of “mass” or the center of “charge”, default is “mass”.

    Returns:

      Quadrupole moment(s) of (compounds of) the group in \(eÅ^2\). If compound was set to `'group'`, the output will be a single value. Otherwise, the output will be a 1d array of shape `(n,)` where `n` is the number of compounds.

    Return type:

      numpy.ndarray

    Added in version 2.4.0.

    Note

    This requires the underlying topology to have charges. Otherwise, a `NoDataError` is raised.

  quadrupole_tensor(wrap=False, unwrap=False, compound='group', center='mass')

    Traceless quadrupole tensor of the group or compounds.

    This tensor is first computed as the outer product of vectors from a reference point to some atom, and multiplied by the atomic charge. The tensor of each atom is then summed to produce the quadrupole tensor of the group:

    \[\mathsf{Q} = \sum_{i=1}^{N} q_{i} ( \mathbf{r}_{i} - \mathbf{r}_{COM} ) \otimes ( \mathbf{r}_{i} - \mathbf{r}_{COM} )\]

    The traceless quadrupole tensor, \(\hat{\mathsf{Q}}\), is then taken from:

    \[\hat{\mathsf{Q}} = \frac{3}{2} \mathsf{Q} - \frac{1}{2} tr(\mathsf{Q})\]

    Computes the quadrupole tensor of `Atoms` in the group. Tensor per `Residue`, `Segment`, molecule, or fragment can be obtained by setting the compound parameter accordingly.

    Note that when there is an unsymmetrical plane in the molecule or group, the magnitude of the quadrupole tensor is dependent on the `center` (e.g., \(\mathbf{r}_{COM}\)) chosen and cannot be translated.

    Parameters:

      - wrap (bool, optional) – If `True` and compound is `'group'`, move all atoms to the primary unit cell before calculation. If `True` and compound is not `group`, the centers of mass of each compound will be calculated without moving any atoms to keep the compounds intact.

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers.

      - compound ({'group', 'segments', 'residues', 'molecules', ) – ‘fragments’}, optional If `'group'`, a single quadrupole value returns. Otherwise, an array of each `Segment`, `Residue`, molecule, or fragment will be returned as an array of position vectors, i.e. a 1d array. Note that, in any case, only the positions of `Atoms` belonging to the group will be taken into account.

      - center ({'mass', 'charge'}, optional) – Choose whether the dipole vector is calculated at the center of “mass” or the center of “charge”, default is “mass”.

    Returns:

      Quadrupole tensor(s) of (compounds of) the group in \(eÅ^2\). If compound was set to `'group'`, the output will be a single tensor of shape `(3,3)`. Otherwise, the output will be a 1d array of shape `(n,3,3)` where `n` is the number of compounds.

    Return type:

      numpy.ndarray

    Added in version 2.4.0.

    Note

    This requires the underlying topology to have charges. Otherwise, a `NoDataError` is raised.

  radius_of_gyration(wrap=False, **kwargs)

    Radius of gyration.

    Parameters:

      wrap (bool, optional) – If `True`, move all atoms within the primary unit cell before calculation. [`False`]

    Changed in version 0.8: Added pbc keyword

    Changed in version 2.1.0: Renamed pbc kwarg to wrap. pbc is still accepted but is deprecated and will be removed in version 3.0.

    Note

    This requires the underlying topology to have masses. Otherwise, a `NoDataError` is raised.

  property residues

    The `ResidueGroup` itself.

    See also

    `copy`

      return a true copy of the `ResidueGroup`

    Changed in version 0.19.0: In previous versions, this returned a copy, but now the `ResidueGroup` itself is returned. This should not affect any code but only speed up calculations.

  rotate(R, point=(0, 0, 0))

    Apply a rotation matrix R to the selection’s coordinates. \(\mathsf{R}\) is a 3x3 orthogonal matrix that transforms a vector \(\mathbf{x} \rightarrow \mathbf{x}'\):

    \[\mathbf{x}' = \mathsf{R}\mathbf{x}\]

    `Atom` coordinates are rotated in-place.

    Parameters:

      - R (array_like) – 3x3 rotation matrix

      - point (array_like, optional) – Center of rotation

    Return type:

      self

    Notes

    By default, rotates about the origin `point=(0, 0, 0)`. To rotate a group `g` around its center of geometry, use `g.rotate(R, point=g.center_of_geometry())`.

    See also

    `rotateby`

      rotate around given axis and angle

    `MDAnalysis.lib.transformations`

      module of all coordinate transforms

  rotateby(angle, axis, point=None)

    Apply a rotation to the selection’s coordinates.

    Parameters:

      - angle (float) – Rotation angle in degrees.

      - axis (array_like) – Rotation axis vector.

      - point (array_like, optional) – Center of rotation. If `None` then the center of geometry of this group is used.

    Return type:

      self

    Notes

    The transformation from current coordinates \(\mathbf{x}\) to new coordinates \(\mathbf{x}'\) is

    \[\mathbf{x}' = \mathsf{R}\,(\mathbf{x}-\mathbf{p}) + \mathbf{p}\]

    where \(\mathsf{R}\) is the rotation by angle around the axis going through point \(\mathbf{p}\).

    See also

    `MDAnalysis.lib.transformations.rotation_matrix`

    `calculate`

      math:mathsf{R}

  property segments

    Get sorted `SegmentGroup` of the unique segments present in the `ResidueGroup`.

  sequence(**kwargs)

    Returns the amino acid sequence.

    The format of the sequence is selected with the keyword format:

    format | description
    --- | ---
    ‘SeqRecord’ | `Bio.SeqRecord.SeqRecord` (default)
    ‘Seq’ | `Bio.Seq.Seq`
    ‘string’ | string

    The sequence is returned by default (keyword `format = 'SeqRecord'`) as a `Bio.SeqRecord.SeqRecord` instance, which can then be further processed. In this case, all keyword arguments (such as the id string or the name or the description) are directly passed to `Bio.SeqRecord.SeqRecord`.

    If the keyword format is set to `'Seq'`, all kwargs are ignored and a `Bio.Seq.Seq` instance is returned. The difference to the record is that the record also contains metadata and can be directly used as an input for other functions in `Bio`.

    If the keyword format is set to `'string'`, all kwargs are ignored and a Python string is returned.

    Example: Write FASTA file

    Use `Bio.SeqIO.write()`, which takes sequence records:

        import Bio.SeqIO

        # get the sequence record of a protein component of a Universe
        protein = u.select_atoms("protein")
        record = protein.sequence(id="myseq1", name="myprotein")

        Bio.SeqIO.write(record, "single.fasta", "fasta")

    A FASTA file with multiple entries can be written with

        Bio.SeqIO.write([record1, record2, ...], "multi.fasta", "fasta")

    Parameters:

      - format (string, optional) –

        - `"string"`: return sequence as a string of 1-letter codes

        - `"Seq"`: return a `Bio.Seq.Seq` instance

        - `"SeqRecord"`: return a `Bio.SeqRecord.SeqRecord` instance

        > Default is `"SeqRecord"`

      - id (optional) – Sequence ID for SeqRecord (should be different for different sequences)

      - name (optional) – Name of the protein.

      - description (optional) – Short description of the sequence.

      - kwargs (optional) – Any other keyword arguments that are understood by class:Bio.SeqRecord.SeqRecord.

    Raises:

      - ValueError –

      - 1-letter IUPAC protein amino acid code; make sure to only –

      - select protein residues. –

      - TypeError –

      - ImportError –

    Added in version 0.9.0.

    Changed in version 2.7.0: Biopython is now an optional dependency

    Note

    This requires the underlying topology to have resnames. Otherwise, a `NoDataError` is raised.

  shape_parameter(wrap=False, unwrap=False, compound='group')

    Shape parameter.

    See [Dima2004a] for background information.

    Parameters:

      - wrap (bool, optional) – If `True`, move all atoms within the primary unit cell before calculation. [`False`]

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers.

      - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – Which type of component to keep together during unwrapping.

    Added in version 0.7.7.

    Changed in version 0.8: Added pbc keyword

    Changed in version 2.1.0: Renamed pbc kwarg to wrap. pbc is still accepted but is deprecated and will be removed in version 3.0. Superfluous kwargs were removed.

    Changed in version 2.5.0: Added calculation for any compound type

    Note

    This requires the underlying topology to have masses. Otherwise, a `NoDataError` is raised.

  subtract(other)

    Group with elements from this Group that don’t appear in other

    The original order of this group is kept, as well as any duplicate elements. If an element of this Group is duplicated and appears in the other Group or Component, then all the occurences of that element are removed from the returned Group.

    Parameters:

      other (Group or Component) – Group or Component with other.level same as self.level

    Returns:

      Group with the elements of self that are not in other, conserves order and duplicates.

    Return type:

      Group

    Example

    Unlike `difference()` this method will not sort or remove duplicates.

        >>> ag1 = u.atoms[[3, 3, 2, 2, 1, 1]]
        >>> ag2 = u.atoms[2]
        >>> ag3 = ag1.subtract(ag2)
        >>> ag3.indices
        array([3, 3, 1, 1])

    See also

    `concatenate`, `difference`

    Added in version 0.16.

  symmetric_difference(other)

    Group of elements which are only in one of this Group or another

    This method removes duplicate elements and the result is sorted. It is synomym to the ^ operator.

    Parameters:

      other (Group or Component) – Group or Component with other.level same as self.level

    Returns:

      Group with the elements that are in self or in other but not in both, without duplicate elements

    Return type:

      Group

    Example

        >>> ag1 = u.atoms[[0, 1, 5, 3, 3, 2]]
        >>> ag2 = u.atoms[[4, 4, 6, 2, 3, 5]]
        >>> ag3 = ag1 ^ ag2  # or ag1.symmetric_difference(ag2)
        >>> ag3.indices  # 0 and 1 are only in ag1, 4 and 6 are only in ag2
        array([0, 1, 4, 6])

    See also

    `difference`

    Added in version 0.16.

  total_charge(compound='group')

    Total charge of (compounds of) the group.

    Computes the total charge of `Atoms` in the group. Total charges per `Residue`, `Segment`, molecule, or fragment can be obtained by setting the compound parameter accordingly.

    Parameters:

      compound ({'group', 'segments', 'residues', 'molecules', 'fragments'},) – optional If ‘group’, the total charge of all atoms in the group will be returned as a single value. Otherwise, the total charges per `Segment`, `Residue`, molecule, or fragment will be returned as a 1d array. Note that, in any case, only the charges of `Atoms` belonging to the group will be taken into account.

    Returns:

      Total charge of (compounds of) the group. If compound was set to `'group'`, the output will be a single value. Otherwise, the output will be a 1d array of shape `(n,)` where `n` is the number of compounds.

    Return type:

      float or numpy.ndarray

    Changed in version 0.20.0: Added compound parameter

    Note

    This requires the underlying topology to have charges. Otherwise, a `NoDataError` is raised.

  total_mass(compound='group')

    Total mass of (compounds of) the group.

    Computes the total mass of `Atoms` in the group. Total masses per `Residue`, `Segment`, molecule, or fragment can be obtained by setting the compound parameter accordingly.

    Parameters:

      compound ({'group', 'segments', 'residues', 'molecules', 'fragments'},) – optional If `'group'`, the total mass of all atoms in the group will be returned as a single value. Otherwise, the total masses per `Segment`, `Residue`, molecule, or fragment will be returned as a 1d array. Note that, in any case, only the masses of `Atoms` belonging to the group will be taken into account.

    Returns:

      Total mass of (compounds of) the group. If compound was set to `'group'`, the output will be a single value. Otherwise, the output will be a 1d array of shape `(n,)` where `n` is the number of compounds.

    Return type:

      float or numpy.ndarray

    Changed in version 0.20.0: Added compound parameter

    Note

    This requires the underlying topology to have masses. Otherwise, a `NoDataError` is raised.

  transform(M)

    Apply homogenous transformation matrix M to the coordinates.

    `Atom` coordinates are rotated and translated in-place.

    Parameters:

      M (array_like) – 4x4 matrix with the rotation in `R = M[:3, :3]` and the translation in `t = M[:3, 3]`.

    Return type:

      self

    See also

    `MDAnalysis.lib.transformations`

      module of all coordinate transforms

    Notes

    The rotation \(\mathsf{R}\) is about the origin and is applied before the translation \(\mathbf{t}\):

    \[\mathbf{x}' = \mathsf{R}\mathbf{x} + \mathbf{t}\]
  translate(t)

    Apply translation vector t to the selection’s coordinates.

    `Atom` coordinates are translated in-place.

    Parameters:

      t (array_like) – vector to translate coordinates with

    Return type:

      self

    See also

    `MDAnalysis.lib.transformations`

      module of all coordinate transforms

    Notes

    The method applies a translation to the `AtomGroup` from current coordinates \(\mathbf{x}\) to new coordinates \(\mathbf{x}'\):

    \[\mathbf{x}' = \mathbf{x} + \mathbf{t}\]
  union(other)

    Group of elements either in this Group or another

    On the contrary to concatenation, this method sort the elements and removes duplicate ones. It is synomymous to the | operator.

    Parameters:

      other (Group or Component) – Group or Component with other.level same as self.level

    Returns:

      Group with the combined elements of self and other, without duplicate elements

    Return type:

      Group

    Example

    In contrast to `concatenate()`, any duplicates are dropped and the result is sorted.

        >>> ag1 = u.select_atoms('name O')
        >>> ag2 = u.select_atoms('name N')
        >>> ag3 = ag1 | ag2  # or ag1.union(ag2)
        >>> ag3[:3].names
        array(['N', 'O', 'N'], dtype=object)

    See also

    `concatenate`, `intersection`

    Added in version 0.16.

  property unique

    Return a `ResidueGroup` containing sorted and unique `Residues` only.

    Examples

        >>> rg = u.residues[[2, 1, 2, 2, 1, 0]]
        >>> rg
        <ResidueGroup with 6 residues>
        >>> rg.ix
        array([2, 1, 2, 2, 1, 0])
        >>> rg2 = rg.unique
        >>> rg2
        <ResidueGroup with 3 residues>
        >>> rg2.ix
        array([0, 1, 2])
        >>> rg2.unique is rg2
        False

    Added in version 0.16.0.

    Changed in version 0.19.0: If the `ResidueGroup` is already unique, `ResidueGroup.unique` now returns the group itself instead of a copy.

    Changed in version 2.0.0: This function now always returns a copy.

  property universe

    The underlying `Universe` the group belongs to.

  unwrap(compound='fragments', reference='com', inplace=True)

    Move atoms of this group so that bonds within the group’s compounds aren’t split across periodic boundaries.

    This function is most useful when atoms have been packed into the primary unit cell, causing breaks mid-molecule, with the molecule then appearing on either side of the unit cell. This is problematic for operations such as calculating the center of mass of the molecule.

        +-----------+       +-----------+
        |           |       |           |
        | 6       3 |       |         3 | 6
        | !       ! |       |         ! | !
        |-5-8   1-2-|  ==>  |       1-2-|-5-8
        | !       ! |       |         ! | !
        | 7       4 |       |         4 | 7
        |           |       |           |
        +-----------+       +-----------+

    Parameters:

      - compound ({'group', 'segments', 'residues', 'molecules', ) – ‘fragments’}, optional Which type of compound to unwrap. Note that, in any case, all atoms within each compound must be interconnected by bonds, i.e., compounds must correspond to (parts of) molecules.

      - reference ({'com', 'cog', None}, optional) – If `'com'` (center of mass) or `'cog'` (center of geometry), the unwrapped compounds will be shifted so that their individual reference point lies within the primary unit cell. If `None`, no such shift is performed.

      - inplace (bool, optional) – If `True`, coordinates are modified in place.

    Returns:

      coords – Unwrapped atom coordinate array of shape `(n, 3)`.

    Return type:

      numpy.ndarray

    Raises:

      - NoDataError – If compound is `'molecules'` but the underlying topology does not contain molecule information, or if reference is `'com'` but the topology does not contain masses.

      - ValueError – If reference is not one of `'com'`, `'cog'`, or `None`, or if reference is `'com'` and the total mass of any compound is zero.

    Note

    Be aware of the fact that only atoms belonging to the group will be unwrapped! If you want entire molecules to be unwrapped, make sure that all atoms of these molecules are part of the group. An AtomGroup containing all atoms of all fragments in the group `ag` can be created with:

        all_frag_atoms = sum(ag.fragments)

    See also

    `make_whole()`, `wrap()`, `pack_into_box()`, `apply_PBC()`

    Added in version 0.20.0.

  wrap(compound='atoms', center='com', box=None, inplace=True)

    Shift the contents of this group back into the primary unit cell according to periodic boundary conditions.

    Specifying a compound will keep the `Atoms` in each compound together during the process. If compound is different from `'atoms'`, each compound as a whole will be shifted so that its center lies within the primary unit cell.

    Parameters:

      - compound ({'atoms', 'group', 'segments', 'residues', 'molecules', ) – ‘fragments’}, optional Which type of compound to keep together during wrapping. Note that, in any case, only the positions of `Atoms` belonging to the group will be taken into account.

      - center ({'com', 'cog'}) – How to define the center of a given group of atoms. If compound is `'atoms'`, this parameter is meaningless and therefore ignored.

      - box (array_like, optional) – The unitcell dimensions of the system, which can be orthogonal or triclinic and must be provided in the same format as returned by `MDAnalysis.coordinates.timestep.Timestep.dimensions`: `[lx, ly, lz, alpha, beta, gamma]`. If `None`, uses the dimensions of the current time step.

      - inplace (bool, optional) – If `True`, coordinates will be changed in place.

    Returns:

      Array of wrapped atom coordinates of dtype np.float32 and shape `(len(self.atoms.n_atoms), 3)`

    Return type:

      numpy.ndarray

    Raises:

      - ValueError – If compound is not one of `'atoms'`, `'group'`, `'segments'`, `'residues'`, `'molecules'`, or `'fragments'`.

      - NoDataError – If compound is `'molecule'` but the topology doesn’t contain molecule information (molnums) or if compound is `'fragments'` but the topology doesn’t contain bonds or if center is `'com'` but the topology doesn’t contain masses.

    Notes

    All atoms of the group will be moved so that the centers of its compounds lie within the primary periodic image. For orthorhombic unit cells, the primary periodic image is defined as the half-open interval \([0,L_i)\) between \(0\) and boxlength \(L_i\) in all dimensions \(i\in\{x,y,z\}\), i.e., the origin of the of the simulation box is taken to be at the origin \((0,0,0)\) of the euclidian coordinate system. A compound center residing at position \(x_i\) in dimension \(i\) will be shifted to \(x_i'\) according to

    \[x_i' = x_i - \left\lfloor\frac{x_i}{L_i}\right\rfloor\,.\]

    When specifying a compound, the translation is calculated based on each compound. The same translation is applied to all atoms within this compound, meaning it will not be broken by the shift. This might however mean that not all atoms of a compound will be inside the unit cell after wrapping, but rather will be the center of the compound. Be aware of the fact that only atoms belonging to the group will be taken into account!

    center allows to define how the center of each group is computed. This can be either `'com'` for center of mass, or `'cog'` for center of geometry.

    box allows a unit cell to be given for the transformation. If not specified, the `dimensions` information from the current `Timestep` will be used.

    Note

    `AtomGroup.wrap()` is currently faster than `ResidueGroup.wrap()` or `SegmentGroup.wrap()`.

    See also

    `pack_into_box()`, `unwrap()`, `MDAnalysis.lib.distances.apply_PBC()`

    Added in version 0.9.2.

    Changed in version 0.20.0: The method only acts on atoms belonging to the group and returns the wrapped positions as a `numpy.ndarray`. Added optional argument inplace.

class MDAnalysis.core.groups.SegmentGroup(*args, **kwargs)

  `SegmentGroup` base class.

  This class is used by a `Universe` for generating its Topology-specific `SegmentGroup` class. All the `TopologyAttr` components are obtained from `GroupBase`, so this class only includes ad-hoc methods specific to `SegmentGroups`.

  `SegmentGroups` can be compared and combined using group operators. See the list of these operators on `GroupBase`.

  Deprecated since version 0.16.2: Instant selectors of Segments will be removed in the 1.0 release.

  Changed in version 1.0.0: Removed instant selectors, use select_atoms instead

  Changed in version 2.1.0: Indexing an SegmentGroup with `None` raises a `TypeError`.

  accumulate(attribute, function=<function sum>, compound='group')

    Accumulates the attribute associated with (compounds of) the group.

    Accumulates the attribute of `Atoms` in the group. The accumulation per `Residue`, `Segment`, molecule, or fragment can be obtained by setting the compound parameter accordingly. By default, the method sums up all attributes per compound, but any function that takes an array and returns an acuumulation over a given axis can be used. For multi-dimensional input arrays, the accumulation is performed along the first axis.

    Parameters:

      - attribute (str or array_like) – Attribute or array of values to accumulate. If a `numpy.ndarray` (or compatible) is provided, its first dimension must have the same length as the total number of atoms in the group.

      - function (callable, optional) – The function performing the accumulation. It must take the array of attribute values to accumulate as its only positional argument and accept an (optional) keyword argument `axis` allowing to specify the axis along which the accumulation is performed.

      - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'},) – optional If `'group'`, the accumulation of all attributes associated with atoms in the group will be returned as a single value. Otherwise, the accumulation of the attributes per `Segment`, `Residue`, molecule, or fragment will be returned as a 1d array. Note that, in any case, only the `Atoms` belonging to the group will be taken into account.

    Returns:

      Acuumulation of the attribute. If compound is set to `'group'`, the first dimension of the attribute array will be contracted to a single value. If compound is set to `'segments'`, `'residues'`, `'molecules'`, or `'fragments'`, the length of the first dimension will correspond to the number of compounds. In all cases, the other dimensions of the returned array will be of the original shape (without the first dimension).

    Return type:

      float or numpy.ndarray

    Raises:

      - ValueError – If the length of a provided attribute array does not correspond to the number of atoms in the group.

      - ValueError – If compound is not one of `'group'`, `'segments'`, `'residues'`, `'molecules'`, or `'fragments'`.

      - NoDataError – If compound is `'molecule'` but the topology doesn’t contain molecule information (molnums), or if compound is `'fragments'` but the topology doesn’t contain bonds.

    Examples

    To find the total charge of a given `AtomGroup`:

        >>> sel = u.select_atoms('prop mass > 4.0')
        >>> sel.accumulate('charges')
        -251.68500316143036

    To find the total mass per residue of all CA `Atoms`:

         >>> sel = u.select_atoms('name CA')
         >>> sel.accumulate('masses', compound='residues')
         array([12.011, 12.011, 12.011, 12.011, 12.011, 12.011, 12.011, 12.011,
                12.011, 12.011, 12.011, 12.011, 12.011, 12.011, 12.011, 12.011,
                12.011, 12.011, 12.011, 12.011, 12.011, 12.011, 12.011, 12.011,
                12.011, 12.011, 12.011, 12.011, 12.011, 12.011, 12.011, 12.011,
                12.011, 12.011, 12.011, 12.011, 12.011, 12.011, 12.011, 12.011,
                ...

    To find the maximum atomic charge per fragment of a given `AtomGroup`:

        >>> import numpy as np
        >>> sel.accumulate('charges', compound="fragments", function=np.max)
        array([0.20999999])

    Added in version 0.20.0.

  align_principal_axis(axis, vector)

    Align principal axis with index axis with vector.

    Parameters:

      - axis ({0, 1, 2}) – Index of the principal axis (0, 1, or 2), as produced by `principal_axes()`.

      - vector (array_like) – Vector to align principal axis with.

    Notes

    To align the long axis of a channel (the first principal axis, i.e. axis = 0) with the z-axis:

        u.atoms.align_principal_axis(0, [0,0,1])
        u.atoms.write("aligned.pdb")

    Note

    This requires the underlying topology to have masses. Otherwise, a `NoDataError` is raised.

  asphericity(wrap=False, unwrap=False, compound='group')

    Asphericity.

    See [Dima2004b] for background information.

    Parameters:

      - wrap (bool, optional) – If `True`, move all atoms within the primary unit cell before calculation. [`False`]

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers.

      - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – Which type of component to keep together during unwrapping.

    Added in version 0.7.7.

    Changed in version 0.8: Added pbc keyword

    Changed in version 0.20.0: Added unwrap and compound parameter

    Changed in version 2.1.0: Renamed pbc kwarg to wrap. pbc is still accepted but is deprecated and will be removed in version 3.0.

    Changed in version 2.5.0: Added calculation for any compound type

    Note

    This requires the underlying topology to have masses. Otherwise, a `NoDataError` is raised.

  asunique(sorted=False)

    Return a `SegmentGroup` containing unique `Segments` only, with optional sorting.

    If the `SegmentGroup` is unique, this is the group itself.

    Parameters:

      sorted (bool (optional)) – Whether or not the returned SegmentGroup should be sorted by segindex.

    Returns:

      Unique `SegmentGroup`

    Return type:

      `SegmentGroup`

    Examples

        >>> sg = u.segments[[2, 1, 2, 2, 1, 0]]
        >>> sg
        <SegmentGroup with 6 segments>
        >>> sg.ix
        array([2, 1, 2, 2, 1, 0])
        >>> sg2 = sg.asunique(sorted=True)
        >>> sg2
        <SegmentGroup with 3 segments>
        >>> sg2.ix
        array([0, 1, 2])
        >>> sg2.asunique() is sg2
        True

    Added in version 2.0.0.

  property atoms

    An `AtomGroup` of `Atoms` present in this `SegmentGroup`.

    The `Atoms` are ordered locally by `Residue`, which are further ordered by `Segment` in the `SegmentGroup`. Duplicates are not removed.

  bbox(wrap=False)

    Return the bounding box of the selection.

    The lengths A,B,C of the orthorhombic enclosing box are

        L = AtomGroup.bbox()
        A,B,C = L[1] - L[0]

    Parameters:

      wrap (bool, optional) – If `True`, move all `Atoms` to the primary unit cell before calculation. [`False`]

    Returns:

      corners – 2x3 array giving corners of bounding box as `[[xmin, ymin, zmin], [xmax, ymax, zmax]]`.

    Return type:

      numpy.ndarray

    Added in version 0.7.2.

    Changed in version 0.8: Added pbc keyword

    Changed in version 1.0.0: Removed flags affecting default behaviour

    Changed in version 2.1.0: Renamed pbc kwarg to wrap. pbc is still accepted but is deprecated and will be removed in version 3.0.

  property bfactors

    Bfactor alias with warning

    Note

    This requires the underlying topology to have tempfactors. Otherwise, a `NoDataError` is raised.

  bsphere(wrap=False)

    Return the bounding sphere of the selection.

    The sphere is calculated relative to the `center of geometry`.

    Parameters:

      wrap (bool, optional) – If `True`, move all atoms to the primary unit cell before calculation. [`False`]

    Returns:

      - R (float) – Radius of the bounding sphere.

      - center (numpy.ndarray) – Coordinates of the sphere center as `[xcen, ycen, zcen]`.

    Added in version 0.7.3.

    Changed in version 0.8: Added pbc keyword

    Changed in version 2.1.0: Renamed pbc kwarg to wrap. pbc is still accepted but is deprecated and will be removed in version 3.0.

  center(weights, wrap=False, unwrap=False, compound='group')

    Weighted center of (compounds of) the group

    Computes the weighted center of `Atoms` in the group. Weighted centers per `Residue`, `Segment`, molecule, or fragment can be obtained by setting the compound parameter accordingly. If the weights of a compound sum up to zero, the coordinates of that compound’s weighted center will be `nan` (not a number).

    Parameters:

      - weights (array_like or None) – Weights to be used. Setting weights=None is equivalent to passing identical weights for all atoms of the group.

      - wrap (bool, optional) – If `True` and compound is `'group'`, move all atoms to the primary unit cell before calculation. If `True` and compound is not `'group'` the center of each compound will be calculated without moving any `Atoms` to keep the compounds intact. Instead, the resulting position vectors will be moved to the primary unit cell after calculation. Default [`False`].

      - unwrap (bool, optional) –

        If `True`, compounds will be unwrapped before computing their

          centers.

      - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – If `'group'`, the weighted center of all atoms in the group will be returned as a single position vector. Else, the weighted centers of each `Segment`, `Residue`, molecule, or fragment will be returned as an array of position vectors, i.e. a 2d array. Note that, in any case, only the positions of `Atoms` belonging to the group will be taken into account.

    Returns:

      center – Position vector(s) of the weighted center(s) of the group. If compound was set to `'group'`, the output will be a single position vector. If compound was set to `'segments'`, `'residues'`, `'molecules'`, or `'fragments'`, the output will be a 2d array of shape `(n, 3)` where `n` is the number of compounds.

    Return type:

      numpy.ndarray

    Raises:

      - ValueError – If compound is not one of `'group'`, `'segments'`, `'residues'`, `'molecules'`, or `'fragments'`.

      - ValueError – If both ‘wrap’ and ‘unwrap’ set to true.

      - NoDataError – If compound is `'molecule'` but the topology doesn’t contain molecule information (molnums) or if compound is `'fragments'` but the topology doesn’t contain bonds.

    Examples

    To find the center of charge of a given `AtomGroup`:

        >>> sel = u.select_atoms('prop mass > 4.0')
        >>> sel.center(sel.charges)
        array([-0.22925091, -0.04771193, -0.16728489])

    To find the centers of mass per residue of all CA `Atoms`:

         >>> sel = u.select_atoms('name CA')
         >>> sel.center(sel.masses, compound='residues')
         array([[ 11.66462231,   8.39347267,  -8.98323059],
               [ 11.41483879,   5.43442154,  -6.51348448],
               [  8.95975494,   5.61292315,  -3.61323047],
               [  8.29006767,   3.07599092,  -0.79665166],
               [  5.01112604,   3.76389837,   1.130355  ],
               ...

    Changed in version 0.19.0: Added compound parameter

    Changed in version 0.20.0: Added `'molecules'` and `'fragments'` compounds

    Changed in version 0.20.0: Added unwrap parameter

    Changed in version 1.0.0: Removed flags affecting default behaviour

    Changed in version 2.1.0: Renamed pbc kwarg to wrap. pbc is still accepted but is deprecated and will be removed in version 3.0.

  center_of_charge(wrap=False, unwrap=False, compound='group')

    Center of (absolute) charge of (compounds of) the group

    \[\boldsymbol R = \frac{\sum_i \vert q_i \vert \boldsymbol r_i} {\sum_i \vert q_i \vert}\]

    where \(q_i\) is the charge and \(\boldsymbol r_i\) the position of atom \(i\) in the given `MDAnalysis.core.groups.AtomGroup`. Centers of charge per `Residue`, `Segment`, molecule, or fragment can be obtained by setting the compound parameter accordingly. If the charges of a compound sum up to zero, the center of mass coordinates of that compound will be `nan` (not a number).

    Parameters:

      - wrap (bool, optional) – If `True` and compound is `'group'`, move all atoms to the primary unit cell before calculation. If `True` and compound is not `group`, the centers of mass of each compound will be calculated without moving any atoms to keep the compounds intact. Instead, the resulting center-of-mass position vectors will be moved to the primary unit cell after calculation.

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers.

      - compound ({'group', 'segments', 'residues', 'molecules', ) – ‘fragments’}, optional If `'group'`, the center of mass of all atoms in the group will be returned as a single position vector. Otherwise, the centers of mass of each `Segment`, `Residue`, molecule, or fragment will be returned as an array of position vectors, i.e. a 2d array. Note that, in any case, only the positions of `Atoms` belonging to the group will be taken into account.

    Returns:

      center – Position vector(s) of the center(s) of charge of the group. If compound was set to `'group'`, the output will be a single position vector. If compound was set to `'segments'` or `'residues'`, the output will be a 2d coordinate array of shape `(n, 3)` where `n` is the number of compounds.

    Return type:

      numpy.ndarray

    Note

    This method can only be accessed if the underlying topology has information about atomic charges.

    Added in version 2.2.0.

    Note

    This requires the underlying topology to have charges. Otherwise, a `NoDataError` is raised.

  center_of_geometry(wrap=False, unwrap=False, compound='group')

    Center of geometry of (compounds of) the group

    \[\boldsymbol R = \frac{\sum_i \boldsymbol r_i}{\sum_i 1}\]

    where \(\boldsymbol r_i\) of `Atoms` \(i\). Centers of geometry per `Residue` or per `Segment` can be obtained by setting the compound parameter accordingly.

    Parameters:

      - wrap (bool, optional) – If `True` and compound is `'group'`, move all atoms to the primary unit cell before calculation. If `True` and compound is `'segments'` or `'residues'`, the center of each compound will be calculated without moving any `Atoms` to keep the compounds intact. Instead, the resulting position vectors will be moved to the primary unit cell after calculation. Default False.

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers.

      - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – If `'group'`, the center of geometry of all `Atoms` in the group will be returned as a single position vector. Else, the centers of geometry of each `Segment` or `Residue` will be returned as an array of position vectors, i.e. a 2d array. Note that, in any case, only the positions of `Atoms` belonging to the group will be taken into account.

    Returns:

      center – Position vector(s) of the geometric center(s) of the group. If compound was set to `'group'`, the output will be a single position vector. If compound was set to `'segments'` or `'residues'`, the output will be a 2d array of shape `(n, 3)` where `n` is the number of compounds.

    Return type:

      numpy.ndarray

    Changed in version 0.8: Added pbc keyword

    Changed in version 0.19.0: Added compound parameter

    Changed in version 0.20.0: Added `'molecules'` and `'fragments'` compounds

    Changed in version 0.20.0: Added unwrap parameter

    Changed in version 1.0.0: Removed flags affecting default behaviour

    Changed in version 2.1.0: Renamed pbc kwarg to wrap. pbc is still accepted but is deprecated and will be removed in version 3.0.

  center_of_mass(wrap=False, unwrap=False, compound='group')

    Center of mass of (compounds of) the group

    \[\boldsymbol R = \frac{\sum_i m_i \boldsymbol r_i}{\sum m_i}\]

    where \(m_i\) is the mass and \(\boldsymbol r_i\) the position of atom \(i\) in the given `MDAnalysis.core.groups.AtomGroup`. Centers of mass per `Residue`, `Segment`, molecule, or fragment can be obtained by setting the compound parameter accordingly. If the masses of a compound sum up to zero, the center of mass coordinates of that compound will be `nan` (not a number).

    Parameters:

      - wrap (bool, optional) – If `True` and compound is `'group'`, move all atoms to the primary unit cell before calculation. If `True` and compound is not `group`, the centers of mass of each compound will be calculated without moving any atoms to keep the compounds intact. Instead, the resulting center-of-mass position vectors will be moved to the primary unit cell after calculation.

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers.

      - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'},) – optional If `'group'`, the center of mass of all atoms in the group will be returned as a single position vector. Otherwise, the centers of mass of each `Segment`, `Residue`, molecule, or fragment will be returned as an array of position vectors, i.e. a 2d array. Note that, in any case, only the positions of `Atoms` belonging to the group will be taken into account.

    Returns:

      center – Position vector(s) of the center(s) of mass of the group. If compound was set to `'group'`, the output will be a single position vector. If compound was set to `'segments'` or `'residues'`, the output will be a 2d coordinate array of shape `(n, 3)` where `n` is the number of compounds.

    Return type:

      numpy.ndarray

    Note

    This method can only be accessed if the underlying topology has information about atomic masses.

    Changed in version 0.8: Added pbc parameter

    Changed in version 0.19.0: Added compound parameter

    Changed in version 0.20.0: Added `'molecules'` and `'fragments'` compounds; added unwrap parameter

    Changed in version 2.1.0: Renamed pbc kwarg to wrap. pbc is still accepted but is deprecated and will be removed in version 3.0.

    Note

    This requires the underlying topology to have masses. Otherwise, a `NoDataError` is raised.

  centroid(wrap=False, unwrap=False, compound='group')

    Center of geometry of (compounds of) the group

    \[\boldsymbol R = \frac{\sum_i \boldsymbol r_i}{\sum_i 1}\]

    where \(\boldsymbol r_i\) of `Atoms` \(i\). Centers of geometry per `Residue` or per `Segment` can be obtained by setting the compound parameter accordingly.

    Parameters:

      - wrap (bool, optional) – If `True` and compound is `'group'`, move all atoms to the primary unit cell before calculation. If `True` and compound is `'segments'` or `'residues'`, the center of each compound will be calculated without moving any `Atoms` to keep the compounds intact. Instead, the resulting position vectors will be moved to the primary unit cell after calculation. Default False.

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers.

      - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – If `'group'`, the center of geometry of all `Atoms` in the group will be returned as a single position vector. Else, the centers of geometry of each `Segment` or `Residue` will be returned as an array of position vectors, i.e. a 2d array. Note that, in any case, only the positions of `Atoms` belonging to the group will be taken into account.

    Returns:

      center – Position vector(s) of the geometric center(s) of the group. If compound was set to `'group'`, the output will be a single position vector. If compound was set to `'segments'` or `'residues'`, the output will be a 2d array of shape `(n, 3)` where `n` is the number of compounds.

    Return type:

      numpy.ndarray

    Changed in version 0.8: Added pbc keyword

    Changed in version 0.19.0: Added compound parameter

    Changed in version 0.20.0: Added `'molecules'` and `'fragments'` compounds

    Changed in version 0.20.0: Added unwrap parameter

    Changed in version 1.0.0: Removed flags affecting default behaviour

    Changed in version 2.1.0: Renamed pbc kwarg to wrap. pbc is still accepted but is deprecated and will be removed in version 3.0.

  concatenate(other)

    Concatenate with another Group or Component of the same level.

    Duplicate entries and original order is preserved. It is synomymous to the + operator.

    Parameters:

      other (Group or Component) – Group or Component with other.level same as self.level

    Returns:

      Group with elements of self and other concatenated

    Return type:

      Group

    Example

    The order of the original contents (including duplicates) are preserved when performing a concatenation.

        >>> ag1 = u.select_atoms('name O')
        >>> ag2 = u.select_atoms('name N')
        >>> ag3 = ag1 + ag2  # or ag1.concatenate(ag2)
        >>> ag3[:3].names
        array(['O', 'O', 'O'], dtype=object)
        >>> ag3[-3:].names
        array(['N', 'N', 'N'], dtype=object)

    Added in version 0.16.0.

  copy()

    Get another group identical to this one.

    Added in version 0.19.0.

  difference(other)

    Elements from this Group that do not appear in another

    This method removes duplicate elements and sorts the result. As such, it is different from `subtract()`. `difference()` is synomymous to the - operator.

    Parameters:

      other (Group or Component) – Group or Component with other.level same as self.level

    Returns:

      Group with the elements of self that are not in other, without duplicate elements

    Return type:

      Group

    See also

    `subtract`, `symmetric_difference`

    Added in version 0.16.

  property dimensions

    Obtain a copy of the dimensions of the currently loaded Timestep

  dipole_moment(**kwargs)

    Dipole moment of the group or compounds in a group.

    \[\mu = |\boldsymbol{\mu}| = \sqrt{ \sum_{i=1}^{D} \mu^2 }\]

    Where \(D\) is the number of dimensions, in this case 3.

    Computes the dipole moment of `Atoms` in the group. Dipole per `Residue`, `Segment`, molecule, or fragment can be obtained by setting the compound parameter accordingly.

    Note that when there is a net charge, the magnitude of the dipole moment is dependent on the center chosen. See `dipole_vector()`.

    Parameters:

      - wrap (bool, optional) – If `True` and compound is `'group'`, move all atoms to the primary unit cell before calculation. If `True` and compound is not `group`, the centers of mass of each compound will be calculated without moving any atoms to keep the compounds intact.

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers.

      - compound ({'group', 'segments', 'residues', 'molecules', ) – ‘fragments’}, optional If `'group'`, a single dipole vector returns. Otherwise, an array of each `Segment`, `Residue`, molecule, or fragment will be returned as an array of position vectors, i.e. a 2d array. Note that, in any case, only the positions of `Atoms` belonging to the group will be taken into account.

      - center ({'mass', 'charge'}, optional) – Choose whether the dipole vector is calculated at the center of “mass” or the center of “charge”, default is “mass”.

    Returns:

      Dipole moment(s) of (compounds of) the group in \(eÅ\). If compound was set to `'group'`, the output will be a single value. Otherwise, the output will be a 1d array of shape `(n,)` where `n` is the number of compounds.

    Return type:

      numpy.ndarray

    Added in version 2.4.0.

    Note

    This requires the underlying topology to have charges. Otherwise, a `NoDataError` is raised.

  dipole_vector(wrap=False, unwrap=False, compound='group', center='mass')

    Dipole vector of the group.

    \[\boldsymbol{\mu} = \sum_{i=1}^{N} q_{i} ( \mathbf{r}_{i} - \mathbf{r}_{COM} )\]

    Computes the dipole vector of `Atoms` in the group. Dipole vector per `Residue`, `Segment`, molecule, or fragment can be obtained by setting the compound parameter accordingly.

    Note that the magnitude of the dipole moment is independent of the `center` chosen unless the species has a net charge. In the case of a charged group the dipole moment can be later adjusted with:

    \[\boldsymbol{\mu}_{COC} = \boldsymbol{\mu}_{COM} + q_{ag}\mathbf{r}_{COM} - q_{ag}\boldsymbol{r}_{COC}\]

    Where \(\mathbf{r}_{COM}\) is the center of mass and \(\mathbf{r}_{COC}\) is the center of charge.

    Parameters:

      - wrap (bool, optional) – If `True` and compound is `'group'`, move all atoms to the primary unit cell before calculation. If `True` and compound is not `group`, the centers of mass of each compound will be calculated without moving any atoms to keep the compounds intact.

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers.

      - compound ({'group', 'segments', 'residues', 'molecules', ) – ‘fragments’}, optional If `'group'`, a single dipole vector returns. Otherwise, an array of each `Segment`, `Residue`, molecule, or fragment will be returned as an array of position vectors, i.e. a 2d array. Note that, in any case, only the positions of `Atoms` belonging to the group will be taken into account.

      - center ({'mass', 'charge'}, optional) – Choose whether the dipole vector is calculated at the center of “mass” or the center of “charge”, default is “mass”.

    Returns:

      Dipole vector(s) of (compounds of) the group in \(eÅ\). If compound was set to `'group'`, the output will be a single value. Otherwise, the output will be a 1d array of shape `(n,3)` where `n` is the number of compounds.

    Return type:

      numpy.ndarray

    Added in version 2.4.0.

    Note

    This requires the underlying topology to have charges. Otherwise, a `NoDataError` is raised.

  get_connections(typename, outside=True)

    Get bonded connections between atoms as a `TopologyGroup`.

    Parameters:

      - typename (str) – group name. One of {“bonds”, “angles”, “dihedrals”, “impropers”, “ureybradleys”, “cmaps”}

      - outside (bool (optional)) – Whether to include connections involving atoms outside this group.

    Returns:

      - TopologyGroup – containing the bonded group of choice, i.e. bonds, angles, dihedrals, impropers, ureybradleys or cmaps.

      - .. versionadded:: 1.1.0

  groupby(topattrs)

    Group together items in this group according to values of topattr

    Parameters:

      topattrs (str or list) – One or more topology attributes to group components by. Single arguments are passed as a string. Multiple arguments are passed as a list.

    Returns:

      Unique values of the multiple combinations of topology attributes as keys, Groups as values.

    Return type:

      dict

    Example

    To group atoms with the same mass together:

         >>> ag.groupby('masses')
         {32.06: <AtomGroup with 7 atoms>,
          1.008: <AtomGroup with 1685 atoms>,
          12.011: <AtomGroup with 1040 atoms>,
          14.007: <AtomGroup with 289 atoms>,
          15.999: <AtomGroup with 320 atoms>}

    To group atoms with the same residue name and mass together:

         >>> group_dict = ag.groupby(['resnames', 'masses'])
         >>> dict(sorted(group_dict.items()))
         {('ALA', 1.008): <AtomGroup with 95 atoms>,
          ('ALA', 12.011): <AtomGroup with 57 atoms>,
          ('ALA', 14.007): <AtomGroup with 19 atoms>,
          ('ALA', 15.999): <AtomGroup with 19 atoms>,
          ('ARG', 1.008): <AtomGroup with 169 atoms>,
          ...

        >>> ag.groupby(['resnames', 'masses'])['ALA', 15.999]
        <AtomGroup with 19 atoms>

    Added in version 0.16.0.

    Changed in version 0.18.0: The function accepts multiple attributes

  gyration_moments(wrap=False, unwrap=False, compound='group')

    Moments of the gyration tensor.

    The moments are defined as the eigenvalues of the gyration tensor.

    \[\mathsf{T} = \frac{1}{N} \sum_{i=1}^{N} (\mathbf{r}_\mathrm{i} - \mathbf{r}_\mathrm{COM})(\mathbf{r}_\mathrm{i} - \mathbf{r}_\mathrm{COM})\]

    Where \(\mathbf{r}_\mathrm{COM}\) is the center of mass.

    See [Dima2004a] for background information.

    Parameters:

      - wrap (bool, optional) – If `True`, move all atoms within the primary unit cell before calculation. [`False`]

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers.

      - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – Which type of component to keep together during unwrapping.

    Returns:

      principle_moments_of_gyration – Gyration vector(s) of (compounds of) the group in \(Å^2\). If compound was set to `'group'`, the output will be a single vector of length 3. Otherwise, the output will be a 2D array of shape `(n,3)` where `n` is the number of compounds.

    Return type:

      numpy.ndarray

    Added in version 2.5.0.

    Note

    This requires the underlying topology to have masses. Otherwise, a `NoDataError` is raised.

  intersection(other)

    Group of elements which are in both this Group and another

    This method removes duplicate elements and sorts the result. It is synomymous to the & operator.

    Parameters:

      other (Group or Component) – Group or Component with other.level same as self.level

    Returns:

      Group with the common elements of self and other, without duplicate elements

    Return type:

      Group

    Example

    Intersections can be used when the select atoms string would become too complicated. For example to find the water atoms which are within 4.0A of two segments:

        >>> shell1 = u.select_atoms('resname SOL and around 4.0 segid 1')
        >>> shell2 = u.select_atoms('resname SOL and around 4.0 segid 2')
        >>> common = shell1 & shell2  # or shell1.intersection(shell2)

    See also

    `union`

    Added in version 0.16.

  is_strict_subset(other)

    If this Group is a subset of another Group but not identical

    Parameters:

      other (Group or Component) – Group or Component with other.level same as self.level

    Returns:

      `True` if this Group is a strict subset of the other one

    Return type:

      bool

    Added in version 0.16.

  is_strict_superset(other)

    If this Group is a superset of another Group but not identical

    Parameters:

      other (Group or Component) – Group or Component with other.level same as self.level

    Returns:

      `True` if this Group is a strict superset of the other one

    Return type:

      bool

    Added in version 0.16.

  isdisjoint(other)

    If the Group has no elements in common with the other Group

    Parameters:

      other (Group or Component) – Group or Component with other.level same as self.level

    Returns:

      `True` if the two Groups do not have common elements

    Return type:

      bool

    Added in version 0.16.

  issubset(other)

    If all elements of this Group are part of another Group

    Note that an empty group is a subset of any group of the same level.

    Parameters:

      other (Group or Component) – Group or Component with other.level same as self.level

    Returns:

      `True` if this Group is a subset of the other one

    Return type:

      bool

    Added in version 0.16.

  issuperset(other)

    If all elements of another Group are part of this Group

    Parameters:

      other (Group or Component) – Group or Component with other.level same as self.level

    Returns:

      `True` if this Group is a subset of the other one

    Return type:

      bool

    Added in version 0.16.

  property isunique

    Boolean indicating whether all components of the group are unique, i.e., the group contains no duplicates.

    Examples

        >>> ag = u.atoms[[2, 1, 2, 2, 1, 0]]
        >>> ag
        <AtomGroup with 6 atoms>
        >>> ag.isunique
        False
        >>> ag2 = ag.unique
        >>> ag2
        <AtomGroup with 3 atoms>
        >>> ag2.isunique
        True

    See also

    `asunique`

    Added in version 0.19.0.

  property ix

    Unique indices of the components in the Group.

    - If this Group is an `AtomGroup`, these are the indices of the `Atom` instances.

    - If it is a `ResidueGroup`, these are the indices of the `Residue` instances.

    - If it is a `SegmentGroup`, these are the indices of the `Segment` instances.

  property ix_array

    Unique indices of the components in the Group.

    For a Group, `ix_array` is the same as `ix`. This method gives a consistent API between components and groups.

    See also

    `ix`

  moment_of_inertia(wrap=False, unwrap=False, compound='group')

    Moment of inertia tensor relative to center of mass.

    Parameters:

      - wrap (bool, optional) – If `True` and compound is `'group'`, move all atoms to the primary unit cell before calculation. If `True` and compound is not `group`, the centers of mass of each compound will be calculated without moving any atoms to keep the compounds intact. Instead, the resulting center-of-mass position vectors will be moved to the primary unit cell after calculation.

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers and tensor of inertia.

      - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'},) – optional compound determines the behavior of wrap. Note that, in any case, only the positions of `Atoms` belonging to the group will be taken into account.

    Returns:

      moment_of_inertia – Moment of inertia tensor as a 3 x 3 numpy array.

    Return type:

      numpy.ndarray

    Notes

    The moment of inertia tensor \(\mathsf{I}\) is calculated for a group of \(N\) atoms with coordinates \(\mathbf{r}_i,\ 1 \le i \le N\) relative to its center of mass from the relative coordinates

    \[\mathbf{r}'_i = \mathbf{r}_i - \frac{1}{\sum_{i=1}^{N} m_i} \sum_{i=1}^{N} m_i \mathbf{r}_i\]

    as

    \[\mathsf{I} = \sum_{i=1}^{N} m_i \Big[(\mathbf{r}'_i\cdot\mathbf{r}'_i) \sum_{\alpha=1}^{3} \hat{\mathbf{e}}_\alpha \otimes \hat{\mathbf{e}}_\alpha - \mathbf{r}'_i \otimes \mathbf{r}'_i\Big]\]

    where \(\hat{\mathbf{e}}_\alpha\) are Cartesian unit vectors, or in Cartesian coordinates

    \[I_{\alpha,\beta} = \sum_{k=1}^{N} m_k \Big(\big(\sum_{\gamma=1}^3 (x'^{(k)}_{\gamma})^2 \big)\delta_{\alpha,\beta} - x'^{(k)}_{\alpha} x'^{(k)}_{\beta} \Big).\]

    where \(x'^{(k)}_{\alpha}\) are the Cartesian coordinates of the relative coordinates \(\mathbf{r}'_k\).

    Changed in version 0.8: Added pbc keyword

    Changed in version 0.20.0: Added unwrap parameter

    Changed in version 2.1.0: Renamed pbc kwarg to wrap. pbc is still accepted but is deprecated and will be removed in version 3.0.

    Note

    This requires the underlying topology to have masses. Otherwise, a `NoDataError` is raised.

  property n_atoms

    Number of atoms present in the `SegmentGroup`, including duplicate segments (and thus, duplicate atoms).

    Equivalent to `len(self.atoms)`.

  property n_residues

    Number of residues present in this `SegmentGroup`, including duplicate segments (and thus, residues).

    Equivalent to `len(self.residues)`.

  property n_segments

    Number of segments in the `SegmentGroup`.

    Equivalent to `len(self)`.

  pack_into_box(box=None, inplace=True)

    Shift all `Atoms` in this group to the primary unit cell.

    Parameters:

      - box (array_like) – Box dimensions, can be either orthogonal or triclinic information. Cell dimensions must be in an identical to format to those returned by `MDAnalysis.coordinates.timestep.Timestep.dimensions`, `[lx, ly, lz, alpha, beta, gamma]`. If `None`, uses these timestep dimensions.

      - inplace (bool) – `True` to change coordinates in place.

    Returns:

      coords – Shifted atom coordinates.

    Return type:

      numpy.ndarray

    Notes

    All atoms will be moved so that they lie between 0 and boxlength \(L_i\) in all dimensions, i.e. the lower left corner of the simulation box is taken to be at (0,0,0):

    \[x_i' = x_i - \left\lfloor\frac{x_i}{L_i}\right\rfloor\]

    The default is to take unit cell information from the underlying `Timestep` instance. The optional argument box can be used to provide alternative unit cell information (in the MDAnalysis standard format `[Lx, Ly, Lz, alpha, beta, gamma]`).

    Works with either orthogonal or triclinic box types.

    Note

    `pack_into_box()` is identical to `wrap()` with all default keywords.

    Note

    `AtomGroup.pack_into_box()` is currently faster than `ResidueGroup.pack_into_box()` or `SegmentGroup.pack_into_box()`.

    Added in version 0.8.

  principal_axes(wrap=False)

    Calculate the principal axes from the moment of inertia.

    e1,e2,e3 = AtomGroup.principal_axes()

    The eigenvectors are sorted by eigenvalue, i.e. the first one corresponds to the highest eigenvalue and is thus the first principal axes.

    The eigenvectors form a right-handed coordinate system.

    Parameters:

      wrap (bool, optional) – If `True`, move all atoms within the primary unit cell before calculation. [`False`]

    Returns:

      axis_vectors – 3 x 3 array with `v[0]` as first, `v[1]` as second, and `v[2]` as third eigenvector.

    Return type:

      array

    Changed in version 0.8: Added pbc keyword

    Changed in version 1.0.0: Always return principal axes in right-hand convention.

    Changed in version 2.1.0: Renamed pbc kwarg to wrap. pbc is still accepted but is deprecated and will be removed in version 3.0.

    Note

    This requires the underlying topology to have masses. Otherwise, a `NoDataError` is raised.

  quadrupole_moment(**kwargs)

    Quadrupole moment of the group according to [1].

    \[Q = \sqrt{\frac{2}{3}{\hat{\mathsf{Q}}}:{\hat{\mathsf{Q}}}}\]

    where the quadrupole moment is calculated from the tensor double contraction of the traceless quadropole tensor \(\hat{\mathsf{Q}}\)

    Computes the quadrupole moment of `Atoms` in the group. Quadrupole per `Residue`, `Segment`, molecule, or fragment can be obtained by setting the compound parameter accordingly.

    Note that when there is an unsymmetrical plane in the molecule or group, the magnitude of the quadrupole moment is dependant on the `center` chosen and cannot be translated.

    Parameters:

      - wrap (bool, optional) – If `True` and compound is `'group'`, move all atoms to the primary unit cell before calculation. If `True` and compound is not `group`, the centers of mass of each compound will be calculated without moving any atoms to keep the compounds intact.

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers.

      - compound ({'group', 'segments', 'residues', 'molecules', ) – ‘fragments’}, optional If `'group'`, a single quadrupole value returns. Otherwise, an array of each `Segment`, `Residue`, molecule, or fragment will be returned as an array of position vectors, i.e. a 1d array. Note that, in any case, only the positions of `Atoms` belonging to the group will be taken into account.

      - center ({'mass', 'charge'}, optional) – Choose whether the dipole vector is calculated at the center of “mass” or the center of “charge”, default is “mass”.

    Returns:

      Quadrupole moment(s) of (compounds of) the group in \(eÅ^2\). If compound was set to `'group'`, the output will be a single value. Otherwise, the output will be a 1d array of shape `(n,)` where `n` is the number of compounds.

    Return type:

      numpy.ndarray

    Added in version 2.4.0.

    Note

    This requires the underlying topology to have charges. Otherwise, a `NoDataError` is raised.

  quadrupole_tensor(wrap=False, unwrap=False, compound='group', center='mass')

    Traceless quadrupole tensor of the group or compounds.

    This tensor is first computed as the outer product of vectors from a reference point to some atom, and multiplied by the atomic charge. The tensor of each atom is then summed to produce the quadrupole tensor of the group:

    \[\mathsf{Q} = \sum_{i=1}^{N} q_{i} ( \mathbf{r}_{i} - \mathbf{r}_{COM} ) \otimes ( \mathbf{r}_{i} - \mathbf{r}_{COM} )\]

    The traceless quadrupole tensor, \(\hat{\mathsf{Q}}\), is then taken from:

    \[\hat{\mathsf{Q}} = \frac{3}{2} \mathsf{Q} - \frac{1}{2} tr(\mathsf{Q})\]

    Computes the quadrupole tensor of `Atoms` in the group. Tensor per `Residue`, `Segment`, molecule, or fragment can be obtained by setting the compound parameter accordingly.

    Note that when there is an unsymmetrical plane in the molecule or group, the magnitude of the quadrupole tensor is dependent on the `center` (e.g., \(\mathbf{r}_{COM}\)) chosen and cannot be translated.

    Parameters:

      - wrap (bool, optional) – If `True` and compound is `'group'`, move all atoms to the primary unit cell before calculation. If `True` and compound is not `group`, the centers of mass of each compound will be calculated without moving any atoms to keep the compounds intact.

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers.

      - compound ({'group', 'segments', 'residues', 'molecules', ) – ‘fragments’}, optional If `'group'`, a single quadrupole value returns. Otherwise, an array of each `Segment`, `Residue`, molecule, or fragment will be returned as an array of position vectors, i.e. a 1d array. Note that, in any case, only the positions of `Atoms` belonging to the group will be taken into account.

      - center ({'mass', 'charge'}, optional) – Choose whether the dipole vector is calculated at the center of “mass” or the center of “charge”, default is “mass”.

    Returns:

      Quadrupole tensor(s) of (compounds of) the group in \(eÅ^2\). If compound was set to `'group'`, the output will be a single tensor of shape `(3,3)`. Otherwise, the output will be a 1d array of shape `(n,3,3)` where `n` is the number of compounds.

    Return type:

      numpy.ndarray

    Added in version 2.4.0.

    Note

    This requires the underlying topology to have charges. Otherwise, a `NoDataError` is raised.

  radius_of_gyration(wrap=False, **kwargs)

    Radius of gyration.

    Parameters:

      wrap (bool, optional) – If `True`, move all atoms within the primary unit cell before calculation. [`False`]

    Changed in version 0.8: Added pbc keyword

    Changed in version 2.1.0: Renamed pbc kwarg to wrap. pbc is still accepted but is deprecated and will be removed in version 3.0.

    Note

    This requires the underlying topology to have masses. Otherwise, a `NoDataError` is raised.

  property residues

    A `ResidueGroup` of `Residues` present in this `SegmentGroup`.

    The `Residues` are ordered locally by `Segment` in the `SegmentGroup`. Duplicates are not removed.

  rotate(R, point=(0, 0, 0))

    Apply a rotation matrix R to the selection’s coordinates. \(\mathsf{R}\) is a 3x3 orthogonal matrix that transforms a vector \(\mathbf{x} \rightarrow \mathbf{x}'\):

    \[\mathbf{x}' = \mathsf{R}\mathbf{x}\]

    `Atom` coordinates are rotated in-place.

    Parameters:

      - R (array_like) – 3x3 rotation matrix

      - point (array_like, optional) – Center of rotation

    Return type:

      self

    Notes

    By default, rotates about the origin `point=(0, 0, 0)`. To rotate a group `g` around its center of geometry, use `g.rotate(R, point=g.center_of_geometry())`.

    See also

    `rotateby`

      rotate around given axis and angle

    `MDAnalysis.lib.transformations`

      module of all coordinate transforms

  rotateby(angle, axis, point=None)

    Apply a rotation to the selection’s coordinates.

    Parameters:

      - angle (float) – Rotation angle in degrees.

      - axis (array_like) – Rotation axis vector.

      - point (array_like, optional) – Center of rotation. If `None` then the center of geometry of this group is used.

    Return type:

      self

    Notes

    The transformation from current coordinates \(\mathbf{x}\) to new coordinates \(\mathbf{x}'\) is

    \[\mathbf{x}' = \mathsf{R}\,(\mathbf{x}-\mathbf{p}) + \mathbf{p}\]

    where \(\mathsf{R}\) is the rotation by angle around the axis going through point \(\mathbf{p}\).

    See also

    `MDAnalysis.lib.transformations.rotation_matrix`

    `calculate`

      math:mathsf{R}

  property segments

    The `SegmentGroup` itself.

    See also

    `copy`

      return a true copy of the `SegmentGroup`

    Changed in version 0.19.0: In previous versions, this returned a copy, but now the `SegmentGroup` itself is returned. This should not affect any code but only speed up calculations.

  shape_parameter(wrap=False, unwrap=False, compound='group')

    Shape parameter.

    See [Dima2004a] for background information.

    Parameters:

      - wrap (bool, optional) – If `True`, move all atoms within the primary unit cell before calculation. [`False`]

      - unwrap (bool, optional) – If `True`, compounds will be unwrapped before computing their centers.

      - compound ({'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – Which type of component to keep together during unwrapping.

    Added in version 0.7.7.

    Changed in version 0.8: Added pbc keyword

    Changed in version 2.1.0: Renamed pbc kwarg to wrap. pbc is still accepted but is deprecated and will be removed in version 3.0. Superfluous kwargs were removed.

    Changed in version 2.5.0: Added calculation for any compound type

    Note

    This requires the underlying topology to have masses. Otherwise, a `NoDataError` is raised.

  subtract(other)

    Group with elements from this Group that don’t appear in other

    The original order of this group is kept, as well as any duplicate elements. If an element of this Group is duplicated and appears in the other Group or Component, then all the occurences of that element are removed from the returned Group.

    Parameters:

      other (Group or Component) – Group or Component with other.level same as self.level

    Returns:

      Group with the elements of self that are not in other, conserves order and duplicates.

    Return type:

      Group

    Example

    Unlike `difference()` this method will not sort or remove duplicates.

        >>> ag1 = u.atoms[[3, 3, 2, 2, 1, 1]]
        >>> ag2 = u.atoms[2]
        >>> ag3 = ag1.subtract(ag2)
        >>> ag3.indices
        array([3, 3, 1, 1])

    See also

    `concatenate`, `difference`

    Added in version 0.16.

  symmetric_difference(other)

    Group of elements which are only in one of this Group or another

    This method removes duplicate elements and the result is sorted. It is synomym to the ^ operator.

    Parameters:

      other (Group or Component) – Group or Component with other.level same as self.level

    Returns:

      Group with the elements that are in self or in other but not in both, without duplicate elements

    Return type:

      Group

    Example

        >>> ag1 = u.atoms[[0, 1, 5, 3, 3, 2]]
        >>> ag2 = u.atoms[[4, 4, 6, 2, 3, 5]]
        >>> ag3 = ag1 ^ ag2  # or ag1.symmetric_difference(ag2)
        >>> ag3.indices  # 0 and 1 are only in ag1, 4 and 6 are only in ag2
        array([0, 1, 4, 6])

    See also

    `difference`

    Added in version 0.16.

  total_charge(compound='group')

    Total charge of (compounds of) the group.

    Computes the total charge of `Atoms` in the group. Total charges per `Residue`, `Segment`, molecule, or fragment can be obtained by setting the compound parameter accordingly.

    Parameters:

      compound ({'group', 'segments', 'residues', 'molecules', 'fragments'},) – optional If ‘group’, the total charge of all atoms in the group will be returned as a single value. Otherwise, the total charges per `Segment`, `Residue`, molecule, or fragment will be returned as a 1d array. Note that, in any case, only the charges of `Atoms` belonging to the group will be taken into account.

    Returns:

      Total charge of (compounds of) the group. If compound was set to `'group'`, the output will be a single value. Otherwise, the output will be a 1d array of shape `(n,)` where `n` is the number of compounds.

    Return type:

      float or numpy.ndarray

    Changed in version 0.20.0: Added compound parameter

    Note

    This requires the underlying topology to have charges. Otherwise, a `NoDataError` is raised.

  total_mass(compound='group')

    Total mass of (compounds of) the group.

    Computes the total mass of `Atoms` in the group. Total masses per `Residue`, `Segment`, molecule, or fragment can be obtained by setting the compound parameter accordingly.

    Parameters:

      compound ({'group', 'segments', 'residues', 'molecules', 'fragments'},) – optional If `'group'`, the total mass of all atoms in the group will be returned as a single value. Otherwise, the total masses per `Segment`, `Residue`, molecule, or fragment will be returned as a 1d array. Note that, in any case, only the masses of `Atoms` belonging to the group will be taken into account.

    Returns:

      Total mass of (compounds of) the group. If compound was set to `'group'`, the output will be a single value. Otherwise, the output will be a 1d array of shape `(n,)` where `n` is the number of compounds.

    Return type:

      float or numpy.ndarray

    Changed in version 0.20.0: Added compound parameter

    Note

    This requires the underlying topology to have masses. Otherwise, a `NoDataError` is raised.

  transform(M)

    Apply homogenous transformation matrix M to the coordinates.

    `Atom` coordinates are rotated and translated in-place.

    Parameters:

      M (array_like) – 4x4 matrix with the rotation in `R = M[:3, :3]` and the translation in `t = M[:3, 3]`.

    Return type:

      self

    See also

    `MDAnalysis.lib.transformations`

      module of all coordinate transforms

    Notes

    The rotation \(\mathsf{R}\) is about the origin and is applied before the translation \(\mathbf{t}\):

    \[\mathbf{x}' = \mathsf{R}\mathbf{x} + \mathbf{t}\]
  translate(t)

    Apply translation vector t to the selection’s coordinates.

    `Atom` coordinates are translated in-place.

    Parameters:

      t (array_like) – vector to translate coordinates with

    Return type:

      self

    See also

    `MDAnalysis.lib.transformations`

      module of all coordinate transforms

    Notes

    The method applies a translation to the `AtomGroup` from current coordinates \(\mathbf{x}\) to new coordinates \(\mathbf{x}'\):

    \[\mathbf{x}' = \mathbf{x} + \mathbf{t}\]
  union(other)

    Group of elements either in this Group or another

    On the contrary to concatenation, this method sort the elements and removes duplicate ones. It is synomymous to the | operator.

    Parameters:

      other (Group or Component) – Group or Component with other.level same as self.level

    Returns:

      Group with the combined elements of self and other, without duplicate elements

    Return type:

      Group

    Example

    In contrast to `concatenate()`, any duplicates are dropped and the result is sorted.

        >>> ag1 = u.select_atoms('name O')
        >>> ag2 = u.select_atoms('name N')
        >>> ag3 = ag1 | ag2  # or ag1.union(ag2)
        >>> ag3[:3].names
        array(['N', 'O', 'N'], dtype=object)

    See also

    `concatenate`, `intersection`

    Added in version 0.16.

  property unique

    Return a `SegmentGroup` containing sorted and unique `Segments` only.

    Examples

        >>> sg = u.segments[[2, 1, 2, 2, 1, 0]]
        >>> sg
        <SegmentGroup with 6 segments>
        >>> sg.ix
        array([2, 1, 2, 2, 1, 0])
        >>> sg2 = sg.unique
        >>> sg2
        <SegmentGroup with 3 segments>
        >>> sg2.ix
        array([0, 1, 2])
        >>> sg2.unique is sg2
        False

    Added in version 0.16.0.

    Changed in version 0.19.0: If the `SegmentGroup` is already unique, `SegmentGroup.unique` now returns the group itself instead of a copy.

    Changed in version 2.0.0: This function now always returns a copy.

  property universe

    The underlying `Universe` the group belongs to.

  unwrap(compound='fragments', reference='com', inplace=True)

    Move atoms of this group so that bonds within the group’s compounds aren’t split across periodic boundaries.

    This function is most useful when atoms have been packed into the primary unit cell, causing breaks mid-molecule, with the molecule then appearing on either side of the unit cell. This is problematic for operations such as calculating the center of mass of the molecule.

        +-----------+       +-----------+
        |           |       |           |
        | 6       3 |       |         3 | 6
        | !       ! |       |         ! | !
        |-5-8   1-2-|  ==>  |       1-2-|-5-8
        | !       ! |       |         ! | !
        | 7       4 |       |         4 | 7
        |           |       |           |
        +-----------+       +-----------+

    Parameters:

      - compound ({'group', 'segments', 'residues', 'molecules', ) – ‘fragments’}, optional Which type of compound to unwrap. Note that, in any case, all atoms within each compound must be interconnected by bonds, i.e., compounds must correspond to (parts of) molecules.

      - reference ({'com', 'cog', None}, optional) – If `'com'` (center of mass) or `'cog'` (center of geometry), the unwrapped compounds will be shifted so that their individual reference point lies within the primary unit cell. If `None`, no such shift is performed.

      - inplace (bool, optional) – If `True`, coordinates are modified in place.

    Returns:

      coords – Unwrapped atom coordinate array of shape `(n, 3)`.

    Return type:

      numpy.ndarray

    Raises:

      - NoDataError – If compound is `'molecules'` but the underlying topology does not contain molecule information, or if reference is `'com'` but the topology does not contain masses.

      - ValueError – If reference is not one of `'com'`, `'cog'`, or `None`, or if reference is `'com'` and the total mass of any compound is zero.

    Note

    Be aware of the fact that only atoms belonging to the group will be unwrapped! If you want entire molecules to be unwrapped, make sure that all atoms of these molecules are part of the group. An AtomGroup containing all atoms of all fragments in the group `ag` can be created with:

        all_frag_atoms = sum(ag.fragments)

    See also

    `make_whole()`, `wrap()`, `pack_into_box()`, `apply_PBC()`

    Added in version 0.20.0.

  wrap(compound='atoms', center='com', box=None, inplace=True)

    Shift the contents of this group back into the primary unit cell according to periodic boundary conditions.

    Specifying a compound will keep the `Atoms` in each compound together during the process. If compound is different from `'atoms'`, each compound as a whole will be shifted so that its center lies within the primary unit cell.

    Parameters:

      - compound ({'atoms', 'group', 'segments', 'residues', 'molecules', ) – ‘fragments’}, optional Which type of compound to keep together during wrapping. Note that, in any case, only the positions of `Atoms` belonging to the group will be taken into account.

      - center ({'com', 'cog'}) – How to define the center of a given group of atoms. If compound is `'atoms'`, this parameter is meaningless and therefore ignored.

      - box (array_like, optional) – The unitcell dimensions of the system, which can be orthogonal or triclinic and must be provided in the same format as returned by `MDAnalysis.coordinates.timestep.Timestep.dimensions`: `[lx, ly, lz, alpha, beta, gamma]`. If `None`, uses the dimensions of the current time step.

      - inplace (bool, optional) – If `True`, coordinates will be changed in place.

    Returns:

      Array of wrapped atom coordinates of dtype np.float32 and shape `(len(self.atoms.n_atoms), 3)`

    Return type:

      numpy.ndarray

    Raises:

      - ValueError – If compound is not one of `'atoms'`, `'group'`, `'segments'`, `'residues'`, `'molecules'`, or `'fragments'`.

      - NoDataError – If compound is `'molecule'` but the topology doesn’t contain molecule information (molnums) or if compound is `'fragments'` but the topology doesn’t contain bonds or if center is `'com'` but the topology doesn’t contain masses.

    Notes

    All atoms of the group will be moved so that the centers of its compounds lie within the primary periodic image. For orthorhombic unit cells, the primary periodic image is defined as the half-open interval \([0,L_i)\) between \(0\) and boxlength \(L_i\) in all dimensions \(i\in\{x,y,z\}\), i.e., the origin of the of the simulation box is taken to be at the origin \((0,0,0)\) of the euclidian coordinate system. A compound center residing at position \(x_i\) in dimension \(i\) will be shifted to \(x_i'\) according to

    \[x_i' = x_i - \left\lfloor\frac{x_i}{L_i}\right\rfloor\,.\]

    When specifying a compound, the translation is calculated based on each compound. The same translation is applied to all atoms within this compound, meaning it will not be broken by the shift. This might however mean that not all atoms of a compound will be inside the unit cell after wrapping, but rather will be the center of the compound. Be aware of the fact that only atoms belonging to the group will be taken into account!

    center allows to define how the center of each group is computed. This can be either `'com'` for center of mass, or `'cog'` for center of geometry.

    box allows a unit cell to be given for the transformation. If not specified, the `dimensions` information from the current `Timestep` will be used.

    Note

    `AtomGroup.wrap()` is currently faster than `ResidueGroup.wrap()` or `SegmentGroup.wrap()`.

    See also

    `pack_into_box()`, `unwrap()`, `MDAnalysis.lib.distances.apply_PBC()`

    Added in version 0.9.2.

    Changed in version 0.20.0: The method only acts on atoms belonging to the group and returns the wrapped positions as a `numpy.ndarray`. Added optional argument inplace.

class MDAnalysis.core.groups.UpdatingAtomGroup(*args, **kwargs)

  `AtomGroup` subclass that dynamically updates its selected atoms.

  Accessing any attribute/method of an `UpdatingAtomGroup` instance triggers a check for the last frame the group was updated. If the last frame matches the current trajectory frame, the attribute is returned normally; otherwise the group is updated (the stored selections are re-applied), and only then is the attribute returned.

  Added in version 0.16.0.

  Parameters:

    - base_group (`AtomGroup`) – group on which selections are to be applied.

    - selections (a tuple of `Selection`) – instances selections ready to be applied to base_group.

  property atoms

    Get a static `AtomGroup` identical to the group of currently selected `Atoms` in the `UpdatingAtomGroup`.

    By returning a static `AtomGroup` it becomes possible to compare the contents of the group between trajectory frames. See the Example below.

    Note

    The `atoms` attribute of an `UpdatingAtomGroup` behaves differently from `AtomGroup.atoms`: the latter returns the `AtomGroup` itself whereas the former returns a `AtomGroup` and not an `UpdatingAtomGroup` (for this, use `UpdatingAtomGroup.copy()`).

    Example

    The static `atoms` allows comparison of groups of atoms between frames. For example, track water molecules that move in and out of a solvation shell of a protein

        u = mda.Universe(TPR, XTC)
        water_shell = u.select_atoms("name OW and around 3.5 protein",
                                     updating=True)
        water_shell_prev = water_shell.atoms

        for ts in u.trajectory:
            exchanged = water_shell - water_shell_prev

        print(ts.time, "waters in shell =", water_shell.n_residues)
        print(ts.time, "waters that exchanged = ", exchanged.n_residues)
        print(ts.time, "waters that remained bound = ",
              water_shell.n_residues - exchanged.n_residues)

        water_shell_prev = water_shell.atoms

    By remembering the atoms of the current time step in water_shell_prev, it becomes possible to use the `subtraction of AtomGroups` to find the water molecules that changed.

    See also

    `copy`

      return a true copy of the `UpdatingAtomGroup`

  copy()

    Get another `UpdatingAtomGroup` identical to this one.

    Added in version 0.19.0.

  property is_uptodate

    Checks whether the selection needs updating based on frame number only.

    Modifications to the coordinate data that render selections stale are not caught, and in those cases `is_uptodate` may return an erroneous value.

    Returns:

      `True` if the group’s selection is up-to-date, `False` otherwise.

    Return type:

      bool

  update_selection()

    Forces the reevaluation and application of the group’s selection(s).

    This method is triggered automatically when accessing attributes, if the last update occurred under a different trajectory frame.

### 12.2.2.1.2. Chemical units

class MDAnalysis.core.groups.Atom(*args, **kwargs)

  `Atom` base class.

  This class is used by a `Universe` for generating its Topology-specific `Atom` class. All the `TopologyAttr` components are obtained from `ComponentBase`, so this class only includes ad-hoc methods specific to `Atoms`.

  property bfactor

    Bfactor alias with warning

    Note

    This requires the underlying topology to have tempfactors. Otherwise, a `NoDataError` is raised.

  property bonded_atoms

    An `AtomGroup` of all `Atoms` bonded to this `Atom`.

    Note

    This requires the underlying topology to have bonds. Otherwise, a `NoDataError` is raised.

  property force

    Force on the atom.

    The force can be changed by assigning an array of shape `(3,)`.

    Note

    changing the force is not reflected in any files; reading any frame from the trajectory will replace the change with that from the file

    Raises:

      NoDataError – If the underlying `Timestep` does not contain `forces`.

  property fragindex

    The index (ID) of the `fragment` this `Atom` is part of.

    Added in version 0.20.0.

    Note

    This requires the underlying topology to have bonds. Otherwise, a `NoDataError` is raised.

  property fragment

    An `AtomGroup` representing the fragment this `Atom` is part of.

    A fragment is a `group of atoms` which are interconnected by `Bonds`, i.e., there exists a path along one or more `Bonds` between any pair of `Atoms` within a fragment. Thus, a fragment typically corresponds to a molecule.

    Added in version 0.9.0.

    Note

    This requires the underlying topology to have bonds. Otherwise, a `NoDataError` is raised.

  get_connections(typename, outside=True)

    Get bonded connections between atoms as a `TopologyGroup`.

    Parameters:

      - typename (str) – group name. One of {“bonds”, “angles”, “dihedrals”, “impropers”, “ureybradleys”, “cmaps”}

      - outside (bool (optional)) – Whether to include connections involving atoms outside this group.

    Returns:

      - TopologyGroup – containing the bonded group of choice, i.e. bonds, angles, dihedrals, impropers, ureybradleys or cmaps.

      - .. versionadded:: 1.1.0

  property ix

    Unique index of this component.

    If this component is an `Atom`, this is the index of the `Atom`. If it is a `Residue`, this is the index of the `Residue`. If it is a `Segment`, this is the index of the `Segment`.

  property ix_array

    Unique index of this component as an array.

    This method gives a consistent API between components and groups.

    See also

    `ix`

  property position

    Coordinates of the atom.

    The position can be changed by assigning an array of length (3,).

    Note

    changing the position is not reflected in any files; reading any frame from the trajectory will replace the change with that from the file

    Raises:

      NoDataError – If the underlying `Timestep` does not contain `positions`.

  property velocity

    Velocity of the atom.

    The velocity can be changed by assigning an array of shape `(3,)`.

    Note

    changing the velocity is not reflected in any files; reading any frame from the trajectory will replace the change with that from the file

    Raises:

      NoDataError – If the underlying `Timestep` does not contain `velocities`.

class MDAnalysis.core.groups.Residue(*args, **kwargs)

  `Residue` base class.

  This class is used by a `Universe` for generating its Topology-specific `Residue` class. All the `TopologyAttr` components are obtained from `ComponentBase`, so this class only includes ad-hoc methods specific to `Residues`.

  property atoms

    An `AtomGroup` of `Atoms` present in this `Residue`.

  property bfactors

    Bfactor alias with warning

    Note

    This requires the underlying topology to have tempfactors. Otherwise, a `NoDataError` is raised.

  chi1_selection(n_name='N', ca_name='CA', cb_name='CB', cg_name='CG CG1 OG OG1 SG')

    Select AtomGroup corresponding to the chi1 sidechain dihedral `N-CA-CB-*G.` The gamma atom is taken to be the heavy atom in the gamma position. If more than one heavy atom is present (e.g. CG1 and CG2), the one with the lower number is used (CG1).

    Warning

    This numbering of chi1 atoms here in following with the IUPAC 1970 rules. However, it should be noted that analyses which use dihedral angles may have different definitions. For example, the `MDAnalysis.analysis.dihedrals.Janin` class does not incorporate amino acids where the gamma atom is not carbon, into its chi1 selections.

    Parameters:

      - c_name (str (optional)) – name for the backbone C atom

      - ca_name (str (optional)) – name for the alpha-carbon atom

      - cb_name (str (optional)) – name for the beta-carbon atom

      - cg_name (str (optional)) – name for the gamma-carbon atom

    Returns:

      4-atom selection in the correct order. If no CB and/or CG is found then this method returns `None`.

    Return type:

      AtomGroup

    Added in version 0.7.5.

    Changed in version 1.0.0: Added arguments for flexible atom names and refactored code for faster atom matching with boolean arrays.

    Note

    This requires the underlying topology to have names. Otherwise, a `NoDataError` is raised.

  get_connections(typename, outside=True)

    Get bonded connections between atoms as a `TopologyGroup`.

    Parameters:

      - typename (str) – group name. One of {“bonds”, “angles”, “dihedrals”, “impropers”, “ureybradleys”, “cmaps”}

      - outside (bool (optional)) – Whether to include connections involving atoms outside this group.

    Returns:

      - TopologyGroup – containing the bonded group of choice, i.e. bonds, angles, dihedrals, impropers, ureybradleys or cmaps.

      - .. versionadded:: 1.1.0

  property ix

    Unique index of this component.

    If this component is an `Atom`, this is the index of the `Atom`. If it is a `Residue`, this is the index of the `Residue`. If it is a `Segment`, this is the index of the `Segment`.

  property ix_array

    Unique index of this component as an array.

    This method gives a consistent API between components and groups.

    See also

    `ix`

  omega_selection(c_name='C', n_name='N', ca_name='CA')

    Select AtomGroup corresponding to the omega protein backbone dihedral CA-C-N’-CA’.

    omega describes the -C-N- peptide bond. Typically, it is trans (180 degrees) although cis-bonds (0 degrees) are also occasionally observed (especially near Proline).

    Parameters:

      - c_name (str (optional)) – name for the backbone C atom

      - n_name (str (optional)) – name for the backbone N atom

      - ca_name (str (optional)) – name for the alpha-carbon atom

    Returns:

      - AtomGroup – 4-atom selection in the correct order. If no C’ found in the previous residue (by resid) then this method returns `None`.

      - .. versionchanged:: 1.0.0 – Added arguments for flexible atom names and refactored code for faster atom matching with boolean arrays.

    Note

    This requires the underlying topology to have names. Otherwise, a `NoDataError` is raised.

  phi_selection(c_name='C', n_name='N', ca_name='CA')

    Select AtomGroup corresponding to the phi protein backbone dihedral C’-N-CA-C.

    Parameters:

      - c_name (str (optional)) – name for the backbone C atom

      - n_name (str (optional)) – name for the backbone N atom

      - ca_name (str (optional)) – name for the alpha-carbon atom

    Returns:

      - AtomGroup – 4-atom selection in the correct order. If no C’ found in the previous residue (by resid) then this method returns `None`.

      - .. versionchanged:: 1.0.0 – Added arguments for flexible atom names and refactored code for faster atom matching with boolean arrays.

    Note

    This requires the underlying topology to have names. Otherwise, a `NoDataError` is raised.

  psi_selection(c_name='C', n_name='N', ca_name='CA')

    Select AtomGroup corresponding to the psi protein backbone dihedral N-CA-C-N’.

    Parameters:

      - c_name (str (optional)) – name for the backbone C atom

      - n_name (str (optional)) – name for the backbone N atom

      - ca_name (str (optional)) – name for the alpha-carbon atom

    Returns:

      - AtomGroup – 4-atom selection in the correct order. If no N’ found in the following residue (by resid) then this method returns `None`.

      - .. versionchanged:: 1.0.0 – Added arguments for flexible atom names and refactored code for faster atom matching with boolean arrays.

    Note

    This requires the underlying topology to have names. Otherwise, a `NoDataError` is raised.

  property segment

    The `Segment` this `Residue` belongs to.

class MDAnalysis.core.groups.Segment(*args, **kwargs)

  `Segment` base class.

  This class is used by a `Universe` for generating its Topology-specific `Segment` class. All the `TopologyAttr` components are obtained from `ComponentBase`, so this class only includes ad-hoc methods specific to `Segments`.

  Deprecated since version 0.16.2: Instant selectors of `Segments` will be removed in the 1.0 release.

  Changed in version 1.0.0: Removed instant selectors, use either segment.residues[…] to select residue by number, or segment.residues[segment.residue.resnames = …] to select by resname.

  property atoms

    An `AtomGroup` of `Atoms` present in this `Segment`.

  property bfactors

    Bfactor alias with warning

    Note

    This requires the underlying topology to have tempfactors. Otherwise, a `NoDataError` is raised.

  get_connections(typename, outside=True)

    Get bonded connections between atoms as a `TopologyGroup`.

    Parameters:

      - typename (str) – group name. One of {“bonds”, “angles”, “dihedrals”, “impropers”, “ureybradleys”, “cmaps”}

      - outside (bool (optional)) – Whether to include connections involving atoms outside this group.

    Returns:

      - TopologyGroup – containing the bonded group of choice, i.e. bonds, angles, dihedrals, impropers, ureybradleys or cmaps.

      - .. versionadded:: 1.1.0

  property ix

    Unique index of this component.

    If this component is an `Atom`, this is the index of the `Atom`. If it is a `Residue`, this is the index of the `Residue`. If it is a `Segment`, this is the index of the `Segment`.

  property ix_array

    Unique index of this component as an array.

    This method gives a consistent API between components and groups.

    See also

    `ix`

  property residues

    A `ResidueGroup` of `Residues` present in this `Segment`.

### 12.2.2.1.3. Levels

Each of the above classes has a level attribute. This can be used to verify that two objects are of the same level, or to access a particular class

    u = mda.Universe()

    ag = u.atoms[:10]
    at = u.atoms[11]

    ag.level == at.level  # Returns True

    ag.level.singular  # Returns Atom class
    at.level.plural  # Returns AtomGroup class