correlation_fft

mdcraft.algorithm.correlation.correlation_fft(x: ndarray[float | complex], y: ndarray[float | complex] = None, /, axis: int = None, *, average: bool = False, double: bool = False, vector: bool = False) → ndarray[float | complex][source]

Evaluates the autocorrelation functions (ACF) \(\mathrm{R_\mathbf{XX}}(\tau)\) or cross-correlation functions (CCF) \(\mathrm{R_\mathbf{XY}}(\tau)\) of time series \(\mathbf{X}(t)\) and \(\mathbf{Y}(t)\) using fast Fourier transforms (FFT).

The fast convolution algorithm (FCA) [1] [2] is associated wtih the Wiener–Khinchin theorem and has a time complexity of \(\mathcal{O}(N\log{N})\).

The ACF for a data set \(\mathbf{X}(t)\) can be computed using

\[\begin{split}\begin{gather*} \hat{\mathbf{X}}(\omega)=\mathcal{F}[\mathbf{X}(t)]\\ \mathrm{R}_{\mathbf{XX}}(\tau)=\mathcal{F}^{-1} [\hat{\mathbf{X}}(\omega)\hat{\mathbf{X}}^*(\omega)] \end{gather*}\end{split}\]

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

Similarly, the CCF for data sets \(\mathbf{X}(t)\) and \(\mathbf{Y}(t)\) can be computed using

\[\mathrm{R}_{\mathbf{XY}}(\tau)=\mathcal{F}^{-1}[\mathcal{F} [\mathbf{X}(t)]\cdot\mathcal{F}[\mathbf{Y}(t)]]\]
Parameters:
xnumpy.ndarray, positional-only

Time evolution of \(d\)-dimensional data for \(N\) entities over \(N_\mathrm{b}\) blocks of \(N_t\) times 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,\,d)\), \((N_\mathrm{b},\,N_t,\,d)\), or \((N_\mathrm{b},\,N_t,\,N,\,d)\).

ynumpy.ndarray, positional-only, optional

Time evolution of \(d\)-dimensional data for another \(N\) entities over \(N_\mathrm{b}\) blocks of \(N_t\) times each. If provided, the CCF for x and y is calculated. Otherwise, the ACF for x is calculated.

Shape: Same as x.

axisint, optional

Axis along which time evolves. If not specified, the axis is determined automatically using the shape of x.

averagebool, keyword-only, default: True

Determines whether the ACF/CCF is averaged over all entities. Only available if x and y contain information for multiple entities.

doublebool, keyword-only, default: False

Determines whether the ACF is doubled or the negative and positive time lags are combined for the CCF.

vectorbool, keyword-only, default: False

Specifies whether x and y contain vectors. If True, the ACF/CCF is summed over the last axis.

Returns:
corrnumpy.ndarray

ACF or CCF.

Shape:

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

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

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

For CCF, the shape is that of x 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 axis 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.