unwrap_trj
- mdtools.box.unwrap_trj(topfile, trjfile, universe, atm_grp, end=-1, make_whole=False, keep_whole=False, compound='fragments', reference='com', verbose=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. The coordinates are changed inplace.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()
is thatunwrap()
only unwraps a single frame while this function unwraps the complete trajectory.- Parameters:
topfile, trjfile (
str
) – Because any changes to thepositions
attribute of aAtomGroup
are overwritten each time the frame of thetrajectory
is changed (except if thetrajectory
is held in memory), the changes are written to a new trajectory. The name of the new (unwrapped) trajectory is given by trjfile and the name of the corresponding topology is given by topfile. Only the atoms of atm_grp are written to the new trajectory. When the unwrapping precedure is done, you can create a new universe from this unwrapped trajectory and topology. See the MDAnalysis user guide for supported file formats.universe (
MDAnalysis.core.universe.Universe
) – The universe holding the trajectory andAtomGroup
to unwrap. You cannot pass aMDAnalysis.coordinates.base.FrameIteratorSliced
here, since unwrapping always has to start with the first frame and is much safer if every single frame is considered, because the algorithm only works if particles do not move more than half the box length in one step. If you want to unwrap the trajectory only until a certain point, use the end argument.atm_grp (
MDAnalysis.core.groups.AtomGroup
) – TheAtomGroup
whose atoms should be unwrapped into real space. TheAtomGroup
must not be anUpdatingAtomGroup
.end (
int
, optional) – Last frame to unwrap (exclusive, i.e. the last frame to unwrap is actuallyend-1
). A negative value means unwrap the complete trajectory.make_whole (
bool
, optional) – IfTrue
, make the compounds of atm_grp that are split across the simulation box edges whole again for each individual frame before unwrapping.keep_whole (
bool
, optional) – If the molecules in the universe are already whole for each frame, it is sufficient to start from a structure with (at least a part of) the whole molecules in the primary unit cell and then propagate these whole molecules in real space instead of making the molecules whole for each individual frame. Note that make_whole takes precedence over keep_whole.compound (
str
, optional) – Which type of component to make whole. Must be either'group'
,'segments'
,'residues'
,'molecules'
or'fragments'
. Seemake_whole()
for more details. Is meaningless if make_whole and keep_whole areFalse
.reference (
str
, optional) – If ‘com’ (center of mass) or ‘cog’ (center of geometry), the compounds that were made whole will be shifted so that their individual reference point lies within the primary unit cell. If None, no such shift is performed. This only affects the starting structure from which to begin the unwrapping, since the displacements, which are calculated according to the minimum image convention, (should) stay the same. Is meaningless if make_whole and keep_whole areFalse
.verbose (
bool
, optional) – IfTrue
, print progress information to standard output.debug (
bool
, optional) – IfTrue
, check the input arguments.