Add the nearest option for wrapping tajectories with triclinic periodic cells. Matches the behavior of NAMD's wrapNearest option. Allows for visualizing the cell as a rhombic dodecahedron (sample data from Chen Lin et al.).
Offer both the lattice-based and torus-based Büllerjahn et al unwrapping schemes, via qunwrap and qunwrap_tor respectively. qunwrap_tor is particularly suited for unwrapping constant-pressure trajectories with the aim of computing diffusion coefficients.
Remove dynamically linked Tcl library and link tclstub library statically instead. This should make the shared object more portable.
This version reverts the change of unwrapping algorithm of the previous version, which was found to lead to distortion of molecules when unwrapping Gromacs trajectories atom-wise (compound none). Shifts are again computed as integer factors of the current cell basis vectors.
It turns out that the von Bülow unwrapping algorithm is not well-suited to qwrap's special treatment of groups of atoms (compounds), and I expect the bias in long-time diffusion from the qunwrap algorithm to be negligible.
As of version 1.4, unwrapping is done according to the algorithm of von Bülow, Bullerjahn and Hummer (https://arxiv.org/pdf/2003.09205.pdf) to obtain correct diffusion coefficient at long times. Note that the algorithm used up to version 1.3 was already similar to this one, and gave only small, bounded deviations from the true long-time diffusion.
On Linux, you can just download the file Linux/qwrap.so, save it somewhere and remember its full path.
First make sure Tcl development packages are installed (tcl-dev or tcl-devel).
tar xf qwrap.tar.gz (in own directory)
make
Optionally, install as a VMD plugin:
# update the PLUGINDIR variable in Makefile
make install
# use 'sudo make install' if VMD is installed system-wide rather than in your user directory
In the VMD terminal or TkConsole, type:
load <path>/qwrap.so
You can use the absolute or relative path, including '.' for the local directory. Or, if you have installed qwrap as a VMD plugin:
package require qwrap
You can now use the qwrap and qunwrap commands.
For Macs with ARM64 processors (M1, M2, M3 etc.), try adapting the paths in Makefile.OSX_ARM64 and running:
make -f Makefile.OSX_ARM64
Some VMD builds for macOS (e.g. 2.0 alphas) use the hardened runtime, which refuses to load self-built (ad-hoc signed) libraries (see #9). If loading qwrap.so fails with a code-signature error, re-sign the VMD executable with the disable-library-validation entitlement (this modifies the VMD app in place; existing entitlements are kept):
make -f Makefile.OSX_ARM64 sign-vmd VMDAPP="/Applications/VMD 2.0.0a7-pre2.app"
# set VMDBIN=... if the executable is not at Contents/vmd2/lib/vmd_MACOSXARM64
To use in VMD:
qwrap [first n] [last n] [compound none|res|beta|fragment [refatoms occ|none]] [center <seltext>] [centerx <seltext>] [centery <seltext>] [centerz <seltext>] [sel <seltext>] [nearest yes|no]
qunwrap [first n] [last n] [compound none|res|beta|fragment [refatoms occ|none]] [sel <seltext>]
sel: selection text indicating atoms to be wrappedfirst,last: frames to be wrapped (defaults: 0 to -1, which means the last frame).compound: wrap groups of atoms instead of individual atoms. Groups can be VMD'sresidues or bondedfragments (default), or custom groups defined by a common integer value of thebetaparameter. The default option (fragment) corresponds to the wrapping behavior of NAMD; however it only works correctly if VMD has accurate connectivity information (eg. read from a PSF file). To undo GROMACS-style, atom-wise wrapping, usecompound none.refatoms: ifcompoundis set, each group may be wrapped according to its geometric center, or to the center of a set of reference atoms within the group. Then reference atoms are defined by nonzerooccupancy (when converted to integer, that is, greater than 1). An example use is to wrap lipid molecules as residues, and give all phosphorus atoms nonzero occupancy so that each lipid has its phosphorus atom in the center unit cell.
center: the geometric center of the given selection text will be translated to (0, 0, 0).centerx,centery,centerz: use a different center selection for one axis. Ifcenteris also given, it is used for the other axes.nearest yes: enable wrapping for non-orthorhombic cells by translating each wrapping block's reference point to its nearest periodic image. This is useful for visualization of truncated-octahedron cells. The default isno; non-orthorhombic cells otherwise produce an error. Orthorhombic cells continue to use the existing fast path.
A classic use to wrap the solvent around a protein would be:
qwrap sel "not protein" center protein
To use the normal protein center in x/y while centering z on a membrane selection:
qwrap sel all compound fragment \
center protein \
centerz "segname MEMB"
To repair a protein complex that has been split across PBC by NAMD (wrapAll), load a trajectory where the first frame has the oligomer in one piece, then run:
qunwrap sel protein
You can then run the command above to wrap the solvent around the complex.
To unwrap a GROMACS trajectory, make sure that the first frame has all molecules in one piece and run:
qunwrap compound none
Wrapping groups can be defined either as residues, by fragment, or by setting custom flags in the beta field. The flags should be integers, and could be alternating 0s and 1s or anything else, they only need to change when the next atom belongs to a different wrapping group. Compound-based wrapping can use a custom set of reference atoms; the reference position of each wrapping group (compound) is the center of the reference atoms contained within this block (it may be a single atom). If refatoms is not defined, the reference position is the center of the whole group.
Compared with PBCTools, qwrap is a less flexible tool (the cell center is fixed at (0,0,0), and qunwrap supports orthorhombic cells only), but it is many times faster.
Please let me know if it is useful, and if you improve it, share it back!