Unwrap#

Unwrapping coordinates across periodic boundaries to restore spatial continuity.

The function molsysmt.pbc.unwrap() reconstructs continuous coordinates across structural ensembles by removing periodic jump discontinuities.

Added in version 1.0.0.

API documentation

Follow this link for a detailed description of the input arguments, raised errors, and returned objects of this function: molsysmt.pbc.unwrap().

Basic usage#

Let’s demonstrate unwrapping on an ensemble with periodic boundary crossing:

import molsysmt as msm
import numpy as np
import matplotlib.pyplot as plt

molsys = msm.convert(msm.systems['two LJ particles']['traj_two_lj_particles.trjpk'], to_form='molsysmt.StructuresDict')

Note

Demo Systems Catalog

This tutorial uses demonstration datasets provided by MolSysMT. To explore the full catalog of bundled systems, forms, and file paths, visit the Demo Systems guide.

We wrap the coordinates into the primary periodic box and then restore continuous trajectories using molsysmt.pbc.unwrap():

molsys_wrapped = msm.pbc.wrap_to_pbc(molsys)
molsys_unwrapped = msm.pbc.unwrap(molsys_wrapped)

We visualize the coordinate evolution before and after unwrapping to verify temporal continuity:

fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(10, 4))
time = molsys_wrapped['time']

ax1.plot(time, molsys_wrapped['coordinates'][:, 0, 0], label='Particle 0 (X)', color='navy')
ax1.set_title('Wrapped Coordinates (PBC Jumps)')
ax1.set_xlabel('Time (ps)')
ax1.set_ylabel('Coordinate (nm)')
ax1.grid(True, linestyle='--', alpha=0.5)

ax2.plot(time, molsys_unwrapped['coordinates'][:, 0, 0], label='Particle 0 (X)', color='teal')
ax2.set_title('Unwrapped Coordinates (Continuous)')
ax2.set_xlabel('Time (ps)')
ax2.set_ylabel('Coordinate (nm)')
ax2.grid(True, linestyle='--', alpha=0.5)

plt.tight_layout()
plt.show()

../../../../_images/f645e4e1aaa848c8c6959ed6f819684698d32d9457b5fa4121c23c37cf8376c0.png