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 that unwrap() only unwraps a single frame while this function unwraps the complete trajectory.

Parameters

  • topfile, trjfile (str) – Because any changes to the positions attribute of a AtomGroup are overwritten each time the frame of the trajectory is changed (except if the trajectory 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 and AtomGroup to unwrap. You cannot pass a MDAnalysis.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) – The AtomGroup whose atoms should be unwrapped into real space. The AtomGroup must not be an UpdatingAtomGroup.

  • end (int, optional) – Last frame to unwrap (exclusive, i.e. the last frame to unwrap is actually end-1). A negative value means unwrap the complete trajectory.

  • make_whole (bool, optional) – If True, 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'. See make_whole() for more details. Is meaningless if make_whole and keep_whole are False.

  • 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 are False.

  • verbose (bool, optional) – If True, print progress information to standard output.

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