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 a
AtomGroup.select_atoms() selection or just 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).

An AtomGroup is an ordered collection of atoms. Typically, an
AtomGroup is generated from a selection, or by indexing/slicing
the AtomGroup 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.

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, 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, so as 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, and keep duplicated
atoms.

Instant selectors will be removed in the 1.0 release. See issue #1377 for more details.

Atoms can also be accessed in a Pythonic fashion by using the atom name as
an attribute. For instance,

ag.CA

will provide a AtomGroup of all CA atoms in the
group. These instant selector attributes are auto-generated for
each atom name encountered in the group.

Notes

The name-attribute instant selector access to atoms is mainly
meant for quick interactive work. Thus it either returns a
single Atom if there is only one matching atom, or a
new AtomGroup for multiple matches. This makes it
difficult to use the feature consistently in scripts.

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

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.base.Timestep.dimensions,
[lx,ly,lz,alpha,beta,gamma]. If None, uses these
timestep dimensions.

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

The positions can be changed by assigning an array of the appropriate
shape, i.e. either Nx3 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 particles to the origin).

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 except if the
trajectory is held in memory, e.g., when the
transfer_to_memory
method was used.

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.

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.

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. segid4AKE
or segidDMPC

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 resid1: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. resnameLYS

name atom-name

select by atom name (as given in the topology). Often, this is
force field dependent. Example: nameCA (for C&alpha; atoms)
or nameOW (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-nameresidue-numberatom-name

a selector for a single atom consisting of segid resid atomname,
e.g. DMPC1C2 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. moltypeProtein_A. At the
moment, only the TPR format defines the molecule type.

Boolean

not

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

and, or

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

Geometric

around distanceselection

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

point xyzdistance

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

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

sphlayer inner radiusouter radiusselection

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

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: selectnameHandbondednameO selects only hydrogens
bonded to oxygens

Index

bynum index-range

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

Preexisting selections

group group-name

selects the atoms in the AtomGroup passed to the
function as an 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("around10globalprotein") — 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.

Deprecated since version 0.11: The use of fullgroup has been deprecated in favor of the equivalent
globalgroup.

Changed in version 0.13.0: Added bonded selection

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

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

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.

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

This is a more powerful version of pack_into_box(), allowing
groups of atoms to be kept together through the process.

Parameters:

compound ({'atoms', 'group', 'residues', 'segments', 'fragments'}) – The group which will be kept together through the shifting process.

center ({'com', 'cog'}) – How to define the center of a given group of atoms.

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

Notes

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 all atoms from the compound are not
inside the unit cell, but rather the center of the compound is.

center allows the definition of the center of each group to be
specified. 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, an the dimensions information from the current Timestep will
be used.

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 os "conect".

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

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.
See Instant selectors for details and alternatives.

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.base.Timestep.dimensions,
[lx,ly,lz,alpha,beta,gamma]. If None, uses these
timestep dimensions.

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

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.

This is a more powerful version of pack_into_box(), allowing
groups of atoms to be kept together through the process.

Parameters:

compound ({'atoms', 'group', 'residues', 'segments', 'fragments'}) – The group which will be kept together through the shifting process.

center ({'com', 'cog'}) – How to define the center of a given group of atoms.

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

Notes

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 all atoms from the compound are not
inside the unit cell, but rather the center of the compound is.

center allows the definition of the center of each group to be
specified. 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, an the dimensions information from the current Timestep will
be used.

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.
See Instant selectors for details and alternatives.

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.base.Timestep.dimensions,
[lx,ly,lz,alpha,beta,gamma]. If None, uses these
timestep dimensions.

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

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.

This is a more powerful version of pack_into_box(), allowing
groups of atoms to be kept together through the process.

Parameters:

compound ({'atoms', 'group', 'residues', 'segments', 'fragments'}) – The group which will be kept together through the shifting process.

center ({'com', 'cog'}) – How to define the center of a given group of atoms.

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

Notes

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 all atoms from the compound are not
inside the unit cell, but rather the center of the compound is.

center allows the definition of the center of each group to be
specified. 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, an the dimensions information from the current Timestep will
be used.

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.

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.

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.

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.
See Instant selectors for details and alternatives.