wrap

mdtools.box.wrap(ag, compound='atoms', center='cog', box=None, inplace=True, debug=False)

Shift compounds of an MDAnalysis AtomGroup back into the primary unit cell.

Todo

Include a make_whole argument that makes compounds whole after the wrapping, even if this implies that some Atoms might lie outside the primary unit cell again.

Parameters:

• ag (MDAnalysis.core.groups.AtomGroup instance) – The MDAnalysis AtomGroup whose compounds shall be wrapped back into the primary unit cell.

• compound ({'atoms', 'group', 'segments', 'residues', 'molecules', 'fragments'}, optional) – Which type of compound to keep together during wrapping. Atoms belonging to the same compound are shifted by the same translation vector such that the center of the compound lies within the box. This might however mean that not all Atoms of the compound will be inside the unit cell after wrapping. Default is 'atoms', which means that each Atom of ag is shifted by its individual translation vector so that finally all Atoms of ag will be inside the unit cell. Refer to the MDAnalysis’ user guide for an explanation of these terms. 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. Also note that broken compounds are note made whole by this function.

• center ({'cog', 'com'}, optional) – How to define the center of a compound. Parse 'cog' for center of geometry or 'com' for center of mass. If compound is 'atoms', this parameter is meaningless and therefore ignored.

• box (array_like, optional) – The unit cell dimensions of the system, which can be orthogonal or triclinic and must be provided in the same format as returned by MDAnalysis.coordinates.base.Timestep.dimensions: [lx, ly, lz, alpha, beta, gamma]. If None, the dimensions of the current Timestep will be used.

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

• debug (bool, optional) – If True, run in debug mode.

Returns:

wrapped_pos (numpy.ndarray) – Array of wrapped Atom coordinates of dtype numpy.float32 and shape (ag.n_atoms, 3).

See also

MDAnalysis.core.groups.AtomGroup.wrap()

Shift compounds of the AtomGroup back into the primary unit cell

MDAnalysis.core.groups.AtomGroup.pack_into_box()

Shift all Atoms in the AtomGroup into the primary unit cell

MDAnalysis.lib.distances.apply_PBC()

Shift coordinates stored as numpy.ndarray into the primary unit cell

mdtools.box.wrap_pos()

Shift all particle positions into the primary unit cell

mdtools.box.make_whole()

Make compounds of a MDAnalysis AtomGroup whole

Notes

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

When calling this function with compounds set to something different than 'atoms', make sure that the respective compounds are whole. Broken compounds will not be made whole by this function. See mdtools.box.make_whole() for a possibility to make compounds whole that are split across periodic boundaries.

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.