Mean Square Displacement’s documentation

C++ API

namespace msd

Functions

template<class T>
std::vector<T> mean_square_displacement(const std::span<T> &signal, device dev, int number_signals, int signal_size, int dimensions)

Computes the mean square displacement (MSD) of a group of trajectories (signals) in a specified number of dimensions over time.

This function calculates the average squared displacement of particles over time, which is useful in analyzing diffusion and dynamic properties in simulations or experiments.

The input signal is assumed to be flattened and structured such that the position of particle i at time t in dimension k is stored in: 

signal[j + signal_size * (dimensions * i + k)]

where:

  • j is the time index (0 ≤ j < signal_size),

  • i is the particle index (0 ≤ i < number_signals),

  • k is the spatial dimension (0 ≤ k < dimensions).

Template Parameters:

T – Numeric data type (e.g., float, double).

Parameters:

  • signal – A span over the flattened signal data.

  • dev – The execution device (e.g., CPU, GPU).

  • number_signals – The number of individual trajectories (particles).

  • signal_size – The number of time points per trajectory.

  • dimensions – The number of spatial dimensions (e.g., 2 for 2D, 3 for 3D).

Returns:

A vector of type T containing the MSD values for each time lag.

Python API

mean_square_displacement.mean_square_displacement(signal: numpy.ndarray[shape=(*, *, *), order='C', device='cpu'], device: str = 'cpu') → numpy.ndarray[order='F', device='cpu']

Compute the mean square displacement (MSD) of a set of particle trajectories over time.

Parameters:

  • signal (ndarray[float32 or float64, shape=(N, D, T)]) –

    A 3D array containing the trajectories of N particles over T time steps in D spatial dimensions. So that:

    signal[i, k, j] = position of particle i in dimension k at time j

  • device (str, optional) – The device to perform computation on. Options are: - ‘cpu’ (default) - ‘gpu’

Returns:

A 2D array of shape (T, D) containing the mean square displacement for each time lag and each dimension, averaged for all particles.

Return type:

ndarray

Notes

The function internally flattens the data and dispatches it to a C++ backend that performs the MSD computation efficiently. The output shares the same data type as the input (float32 or float64).