vachoppy.vibration
vachoppy.vibration
Provides the Vibration class for calculating the characteristic atomic vibrational frequency from a molecular dynamics trajectory.
The primary purpose of this module is to determine a suitable time scale for coarse-graining the main trajectory analysis. The calculated mean vibrational frequency is the inverse of the t_interval parameter used throughout vachoppy. This allows for a clear, data-driven distinction between rapid atomic vibrations and slower, diffusive hopping events.
Main Components
Vibration: A class that analyzes atomic displacements within a short trajectory segment. It uses a statistical approach and a Fast Fourier Transform (FFT) to determine the mean vibrational frequency.
Typical Usage
This class is often used to automatically estimate the t_interval parameter before running a full diffusion analysis.
from vachoppy.core import Site
from vachoppy.vibration import Vibration
# 1. First, set up the site information
site_info = Site(path_structure="path/to/POSCAR", symbol="O")
# 2. Initialize the Vibration class with a trajectory
vib_analyzer = Vibration(
path_traj="path/to/TRAJ_O.h5",
site=site_info
)
# 3. Run the frequency calculation
vib_analyzer.calculate()
# 4. Access the result to determine a suitable t_interval
if vib_analyzer.mean_frequency > 0:
estimated_t_interval = 1 / vib_analyzer.mean_frequency
print(f"Estimated t_interval: {estimated_t_interval:.3f} ps")
# This estimated_t_interval can then be passed to a Calculator object.
- class vachoppy.vibration.Vibration(path_traj: str, site: Site, sampling_size: int = 5000, filter_high_freq: bool = True, verbose: bool = True)[source]
Calculates atomic vibrational frequencies from a molecular dynamics trajectory.
This class analyzes a short segment of a trajectory to determine the characteristic vibrational frequency of atoms. The workflow involves: 1. Determining a data-driven “site radius” based on atomic displacements. 2. Assigning atoms to their nearest lattice sites. 3. Segmenting individual atom trajectories into periods of stable vibration. 4. Calculating the frequency spectrum for all segments using FFT.
The main entry point is the .calculate() method. The results can be visualized with the .plot_*() methods or inspected via attributes.
- Parameters:
path_traj (str) – Path to the HDF5 trajectory file.
site (Site) – An initialized Site object containing lattice site information.
sampling_size (int, optional) – Number of initial trajectory frames to use for the analysis. Defaults to 5000.
filter_high_freq (bool, optional) – If True, filters out high-frequency outliers using the IQR method. Defaults to True.
verbose (bool, optional) – Verbosity flag. Defaults to True.
- mean_frequency
The mean of all calculated vibrational frequencies in THz.
- Type:
float
- frequencies
A list containing all individual vibrational frequencies calculated from the trajectory segments.
- Type:
list[float]
- displacements
A flattened array of all measured atomic displacements (Å) during vibrational periods.
- Type:
numpy.ndarray
- site_radius
The calculated site radius (2σ of displacements) in Å, used for atom-to-site assignment.
- Type:
float
- Raises:
FileNotFoundError – If the path_traj file does not exist.
ValueError – If the HDF5 file is missing required data or metadata.
IOError – If the HDF5 file cannot be read.
- calculate(n_jobs: int = -1, jump_detection_radius: float = 1.0, verbose: bool | None = None) None[source]
Executes the full vibrational frequency analysis workflow.
This is the main method to run the analysis. It performs the following steps: 1. Calculates the average vibrational amplitude to determine a site radius. 2. Assigns each atom to its nearest lattice site at each timestep. 3. Segments the trajectory for each atom based on these site assignments. 4. Calculates the vibrational frequencies for all segments using FFT. 5. Optionally filters high-frequency outliers.
The results are stored in the object’s attributes (e.g., self.mean_frequency).
- Parameters:
n_jobs (int, optional) – The number of CPU cores for parallel processing. -1 uses all available cores. Defaults to -1.
jump_detection_radius (float, optional) – The radius (Å) used to distinguish between vibrations and jumps during the initial amplitude estimation. Defaults to 1.0.
verbose (bool | None, optional) – Overrides the class-level verbosity for this method run. If None, the class-level setting is used. Defaults to None.
- plot_displacements(bins: int = 50, disp: bool = True, save: bool = True, title: str | None = 'Displacement Distribution', filename: str = 'displacement.png', dpi: int = 300) None[source]
Plots a histogram of the atomic displacements with a Gaussian fit.
- Parameters:
bins (int, optional) – Number of bins for the histogram. Defaults to 50.
disp (bool, optional) – If True, displays the plot. Defaults to True.
save (bool, optional) – If True, saves the plot to a file. Defaults to True.
title (str | None, optional) – A custom title for the plot.
filename (str, optional) – Filename for the saved plot.
dpi (int, optional) – Resolution for the saved figure.
- Raises:
AttributeError – If .calculate() has not been run yet.
- plot_frequencies(bins: int = 50, disp: bool = True, save: bool = True, title: str | None = 'Frequency Distribution', filename: str = 'frequency.png', dpi: int = 300) None[source]
Plots a histogram of the calculated vibrational frequencies.
- Parameters:
bins (int, optional) – Number of bins for the histogram. Defaults to 50.
disp (bool, optional) – If True, displays the plot. Defaults to True.
save (bool, optional) – If True, saves the plot to a file. Defaults to True.
title (str | None, optional) – A custom title for the plot.
filename (str, optional) – Filename for the saved plot.
dpi (int,optional) – Resolution for the saved figure.
- Raises:
AttributeError – If .calculate() has not been run yet.