correlation_fft

mdhelper.algorithm.correlation.correlation_fft(arr1: ndarray[float], arr2: ndarray[float] = None, axis: int = None, *, average: bool = False, double: bool = False, vector: bool = False) → ndarray[float][source]

Evaluates the autocorrelation function (ACF) or cross-correlation function (CCF) of a time series using fast Fourier transforms (FFT).

The algorithm, better known as the Fast Correlation Algorithm (FCA) [1] [2], is a result of the Wiener–Khinchin theorem and has a time complexity of \(\mathcal{O}(N\log{N})\). Effectively, the ACF can be computed from the raw data \(\mathbf{r}(t)\) with two FFTs using

\[\begin{split}\begin{gather*} \hat{\mathbf{r}}(\xi)=\mathrm{FFT}(\mathbf{r}(t))\\ A(\tau)=\mathrm{FFT}^{-1}(\hat{\mathbf{r}}(\xi)\hat{\mathbf{r}}^*(\xi)) \end{gather*}\end{split}\]

where \(\tau\) is the time lag and the asterisk (\(^*\)) denotes the complex conjugate.

Similarly, the CCF for species \(i\) and \(j\) is evaluated using

\[C_{ij}(\tau)=\mathrm{FFT}^{-1}(\mathrm{FFT}(\mathbf{r}_i(t)) \cdot\mathrm{FFT}(\mathbf{r}_j(t)))\]
Parameters:
arr1numpy.ndarray

Time evolution of \(N\) entities over \(N_\mathrm{b}\) blocks of \(N_t\) frames each.

Shape:

  • Scalar: \((N_t,)\), \((N_t,\,N)\), \((N_\mathrm{b},\,N_t)\), or \((N_\mathrm{b},\,N_t,\,N)\).

  • Vector: \((N_t,\,d)\), \((N_t,\,N,\,N_\mathrm{d})\), \((N_\mathrm{b},\,N_t,\,N_\mathrm{d})\), or \((N_\mathrm{b},\,N_t,\,N,\,N_\mathrm{d})\), where \(N_\mathrm{d}\) is the number of dimensions each vector has.

arr2numpy.ndarray, optional

Time evolution of another \(N\) entities. If provided, the CCF for arr1 and arr2 is calculated. Otherwise, the ACF for arr1 is calculated.

Shape: Same as arr1.

axisint, optional

Axis along which to evaluate the ACF/CCF. If arr1 contains a full, unsplit trajectory, the ACF/CCF should be evaluated along the first axis (axis=0). If arr1 contains a trajectory split into multiple blocks, the ACF/CCF should be evaluated along the second axis (axis=1). If not specified, the axis is determined automatically using the shape of arr1.

averagebool, keyword-only, default: True

Determines whether the ACF/CCF is averaged over all entities if the arrays contain information for multiple entities.

doublebool, keyword-only, default: False

If True, the ACF is doubled or the CCFs for the negative and positive time lags are combined. Useful for evaluating the mean squared or cross displacement. See mdhelper.algorithm.correlation.msd_fft() for more information.

vectorbool, keyword-only, default: False

Specifies whether arr1 and arr2 contain vectors. If True, the ACF/CCF is summed over the last dimension.

Returns:
corrnumpy.ndarray

Autocorrelation or cross-correlation function.

Shape:

For ACF, the shape is that of arr1 but with the following modifications:

  • If average=True, the axis containing the \(N\) entities is removed.

  • If vector=True, the last dimension is removed.

For CCF, the shape is that of arr1 but with the following modifications:

  • If average=True, the axis containing the \(N\) entities is removed.

  • If double=False, the axis containing the \(N_t\) times now has a length of \(2N_t-1\) to accomodate negative and positive time lags.

  • If vector=True, the last dimension is removed.

References

[1]

Kneller, G. R.; Keiner, V.; Kneller, M.; Schiller, M. NMOLDYN: A Program Package for a Neutron Scattering Oriented Analysis of Molecular Dynamics Simulations. Computer Physics Communications 1995, 91 (1–3), 191–214. https://doi.org/10.1016/0010-4655(95)00048-K.

[2]

Calandrini, V.; Pellegrini, E.; Calligari, P.; Hinsen, K.; Kneller, G. R. NMoldyn - Interfacing Spectroscopic Experiments, Molecular Dynamics Simulations and Models for Time Correlation Functions. JDN 2011, 12, 201–232. https://doi.org/10.1051/sfn/201112010.