make_whole

mdtools.box.make_whole(ag, compound='fragments', reference='cog', inplace=True, debug=False)[source]

Make compounds of a MDAnalysis AtomGroup whole that are split across periodic boundaries.

Note that all Atoms of the input AtomGroup are wrapped back into the primary unit cell before making compounds whole.

Parameters:

  • ag (MDAnalysis.core.groups.AtomGroup instance) – The MDAnalysis AtomGroup whose compounds shall be made whole.

  • compound ({'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – Which type of component to make whole. Note that in any case, all Atoms within each compound must be interconnected by bonds, i.e. compounds must correspond to (parts of) molecules. This is always fulfilled for fragments, because a MDAnalysis fragment is what is typically considered a molecule, i.e. an AtomGroup where any Atom is reachable from any other Atom in the AtomGroup by traversing bonds, and none of its Atoms is bonded to any Atom outside the AtomGroup. A ‘molecule’ in MDAnalysis refers to a GROMACS-specific concept. See the MDAnalysis user guide for further information. Note that in any case, even if compound is e.g. 'residues', only the Atoms belonging to ag are taken into account, even if the compound might comprise additional Atoms that are not contained in ag. If you want entire molecules to be made whole, make sure that all Atoms of these molecules are part of ag.

  • reference ({'cog', 'com', None}, optional) – If ‘cog’ (center of geometry) or ‘com’ (center of mass), the compounds that were made whole will be shifted such 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.

  • debug (bool, optional) – If True, check the input arguments. Default: False

Returns:

pos (numpy.ndarray) – Array of shape (ag.n_atoms, 3) containing the coordinates of all Atoms in ag after the specified compounds of ag were made whole.

See also

MDAnalysis.core.groups.AtomGroup.unwrap()

Move Atoms in the AtomGroup such that bonds within the group’s compounds aren’t split across periodic boundaries

MDAnalysis.lib.mdamath.make_whole()

Move all Atoms in an MDAnalysis AtomGroup such that bonds don’t split over periodic images

mdtools.box.wrap()

Shift compounds of a MDAnalysis AtomGroup back into the primary unit cell`

Notes

This function is just a wrapper around the unwrap() method of the input AtomGroup that additionally checks the masses of all Atoms in ag when reference is set to 'com'. See mdtools.check.masses_new() for further information.

Before making any compound whole, all Atoms in ag are wrapped back into the primary unit cell. This is done to make sure that the unwrap algorithm (better “make whole” algorithm) of unwrap() is working properly. This means that making compounds whole in an unwrapped trajectory while keeping the trajectory unwrapped is not possible with this function.

Todo

Check if it is really necessary to wrap all Atoms back into the primary unit before calling unwrap(). This is a serious problem, because it implies an inplace change of the Atom coordinates.

Because MDAnalysis will pull trajectory data directly from the file it is reading from, changes to Atom coordinates and box dimensions will not persist once the frame is changed (even if inplace is True). The only way to make these changes permanent is to load the trajectory into memory, or to write a new trajectory to file for every frame. See the MDAnalysis user guide about trajectories (second last paragraph) and in-memory trajectories.