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 that unwrap_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 the AtomGroup to the outcome of this function, keep in mind that changing atom positions is not reflected in any file; 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.

Parameters

  • atm_grp (MDAnalysis.core.groups.AtomGroup) – The AtomGroup whose atoms should be unwrapped into real space.

  • coord_unwrapped_prev (array_like) – Array of the same shape as atm_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 that atm_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 as atm_grp.positions.shape and dtype numpy.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) – If True, change coord_unwrapped_prev inplace to the unwrapped coordinates of the current frame

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

Returns

coord_unwrapped (numpy.ndarray) – The unwrapped coordinates of atm_grp at the current frame, nominally coord_unwrapped_prev + displacement.