MSD Module

Overview

freud.msd.MSD

Compute the mean squared displacement.

Details

The freud.msd module provides functions for computing the mean-squared-displacement (MSD) of particles in periodic systems.

MSD

class freud.msd.MSD(box=None, mode=None)

Compute the mean squared displacement.

The mean squared displacement (MSD) measures how much particles move over time. The MSD plays an important role in characterizing Brownian motion, since it provides a measure of whether particles are moving according to diffusion alone or if there are other forces contributing. There are a number of definitions for the mean squared displacement. This function provides access to the two most common definitions through the mode argument.

  • 'window' (default): This mode calculates the most common form of the MSD, which is defined as

    \[MSD(m) = \left\langle\frac{1}{N-m} \sum_{k=0}^{N-m-1} (\vec{r}(k+m) - \vec{r}(k))^2\right\rangle_{particles}\]

    According to this definition, the mean squared displacement is the average displacement over all windows of length \(m\) over the course of the simulation. Therefore, for any \(m\), \(MSD(m)\) is averaged over all windows of length \(m\) and over all particles. This calculation can be accessed using the ‘window’ mode of this function.

    The windowed calculation can be quite computationally intensive. To perform this calculation efficiently, we use the algorithm described in [Calandrini2011] as described in this StackOverflow thread.

  • 'direct': Under some circumstances, however, we may be more interested in calculating a different quantity described by

    \begin{eqnarray*} MSD(t) = &\langle (\vec{r}-\vec{r}_0)^2 \rangle_{particles} \\ = & \dfrac{1}{N} \sum_{n=1}^N (x_n(t) - x_n(0))^2 \\ \end{eqnarray*}

    In this case, we simply compute how much particles have moved from their initial position, averaged over all particles. For more information on this calculation, see the Wikipedia page.

Note

The MSD is only well-defined when the box is constant over the course of the simulation. Additionally, the number of particles must be constant over the course of the simulation.

Module author: Vyas Ramasubramani <vramasub@umich.edu>

New in version 1.0.

Parameters
  • box (freud.box.Box, optional) – If not provided, the class will assume that all positions provided in calls to compute() or accumulate() are already unwrapped.

  • mode (str, optional) – Mode of calculation. Options are 'window' and 'direct'. (Default value = 'window').

Variables
  • box (freud.box.Box) – Box used in the calculation.

  • msd (\(\left(N_{frames}, \right)\) numpy.ndarray) – The mean squared displacement.

accumulate

Calculate the MSD for the positions provided and add to the existing per-particle data.

Note

Unlike most methods in freud, accumulation for the MSD is split over particles rather than frames of a simulation. The reason for this choice is that efficient computation of the MSD requires using the entire trajectory for a given particle. As a result, this accumulation is primarily useful when the trajectory is so large that computing an MSD on all particles at once is prohibitive.

Parameters
  • positions ((\(N_{frames}\), \(N_{particles}\), 3) numpy.ndarray) – The particle positions over a trajectory. If neither box nor images are provided, the positions are assumed to be unwrapped already.

  • images ((\(N_{frames}\), \(N_{particles}\), 3) numpy.ndarray, optional) – The particle images to unwrap with if provided. Must be provided along with a simulation box (in the constructor) if particle positions need to be unwrapped. If neither are provided, positions are assumed to be unwrapped already.

compute

Calculate the MSD for the positions provided.

Parameters
  • positions ((\(N_{frames}\), \(N_{particles}\), 3) numpy.ndarray) – The particle positions over a trajectory. If neither box nor images are provided, the positions are assumed to be unwrapped already.

  • images ((\(N_{frames}\), \(N_{particles}\), 3) numpy.ndarray, optional) – The particle images to unwrap with if provided. Must be provided along with a simulation box (in the constructor) if particle positions need to be unwrapped. If neither are provided, positions are assumed to be unwrapped already.

reset

Clears the stored MSD values from previous calls to accumulate (or the last call to compute).