Path A - Module 41: Wrapping & Unwrapping#

In a periodic simulation, atoms don’t stop at the wall; they “teleport” to the other side. This creates visual artifacts where a molecule appears broken or exploded across the box.

In this module, you will learn to fix these effects and keep your Alzheimer’s fibril physically whole using MolSysMT.

import molsysmt as msm
from molsysmt import systems

# Let's use a trajectory where the protein crosses the box boundaries
villin_traj = systems['chicken villin HP35']['traj_chicken_villin_HP35_solvated.dcd']
villin_topo = systems['chicken villin HP35']['chicken_villin_HP35_solvated.h5msm']
molsys = [villin_topo, villin_traj]

1. The “Broken Molecule” Problem#

If you visualize a raw trajectory, some residues might look like they have bonds several nanometers long. This is because some atoms are on one side of the box and others are on the opposite side.

2. Unwrapping for Continuity#

The function unwrap() restores each atom’s temporal continuity across successive frames. Molecular reconstruction within one frame is a separate operation controlled by keep_covalent_bonds in the wrapping functions.

# Unwrap protein atom trajectories across successive frames
unwrapped_molsys = msm.pbc.unwrap(molsys, selection='molecule_type=="protein"')

print("Protein atom trajectories are now temporally continuous.")

3. Wrapping for Compactness#

Sometimes you want the opposite: you want every atom to be inside the main unit cell (the simulation box). We use wrap_to_pbc() for this.

# Wrap all atoms (protein and water) back into the primary box
wrapped_molsys = msm.pbc.wrap_to_pbc(molsys, keep_covalent_bonds=True)

print("System wrapped. All atoms are now inside the box boundaries.")

4. Minimum Image Convention (MIC)#

When calculating distances between a peptide and a fibril, you must ensure you are measuring to the nearest periodic image. wrap_to_mic() helps ensure your coordinates are ready for these calculations.

# Wrap the peptide to the Minimum Image Convention relative to the fibril
mic_molsys = msm.pbc.wrap_to_mic(molsys, selection='molecule_type=="peptide"', 
                                 center_of_selection='molecule_type=="protein"',
                                 keep_covalent_bonds=True)
print("Peptide wrapped to the nearest image of the fibril.")

🏆 Path A Challenge: The Ghost Buster#

  1. Take the Villin trajectory.

  2. Visualize the first frame without any PBC processing.

  3. Apply msm.pbc.unwrap() and visualize it again. Can you see the difference in the protein’s shape?

  4. Use msm.pbc.wrap_to_pbc() on all water molecules and check if any water atom has a coordinate greater than the box lengths.

You are now a master of simulation space! In Module 42, we will leave the geometry behind and start talking about forces: Molecular Mechanics (Energies).