msd

A module containing the MSD class. The MSD class is used to calculate the mean square displacement (MSD) of a selection of atoms using multiple time origins on a sliding window. The MSD is a measure of the average squared distance particles travel within a given correlation time and gives access to the self-diffusion coefficient via the Einstein relation.

Summary

Classes:

`MSD`	A class for calculating the mean square displacement (MSD) of a target selection using multiple simultaneously active time origins.
`MSDDiffusionFit`	A container for the result of a linear diffusion fit of an MSD component.

Reference

Bases: object

A class for calculating the mean square displacement (MSD) of a target selection using multiple simultaneously active time origins.

A new time origin is spawned every gap frames until window // gap origins are active. Every frame, each active origin accumulates the squared displacement of every selected atom relative to the origin position into the lag bin given by the frame distance to the origin. Displacements are unwrapped with a running minimum image convention applied to the per-frame displacement vectors, so that trajectories wrapped into the simulation box are handled correctly. When the oldest origin has covered the full window, it accumulates its final lag term and is replaced by a new origin (or dropped without replacement once no new origins may spawn anymore).

This is a port of the Diffcalc tool of thh_tools and reproduces its results exactly, including its normalization convention: every lag bin is divided by the number of selected atoms times total_origins, where total_origins = stop_frame // gap and stop_frame = (n_frames - window) // gap * gap. Note that this normalization intentionally follows the legacy code also for n_start > 0. The legacy boundary case of a trajectory of exactly window frames with gap == 1 is also kept: a single time origin spawns at the first frame and the final lag bin (lag == window), which can never be sampled, is written as exactly 0.0 (a warning is emitted). Any shorter trajectory raises an MSDError.

If a time step is given, the trailing fit_window points of the MSD components are fitted linearly to extract self-diffusion coefficients via the Einstein relation (slope / (2 * dimensionality), converted to m^2/s).

The MSD class can be initialized with either a trajectory object or via a TrajectoryReader object. The TrajectoryReader allows for lazy loading of the trajectory, which is useful for large trajectories that do not fit into memory. For xyz trajectory files the frames are streamed via the raw-frame fast path (RawTrajectoryReader) and accumulated with a compiled kernel, which is considerably faster and produces identical results.

Parameters:

traj (Trajectory | TrajectoryReader) – The trajectory to analyze. If a TrajectoryReader is provided, the trajectory is read frame by frame via a frame_generator.
target_species (SelectionCompatible) – The target species of the MSD analysis.
use_full_atom_info (bool | None, optional) – Whether to use the full atom information of the trajectory or not, by default None (False).
window (PositiveInt | None, optional) – The correlation window size in frames, by default None (1000).
gap (PositiveInt | None, optional) – The gap between two time origins in frames, by default None (10).
n_start (int | None, optional) – The first frame (1-based frame counter) at which processing starts, by default None (0). Frames before n_start are read (to keep the unwrapping continuous) but do not contribute to the MSD.
time_step (PositiveReal | None, optional) – The time step between two frames in ps. If given, diffusion coefficients are calculated from a linear fit of the MSD tail, by default None.
fit_window (PositiveInt | None, optional) – The number of trailing MSD points used for the diffusion fit, by default None (last 20% of the window).

Raises:

MSDError – If n_start is negative.
MSDError – If the window is not a multiple of the gap.
MSDError – If time_step is not positive.
MSDError – If fit_window is smaller than 2.
MSDError – If fit_window is larger than window + 1.
MSDError – If the trajectory is empty.
MSDError – If the target selection is empty.
MSDError – If the trajectory is too short to establish at least one full window (n_frames < window + gap and not the legacy single-origin case of exactly window frames with gap == 1).
MSDError – If n_start is larger than stop_frame, so that no time origin could spawn.