vacf

A module containing the VACF class. The VACF class is used to calculate the normalized velocity auto-correlation function of a target selection of a given velocity trajectory. In the charge-flux mode the atomic velocities are weighted with (possibly time-dependent) atomic partial charges, which turns the auto-correlation function into a charge-flux (current) auto-correlation function.

The implementation is a port of the legacy FreqCalc and Fluxfreqcalc tools of the thh_tools collection. Both legacy tools share the identical sliding-time-origin estimator - they only differ in the charge weighting of the velocities at read time.

Summary

Classes:

VACF

A class for calculating the normalized velocity (or charge-flux) auto-correlation function of a target selection of a velocity trajectory.

Reference

class VACF(
traj: Trajectory | TrajectoryReader,
time_step: PositiveReal,
window_size: PositiveInt | None = None,
target_species: SelectionCompatible = None,
gap: PositiveInt | None = None,
charges: Np1DNumberArray | None = None,
charge_traj: Trajectory | TrajectoryReader | None = None,
method: str | None = None,
use_full_atom_info: bool | None = False,
)[source]

Bases: object

A class for calculating the normalized velocity (or charge-flux) auto-correlation function of a target selection of a velocity trajectory.

The auto-correlation function is estimated with sliding time origins. A new origin is spawned every gap frames as long as a full correlation window of window_size frames can still be accommodated by the trajectory, i.e. for all origin frames t0 <= stop_frame with stop_frame = floor((n_frames - window_size) / gap) * gap (frames are counted starting at 1). Like in the legacy tools, a stop_frame of exactly zero (i.e. n_frames == window_size) is reset to one, so that for gap == 1 a single origin is spawned at the first frame and only the final lag bin of the correlation function stays zero. Each origin is normalized by its own aggregate squared velocity norm, so that the correlation function starts at exactly one:

C(lag) = (1 / n_origins) * sum_i [sum_j v_j(t0_i + lag) . v_j(t0_i)] / [sum_j |v_j(t0_i)|^2]

where the sum over j runs over all selected atoms and the sum over i over all time origins. This reproduces the legacy FreqCalc/Fluxfreqcalc estimator exactly, including the requirement that window_size is an integer multiple of gap.

In the charge-flux mode (legacy Fluxfreqcalc) every velocity is replaced by q_j(t) * v_j(t) at read time, either with static charges or with a charge trajectory read in lockstep with the velocity trajectory.

Alternatively, a fast estimator based on the Wiener-Khinchin theorem can be selected with method='fft'. Note that this is a slightly different (denser-origin) estimator: every frame serves as a time origin (the gap parameter is ignored), each lag is averaged over its actual number of origins and the normalization is performed with the aggregate mean squared velocity instead of per-origin norms. The default method='direct' is legacy-exact.

Parameters:

  • traj (Trajectory | TrajectoryReader) – The velocity trajectory to analyze. If a TrajectoryReader is provided, the trajectory is read lazily frame by frame. All frames must provide velocities.

  • time_step (PositiveReal) – The time step between two frames in ps. It is only used to build the time axis of the results.

  • window_size (PositiveInt | None, optional) – The correlation window length in frames. The correlation function is calculated for the lags 0..window_size, by default None (1000).

  • target_species (SelectionCompatible, optional) – The target species of the VACF analysis, by default None (all atoms).

  • gap (PositiveInt | None, optional) – The spacing between two time origins in frames, by default None (1). window_size must be an integer multiple of gap.

  • charges (Np1DNumberArray | None, optional) – Static atomic partial charges for the charge-flux mode, one charge per atom of the full system, by default None.

  • charge_traj (Trajectory | TrajectoryReader | None, optional) – A charge trajectory for the charge-flux mode, read in lockstep with the velocity trajectory, by default None.

  • method (str | None, optional) – The estimator to use, either direct (legacy-exact sliding origins) or fft (denser-origin Wiener-Khinchin estimator, ignores gap), by default None (direct).

  • use_full_atom_info (bool | None, optional) – Whether to use the full atom information for the target selection, by default None (False).

Raises:

  • VACFError – If the time step is not positive.

  • VACFError – If the method is unknown.

  • VACFError – If both static charges and a charge trajectory are given.

  • VACFError – If the window size is not an integer multiple of the gap.

  • VACFError – If the trajectory is too short to place a single time origin.

  • VACFError – If the target selection does not select any atoms.

  • VACFError – If the number of static charges does not match the number of atoms.

run() → tuple[Np1DNumberArray, Np1DNumberArray][source]

Runs the VACF analysis.

This method will display a progress bar by default. This can be disabled by setting with_progress_bar to False.

Returns:

  • time (Np1DNumberArray) – The lag times lag * time_step for the lags 0..window_size.

  • vacf (Np1DNumberArray) – The normalized (charge-flux weighted) velocity auto-correlation function; vacf[0] is exactly one for the direct method.

logger = <CustomLogger PQAnalysis.VACF (INFO)>
property n_atoms: int

The number of atoms of the VACF analysis.

Type:

int

property stop_frame: int

The last frame (1-based) at which a time origin is spawned.

Type:

int