10.4.1. Core functions of MDAnalysis

The basic class is an AtomGroup; the whole simulation is called the Universe. Selections are computed on an AtomGroup and return another AtomGroup.

To get started, load the Universe:

u = Universe(topology_file, trajectory_file)

A simple selection of all water oxygens within 4 A of the protein:

water_shell = u.select_atoms('name OH2 and around 4.0 protein')
water_shell.n_atoms           # how many waters were selected
water_shell.total_mass()       # their total mass

AtomGroup instances have various methods that allow calculation of simple properties. For more complicated analysis, obtain the coordinates as a numpy array

coords = water_shell.positions

and write your own Python code.

10.4.1.1. Flags

Deprecated since version 0.16.2: The flags registry will be removed in release 1.0. Use keyword arguments for functions to obtain the desired behavior. See issue #782 for more details.

(This is an advanced topic and can probably be skipped by most people.)

There are a number flags that influence how MDAnalysis behaves. They are accessible through the pseudo-dictionary MDAnalysis.core.flags.

The entries appear as ‘name’-‘value’ pairs. Flags check values and illegal ones raise a ValueError. Documentation on all flags can be obtained with

print(MDAnalysis.core.flags.doc())

10.4.1.1.1. List of MDAnalysis flags with default values

class MDAnalysis.core.__init__.flagsDocs[source]

use_periodic_selections = True

Determines if distance selections (AROUND, POINT) respect periodicity.

>>> flags['use_periodic_selections'] = value
Values of flag:

  • True - periodicity is taken into account if supported

  • False - periodicity is ignored

The MDAnalysis preset of this flag is True.

use_KDTree_routines = ‘fast’

Determines which KDTree routines are used for distance selections

>>> flags['use_KDTree_routines'] = value

Values for flag:

  • True, ‘fast’ - only use KDTree routines that are typically faster than others - POINT uses distance matrix routines (with periodicity) - AROUND uses KDTree routines (always ignores periodicity)

  • ‘always’ - always use KDTree routines where available (eg for benchmarking)

  • False, ‘never’ - always use alternatives

The preset value for MDAnalysis is ‘fast’.

MDAnalysis.lib.KDTree routines are significantly faster for some distance selections. However, they cannot deal with periodic boxes and thus ignore periodicity; if periodicity is crucial, disable KDTree routines with

>>> MDAnalysis.core.flags['use_KDTree_routines'] = False

convert_lengths = True

Determine if trajectory reader and writer converts length units between native and MDAnalysis default.

>>> flags['convert_lengths'] = value

Some trajectories are in other length units than the MDAnalysis default (see the flag length_unit); e.g. Gromacs XTC and TRR trajectories are in nm. If True then coordinates are automatically converted, with False the coordinate values are presented as read from the trajectories.

Note

The conversion of lengths also affects conversion of velocities.

length_unit = ‘Angstrom’

Base unit for lengths (in particular coordinates in trajectories)

>>> flags['length_unit'] = value

Warning

Do not change, only Angstrom fully supported.

time_unit = ‘ps’

Base unit for times (in particular time steps in trajectories)

>>> flags['time_unit'] = value

speed_unit = ‘Angstrom/ps’

Base unit for speed (in particular velocities in trajectories)

>>> flags['speed_unit'] = value

force_unit = ‘kJ/(mol*Angstrom)’

Base unit for forces (in particular forces in trajectories)

>>> flags['force_unit'] = value

charge_unit = ‘e’

Base unit for charge

>>> flags['charge_unit'] = value

use_pbc = False

Choose whether to consider periodic boundary conditions when performing many MDAnalysis.core.groups.AtomGroup methods. This is set to False by default but can be enabled with:

>>> MDAnalysis.core.flags['use_pbc'] = True

Values for flag:

  • True - Move all atoms within the primary unit cell before calculation

  • False - Use coordinates as supplied

Warning

Changing this to True changes the default behaviour of commonly used MDAnalysis.core.groups.AtomGroup methods such as MDAnalysis.core.groups.AtomGroup.center_of_mass() and MDAnalysis.core.groups.AtomGroup.center_of_geometry()!

10.4.1.1.2. Classes

MDAnalysis.core.__init__.flags
class MDAnalysis.core.__init__.Flags(*args)[source]

Global registry of flags. Acts like a dict for item access.

There are a number flags defined that influence how MDAnalysis behaves. They are accessible through the pseudo-dictionary

MDAnalysis.core.flags

The entries appear as ‘name’-‘value’ pairs. Flags check values and illegal ones raise a ValueError. Documentation on all flags can be obtained with

print(MDAnalysis.core.flags.__doc__)

New flags are added with the Flags.register() method which takes a new Flag instance as an argument.

Deprecated since version 0.16.2: The flags registry will be removed in release 1.0. Use keyword arguments for functions to obtain the desired behavior. See issue #782 for more details.

For DEVELOPERS: Initialize Flags registry with a list of Flag instances.

doc()[source]

Shows doc strings for all flags.

items() → a set-like object providing a view on D's items[source]
register(flag)[source]

Register a new Flag instance with the Flags registry.

setdefault(k, d=None)[source]

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update(*flags)[source]

Update Flags registry with a list of Flag instances.

values() → an object providing a view on D's values[source]
class MDAnalysis.core.__init__.Flag(name, default, mapping=None, doc=None)[source]

A Flag, essentially a variable that knows its default and legal values.

Deprecated since version 0.16.2: The flags registry will be removed in release 1.0. Use keyword arguments for functions to obtain the desired behavior. See issue #782 for more details.

Create a new flag which will be registered with Flags.

Parameters

  • name (str) – name of the flag, must be a legal python name

  • default – default value

  • mapping (dict) – dict that maps allowed input values to canonical values; if None then no argument checking will be performed and all values are directly set.

  • doc (str) –

    doc string; may contain string interpolation mappings for:

    %%(name)s        name of the flag
%%(default)r     default value
%%(value)r       current value
%%(mapping)r     mapping

    Doc strings are generated dynamically and reflect the current state.

Example

Create a new flag:

newflag = Flag(name, default, mapping, doc)
prop()[source]

Use this for property(**flag.prop())