rd.correlate()#
- RotationalDiffusion.correlations.correlate(orientations, stop=0.1, step=1, do_variance=False, verbose=False)[source]#
Compute rotational correlation functions from trajectories of orientations.
The orientations must be provided as a time series (trajectory) of orientational (unit) quaternions in scalar-first convention, i.e., each quaternion is represented by a numpy array \((w, x, y, z)\), where \(w\) is the scalar part. If an
array_likeof orientational trajectories is provided, all trajectories are processed at once using fast numpy array operations, which is much quicker than looping over the trajectories.The maximum lag time can be specified with
stop. Ifstopis afloat, then it specifies a fraction of the trajectory length, which is converted into a maximal lag index. For example, if the trajectory contains 1000 frames andstopis set to 0.1 (default), then the correlation function is computed up to 10% of the trajectory length and the maximum lag index is set to 100. Ifstopis anint, it directly specifies the maximum lag index.The computed quaternion covariance matrix contains (ensemble) averages of products of quaternion components, which form six rotational correlation functions.[1] If
do_varianceisTrue, then also the corresponding variances of products of quaternion components are computed. In that case, a tuple of the quaternion covariance matrix and the variance matrix is returned. However, computing the variances increases the computational time and is seldomly necessary, hence, it is deactivated by default.- Parameters:
- orientations(…, n_frames, 4) array_like
Quaternions representing the orientations, in scalar first convention. The second-to-last dimension must contain the time series of quaternions.
- stop
floatorint, default: 0.1 Maximum lag time. If
float,stopspecifies a fraction of the trajectory length. Ifint,stopspecifies the maximum lag index.- step
int, default: 1 Increment of the lag index.
- do_variancebool, default:
False Whether to compute the variances of correlation matrix elements.
- verbosebool, default:
False Show progress bar if set to
True.
- Returns:
- Raises:
ValueErrorIf
stopis too large.
See also
RotationalDiffusion.orientations.OrientationsMDAnalysis-based class for extracting the orientations of a molecular structure from MD trajectories.
RotationalDiffusion.quaternionsQuaternion operations used under the hood.
Notes
First, reorientations \(q(t, \tau)\) are computed from the provided trajectory of orientations \(q(t)\) as
\[q(t, \tau) = q(t) \cdot q^{-1}(t + \tau).\]Second, the covariance matrix of the vector parts of these reorientational quaternions is computed as \({\bf \tilde{Q}}_{ij}(\tau) = \langle q_i q_j \rangle_t\). The resulting matrix \({\bf \tilde{Q}}_{ij}(\tau)\) contains six rotational correlation functions. See Holtbrügge and Schäfer[1] for more details.
References