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]

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{array}{r}\begin{array}{c}\hat{\mathbf{r}}(\xi )=\mathrm{FFT}(\mathbf{r}(t))\\ A(\tau )={\mathrm{FFT}}^{-1}(\hat{\mathbf{r}}(\xi ){\hat{\mathbf{r}}}^{\ast }(\xi ))\end{array}\end{array}$$

where $\tau$ is the time lag and the asterisk (${}^{\ast }$) 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.