unwrap
- mdtools.box.unwrap(atm_grp, coord_unwrapped_prev, displacement=None, inplace=False, debug=False)[source]
Unwrap the atoms of a MDAnalysis
AtomGroup
out of the primary unit cell, i.e. calculate their coordinates in real space.This function uses the algorithm proposed by von Bülow et al. in J. Chem. Phys., 2020, 153, 021101. Basically it calculates the atom displacements from frame to frame and adds these displacements to the previous atom positions to build the unwraped trajectory.
The main difference to
unwrap_trj()
is thatunwrap_trj()
unwraps the complete trajectory while this function only unwraps a single frame based on the unwrapped coordinates of the previous frame.Note
If you want to change the
positions
attribute of theAtomGroup
to the outcome of this function, keep in mind that changing atom positions is not reflected in any file; reading any frame from thetrajectory
will replace the change with that from the file except if thetrajectory
is held in memory, e.g., when thetransfer_to_memory()
method was used.- Parameters:
atm_grp (
MDAnalysis.core.groups.AtomGroup
) – TheAtomGroup
whose atoms should be unwrapped into real space.coord_unwrapped_prev (
array_like
) – Array of the same shape asatm_grp.positions.shape
containing the unwrapped coordinates of atm_grp from the previous frame. When starting the unwrapping, coord_unwrapped_prev should be the wrapped coordinates of atm_grp from the very first frame and atm_grp should be parsed from the second frame so thatatm_grp.positions
contains the atom coordinates of atm_grp from the second frame. For all further frames, coord_unwrapped_prev should be the result of this function and atm_grp should be parsed from next frame.displacement (
numpy.ndarray
, optional) – Preallocated temporary array of the same shape asatm_grp.positions.shape
and dtypenumpy.float64
. If provided, this array is used to store the displacement vectors from the previous (coord_unwrapped_prev) to the current (atm_grp.positions
) frame. Avoids creating the array which saves time when the function is called repeatedly and additionally the displacement vectors can be used outside this function for further analyses. But bear in mind that this array is overwritten each time this function is called.inplace (
bool
, optional) – IfTrue
, change coord_unwrapped_prev inplace to the unwrapped coordinates of the current framedebug (
bool
, optional) – IfTrue
, check the input arguments. Default:False
- Returns:
coord_unwrapped (
numpy.ndarray
) – The unwrapped coordinates of atm_grp at the current frame, nominallycoord_unwrapped_prev + displacement
.