spectrum

A module containing the spectrum functions of the VACF analysis.

The functions in this module port the legacy ft.f Fourier transformation tool (ftvac ver. 2.0) of the thh_tools collection. The auto-correlation function is optionally multiplied with a one-sided apodization window, mirrored into an even extension and transformed with a discrete cosine sum. All legacy conventions are replicated exactly - see the notes of vacf_spectrum() for the historical quirks that are kept for backwards compatibility.

Summary

Functions:

apodization_window

Calculates the one-sided legacy apodization window.

vacf_spectrum

Calculates the legacy cosine-transform spectrum of a correlation function.

Reference

apodization_window(
n_points: PositiveInt,
time_step: PositiveReal,
window_function: str = 'none',
window_param: PositiveReal = 4.0,
window_start: PositiveReal = 0.0,
window_stop: PositiveReal = 1000.0,
) → Np1DNumberArray[source]

Calculates the one-sided legacy apodization window.

The window replicates the legacy ft.f window functions exactly. With the start index winsind = nint(window_start / time_step) and the end index wineind = nint(window_stop / time_step) the window factor of the one-based point i is one for i <= winsind, zero for i > wineind and otherwise:

  • exponential: exp(-window_param * time_step * (i - 1 - winsind))

  • hann: (1 - cos(pi * (wineind - i) / (wineind - winsind))) / 2

  • blackman: 0.42 + 0.5 * cos(pi * (i - 1 - winsind) / wineind) + 0.08 * cos(2 * pi * (i - 1 - winsind) / wineind)

Note that the legacy hann and blackman formulas are non-standard: the hann window is mirrored (it rises from the end of the window range) and the blackman denominators are wineind instead of the window width. Both quirks are replicated deliberately.

Parameters:

  • n_points (PositiveInt) – The number of points of the correlation function.

  • time_step (PositiveReal) – The time step between two points of the correlation function.

  • window_function (str, optional) – The window function, one of none, exponential, hann and blackman, by default none (all factors are one).

  • window_param (PositiveReal, optional) – The exponential decay coefficient a of the exponential window exp(-a * t), by default 4.0.

  • window_start (PositiveReal, optional) – The time at which the window starts to decay, by default 0.0.

  • window_stop (PositiveReal, optional) – The time at which the window becomes zero, by default 1000.0.

Returns:

The window factors for all points.

Return type:

Np1DNumberArray

Raises:

  • VACFError – If the window function is unknown.

  • VACFError – If the window range is empty or inverted.

vacf_spectrum(
time: Np1DNumberArray,
correlation: Np1DNumberArray,
ftsize: PositiveInt = 2000,
window_function: str = 'none',
window_param: PositiveReal = 4.0,
window_start: PositiveReal = 0.0,
window_stop: PositiveReal = 1000.0,
) → tuple[Np1DNumberArray, Np1DNumberArray, Np1DNumberArray][source]

Calculates the legacy cosine-transform spectrum of a correlation function.

The (optionally apodized) correlation function is zero-padded to ftsize points and mirrored into an even extension of length 2 * ftsize - 1 centered at index ftsize. The spectrum is the discrete cosine sum

spectrum(l) = |0.5 * sum_k cd(k) * cos(2 * pi * l * (k - ftsize) / (2 * ftsize - 1))|

for l = 1..ftsize, which is evaluated here via the equivalent real part of the FFT of the circularly shifted even extension.

Notes

The frequency axis replicates the historical calibration of the legacy ft.f tool: the wavenumber spacing is calculated with a period of 2 * (ftsize - 1) points although the underlying even extension has 2 * ftsize - 1 points. This slight frequency-axis mismatch is kept deliberately so that spectra remain comparable with the historical results. The time step is taken from the first two entries of the time axis and is assumed to be constant, and the last spectrum point duplicates its predecessor (a legacy consequence of evaluating the cosine sum at l = ftsize).

Parameters:

  • time (Np1DNumberArray) – The equidistant time axis of the correlation function in ps.

  • correlation (Np1DNumberArray) – The correlation function values.

  • ftsize (PositiveInt, optional) – The Fourier transform point size, by default 2000. The correlation function is zero-padded (or truncated) to this size.

  • window_function (str, optional) – The apodization window, one of none, exponential, hann and blackman, by default none. See apodization_window().

  • window_param (PositiveReal, optional) – The exponential window decay coefficient, by default 4.0.

  • window_start (PositiveReal, optional) – The window start time, by default 0.0.

  • window_stop (PositiveReal, optional) – The window stop time, by default 1000.0.

Returns:

  • wavenumbers (Np1DNumberArray) – The wavenumbers in cm^-1 for the indices 1..ftsize.

  • amplitudes (Np1DNumberArray) – The spectrum amplitudes.

  • windowed_correlation (Np1DNumberArray) – The correlation function after applying the apodization window (equal to the input for the none window).

Raises:

VACFError – If less than two points are given, the time axis and the correlation function have different lengths or ftsize is smaller than two.

WINDOW_FUNCTIONS = ('none', 'exponential', 'hann', 'blackman')

The window functions supported by apodization_window().