vachoppy.trajectory

vachoppy.trajectory

Contains the core classes that form the computational engine for vacancy diffusion analysis in VacHopPy.

This module provides a hierarchy of classes designed to process trajectory data in progressive stages, from the lowest level of identifying individual atomic hops to the highest level of calculating ensemble-averaged physical properties and performing Arrhenius fits.

While these classes can be used individually for advanced or custom workflows, they are typically orchestrated by the high-level setup function in the vachoppy.core module.

Core Classes

  • Trajectory: The foundational class that reads a single HDF5 trajectory, determines the site occupation of each atom at each time step, and reconstructs the raw vacancy movement paths.

  • TrajectoryAnalyzer: Analyzes the output of a Trajectory object to identify and quantify discrete hopping events, calculating statistics like hop counts and site residence times.

  • Encounter: Processes results from TrajectoryAnalyzer to identify atom-vacancy encounters and calculate the correlation factor (f).

  • CalculatorSingle: A high-level orchestrator that combines the three classes above to run the full pipeline on a single trajectory file. It serves as the worker process for ensemble calculations.

  • CalculatorEnsemble: The top-level analysis class that manages an ensemble of trajectories. It uses TrajectoryBundle for file discovery and runs multiple CalculatorSingle instances in parallel to compute temperature-dependent properties.

  • TrajectoryBundle: A helper class used by CalculatorEnsemble to discover, validate, and group a collection of trajectory files for multi-temperature analysis.

Typical Usage

Users should typically not import classes from this module directly. Instead, the intended entry point is the vachoppy.core.Calculator function, which handles the instantiation and execution of the appropriate classes from this module behind the scenes.

class vachoppy.trajectory.CalculatorEnsemble(path_traj: str, site: Site, t_interval: float, prefix: str = 'TRAJ', depth: int = 2, use_incomplete_encounter: bool = True, eps: float = 0.001, verbose: bool = True)[source]

Orchestrates the full analysis pipeline for an ensemble of trajectories.

This class is the main user interface for multi-temperature diffusion analysis. It inherits from TrajectoryBundle, using it to automatically discover, validate, and group HDF5 trajectory files by temperature from a given path.

The primary workflow involves two steps:

  1. Initialization: Create an instance of the class, which prepares the dataset.

  2. Calculation: Call the .calculate() method to run the entire computational pipeline. This process analyzes each trajectory in parallel, aggregates the results, and performs Arrhenius fits to determine activation energies and pre-exponential factors.

Once calculated, results can be viewed with the .summary() method, visualized with a suite of plotting methods (e.g., .plot_D()), or saved to a file.

Parameters:

  • path_traj (str) – Path to a single HDF5 file or a root directory to search for files.

  • site (Site) – An initialized Site object with lattice and path information.

  • t_interval (float) – The time interval in picoseconds (ps) for coarse-graining the analysis.

  • prefix (str, optional) – Prefix of trajectory files to search for (used in directory scans). Defaults to “TRAJ”.

  • depth (int, optional) – Maximum directory depth for file searches. Defaults to 2.

  • use_incomplete_encounter (bool, optional) – If True, incomplete encounters are included in the analysis. Defaults to True.

  • eps (float, optional) – A tolerance for floating-point comparisons. Defaults to 1.0e-3.

  • verbose (bool, optional) – Verbosity flag. Defaults to True.

temperatures

Array of unique temperatures (K) found in the analysis.

Type:

numpy.ndarray

The following attributes are populated after calling the `.calculate()` method
D

Temperature-dependent vacancy diffusivity (m²/s).

Type:

numpy.ndarray

Ea_D

Activation energy (eV) for diffusivity from Arrhenius fit. This value corresponds to the diffusion barrier.

Type:

float

D0

Pre-exponential factor (m²/s) for diffusivity.

Type:

float

D_rand

Temperature-dependent random-walk diffusivity (m²/s).

Type:

numpy.ndarray

Ea_D_rand

Activation energy (eV) for random-walk diffusivity. This value corresponds to the hopping barrier.

Type:

float

D_rand0

Pre-exponential factor (m²/s) for random-walk diffusivity.

Type:

float

f

Temperature-dependent correlation factor.

Type:

numpy.ndarray

Ea_f

Activation energy (eV) for the correlation factor.

Type:

float

f0

Pre-exponential factor (ps) for the correlation factor

Type:

float

tau

Temperature-dependent average vacancy residence time (ps).

Type:

numpy.ndarray

Ea_tau

Activation energy (eV) for residence time. This value is the same with the Ea_D_rand.

Type:

float

tau0

Pre-exponential factor (ps) for the vacancy residence time.

Type:

float

a

Effective hopping distance (Å).

Type:

numpy.ndarray

calculators

A list of the successfully completed CalculatorSingle instances, ordered corresponding to the all_traj_paths attribute.

Type:

list[CalculatorSingle]

The following attributes are populated after calling the `.calculate_attempt_frequency()` method
z

Temperature-dependent effective coordination number.

Type:

numpy.ndarray

nu

Temperature-dependent effective attempt frequency (THz).

Type:

numpy.ndarray

nu_path

Path-wise attempt frequency (THz), with shape (n_temperatures, n_paths).

Type:

numpy.ndarray

The following attributes are populated after calling the `.decompose_diffusivity()` method
Dx

Temperature-dependent vacancy diffusivity in the x-direction (m²/s).

Type:

numpy.ndarray

D0_x

Pre-exponential factor for Dx (m²/s) from Arrhenius fit.

Type:

float

Ea_x

Activation energy for Dx (eV) from Arrhenius fit.

Type:

float

Dy

Temperature-dependent vacancy diffusivity in the y-direction (m²/s).

Type:

numpy.ndarray

D0_y

Pre-exponential factor for Dy (m²/s) from Arrhenius fit.

Type:

float

Ea_y

Activation energy for Dy (eV) from Arrhenius fit.

Type:

float

Dz

Temperature-dependent vacancy diffusivity in the z-direction (m²/s).

Type:

numpy.ndarray

D0_z

Pre-exponential factor for Dz (m²/s) from Arrhenius fit.

Type:

float

Ea_z

Activation energy for Dz (eV) from Arrhenius fit.

Type:

float

Raises:

  • FileNotFoundError – If path_traj does not exist or no valid files are found.

  • ValueError – If inconsistent simulation parameters are found among trajectories.

Examples

>>> # 1. Initialize the Site and CalculatorEnsemble objects
>>> site_info = Site("POSCAR", symbol="O")
>>> ensemble = CalculatorEnsemble(
...     path_traj="path/to/trajectories/",
...     site=site_info,
...     t_interval=0.1
... )
>>>
>>> # 2. Run the entire parallel analysis pipeline
>>> ensemble.calculate(n_jobs=-1)
>>>
>>> # 3. View and visualize the main results
>>> ensemble.summary()
>>> ensemble.plot_D(filename="diffusivity_plot.png")
>>>
>>> # 4. (Optional) Calculate attempt frequencies with NEB data
>>> ensemble.calculate_attempt_frequency(neb_csv="path/to/neb_data.csv")
>>> ensemble.plot_nu()
>>>
>>> # 5. (Optional) Decompose diffusivity and plot results
>>> ensemble.decompose_diffusivity()
>>> ensemble.plot_D_xyz()
calculate(n_jobs: int = -1, verbose=True) → None[source]

Runs the full analysis pipeline on all trajectories in parallel.

This method performs the following steps: 1. Runs the CalculatorSingle analysis for each trajectory file in parallel. 2. Gathers and aggregates the results by temperature. 3. Calculates temperature-averaged physical properties (D, f, tau, etc.). 4. Performs Arrhenius fits for these properties if more than one temperature is available. 5. Calculates the effective hopping distance from the fit results.

Parameters:

  • n_jobs (int, optional) – Number of CPU cores for parallel analysis. -1 uses all available cores. Defaults to -1.

  • verbose (bool, optional) – Verbosity flag for the performance monitor decorator. Defaults to True.

Returns:

This method populates the instance’s attributes with the

analysis results and does not return any value.

Return type:

None

calculate_attempt_frequency(neb_csv: str, filename: str = 'parameters.json') → None[source]

Calculates attempt frequencies and updates the parameter file.

This method first saves the current analysis results, then runs the AttemptFrequency analysis using the provided NEB data, and finally updates the parameter file with the newly calculated frequency results.

Parameters:

  • neb_csv (str) – Path to the CSV file containing NEB-calculated activation barriers.

  • filename (str, optional) – The name of the parameter JSON file to create and update. Defaults to “parameters.json”.

decompose_diffusivity(verbose: bool = True) → None[source]

Decomposes the final diffusivity (self.D) into directional components (Dx, Dy, Dz) and performs Arrhenius fits on them.

This method uses a statistically robust approach:

  1. The already-calculated total diffusivity (self.D) is used as the basis.

  2. For each temperature, the MSD component ratios (x, y, z) are calculated at each available time step and then time-averaged to get a stable mean contribution for each direction.

  3. The total D is apportioned into Dx, Dy, and Dz using these mean ratios, ensuring physical consistency.

  4. Finally, an Arrhenius fit is performed on the decomposed diffusivities.

The results are stored in instance attributes like self.Dx, self.Ea_x, self.D0_x, etc.

Parameters:

verbose (bool, optional) – If True, prints a summary of the fitting results. Defaults to True.

plot_D(title: str | None = 'Diffusivity (Arrhenius Plot)', disp: bool = True, save: bool = True, filename: str = 'D.png', error_bar: bool = False, dpi: int = 300) → None[source]

Generates an Arrhenius plot for the final diffusivity (D).

Parameters:

  • title (str | None, optional) – A custom title for the plot.

  • 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.

  • filename (str, optional) – Filename for the saved plot.

  • error_bar (bool, optional) – If True, displays SEM error bars.

  • dpi (int, optional) – Resolution for the saved figure.

plot_D_rand(title: str | None = 'Random Walk Diffusivity (Arrhenius Plot)', disp: bool = True, save: bool = True, filename: str = 'D_rand.png', error_bar: bool = False, dpi: int = 300) → None[source]

Generates an Arrhenius plot for the random-walk diffusivity (D_rand).

Parameters:

  • title (str | None, optional) – A custom title for the plot.

  • 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.

  • filename (str, optional) – Filename for the saved plot.

  • error_bar (bool, optional) – If True, displays SEM error bars.

  • dpi (int, optional) – Resolution for the saved figure.

plot_D_xyz(title: str | None = 'Decomposed Diffusivity (Arrhenius Plot)', disp: bool = True, save: bool = True, filename: str = 'D_xyz.png', dpi: int = 300) → None[source]

Generates Arrhenius plots for the decomposed directional diffusivities (Dx, Dy, Dz).

This method creates a figure with three horizontal subplots, one for each spatial component, to visualize their temperature dependence and Arrhenius fits.

Parameters:

  • title (str | None, optional) – A custom title for the overall figure.

  • 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.

  • filename (str, optional) – Filename for the saved plot.

  • dpi (int, optional) – Resolution for the saved figure.

plot_a(title: str | None = 'Hopping Distance vs. Temperature', disp: bool = True, save: bool = True, filename: str = 'a.png', dpi: int = 300) → None[source]

Plots the hopping distance (a) as a function of temperature.

Parameters:

  • title (str | None, optional) – A custom title for the plot.

  • 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.

  • filename (str, optional) – Filename for the saved plot.

  • dpi (int, optional) – Resolution for the saved figure.

plot_counts(title: str | None = 'Total Hopping Counts per Path', disp: bool = True, save: bool = True, filename: str = 'counts.png', dpi: int = 300) → None[source]

Generates a bar plot of total hop counts for each path type.

This plot visualizes the frequency of all observed hopping events, summed across all trajectories in the ensemble.

Parameters:

  • title (str | None, optional) – A custom title for the plot.

  • 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.

  • filename (str, optional) – Filename for the saved plot.

  • dpi (int, optional) – Resolution for the saved figure.

plot_f(title: str | None = 'Correlation Factor vs. Temperature', disp: bool = True, save: bool = True, filename: str = 'f.png', error_bar: bool = False, dpi: int = 300) → None[source]

Plots the correlation factor (f) as a function of temperature.

Parameters:

  • title (str | None, optional) – A custom title for the plot.

  • 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.

  • filename (str, optional) – Filename for the saved plot.

  • error_bar (bool, optional) – If True, displays SEM error bars.

  • dpi (int, optional) – Resolution for the saved figure.

plot_msd_xyz(title: str | None = 'MSD Components vs. Time', disp: bool = True, save: bool = True, filename: str = 'msd_xyz.png', dpi: int = 300) → None[source]

Plots the x, y, and z components of the MSD vs. time for all temperatures.

Each component is plotted on a separate subplot in a horizontal layout. This plot shows the raw MSD data without any fitting lines.

Parameters:

  • title (str | None, optional) – A custom title for the plot figure.

  • 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.

  • filename (str, optional) – Filename for the saved plot.

  • dpi (int, optional) – Resolution for the saved figure.

plot_nu(title: str | None = 'Attempt Frequency vs. Temperature', disp: bool = True, save: bool = True, filename: str = 'attempt_frequency.png', dpi: int = 300) → None[source]

Plots the effective attempt frequency (nu) vs. temperature.

This method delegates the plotting task to the internal AttemptFrequency object. .calculate_attempt_frequency() must be called first.

Parameters:

  • title (str | None, optional) – A custom title for the plot.

  • disp (bool, optional) – If True, displays the plot. Defaults to True.

  • save (bool, optional) – If True, saves the plot. Defaults to True.

  • filename (str, optional) – Filename for the saved plot.

  • dpi (int, optional) – Resolution for the saved figure.

plot_tau(title: str | None = 'Residence Time vs. Temperature', disp: bool = True, save: bool = True, filename: str = 'tau.png', error_bar: bool = False, dpi: int = 300) → None[source]

Plots the average residence time (tau) vs. temperature.

Parameters:

  • title (str | None, optional) – A custom title for the plot.

  • 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.

  • filename (str, optional) – Filename for the saved plot.

  • error_bar (bool, optional) – If True, displays SEM error bars on the bars.

  • dpi (int, optional) – Resolution for the saved figure.

plot_z(title: str | None = 'Coordination Number vs. Temperature', disp: bool = True, save: bool = True, filename: str = 'coordination_number.png', dpi: int = 300) → None[source]

Plots the effective coordination number (z) vs. temperature.

This method delegates the plotting task to the internal AttemptFrequency object. .calculate_attempt_frequency() must be called first.

Parameters:

  • title (str | None, optional) – A custom title for the plot.

  • disp (bool, optional) – If True, displays the plot. Defaults to True.

  • save (bool, optional) – If True, saves the plot. Defaults to True.

  • filename (str, optional) – Filename for the saved plot.

  • dpi (int, optional) – Resolution for the saved figure.

save_parameters(filename: str = 'parameters.json') → None[source]

Saves all calculated and fitted physical parameters to a JSON file.

The output JSON includes a ‘description’ key that explains each parameter, making the file self-documenting.

Parameters:

filename (str, optional) – The name of the output JSON file.

save_trajectory(path_dir: str = 'trajectories', prefix: str = 'trajectory') → None[source]

Saves the unwrapped vacancy trajectories from all simulations.

This method creates a directory structure organized by temperature (e.g., ‘trajectories/300K/’), and saves the unwrapped vacancy trajectory from each simulation as a separate JSON file within the appropriate subdirectory.

Parameters:

  • path_dir (str, optional) – The root directory for saving trajectories.

  • prefix (str, optional) – The prefix for the output JSON filenames.

show_hopping_history() → None[source]

Prints instructions on how to view the history for a single trajectory.

This method does not print a history table directly, as this is an ensemble analysis. Instead, it provides a user guide explaining how to access the show_hopping_history method of an individual CalculatorSingle object within the .calculators list.

show_hopping_paths() → None[source]

Prints a summary table of all observed hopping path types and their counts.

summary()[source]

Prints a comprehensive summary of the ensemble analysis results.

The summary includes a table of temperature-dependent data (D, f, tau) and a detailed breakdown of the final fitted Arrhenius parameters for each physical quantity.

class vachoppy.trajectory.CalculatorSingle(path_traj: str, site: Site, t_interval: float, eps: float = 0.001, use_incomplete_encounter: bool = True, verbose: bool = True)[source]

Orchestrates the full vacancy diffusion analysis for a single trajectory.

This class provides a high-level interface for analyzing a single simulation run. Upon initialization, it immediately performs the foundational analysis by processing the trajectory to identify all hopping events and atom-vacancy encounters.

After the object is created, the .calculate() method must be called to compute the final, derived physical properties (e.g., diffusivity, correlation factor, residence time) from the initial results.

Parameters:

  • path_traj (str) – Path to the HDF5 trajectory file.

  • site (Site) – An initialized Site object containing lattice structure and path info.

  • t_interval (float) – The time interval in picoseconds (ps) for coarse-graining the analysis.

  • eps (float, optional) – A tolerance for floating-point comparisons. Defaults to 1.0e-3.

  • use_incomplete_encounter (bool, optional) – If True, incomplete encounters are included in the final analysis. Defaults to True.

  • verbose (bool, optional) – Verbosity flag. Defaults to True.

f

The calculated correlation factor. Populated after .calculate() is called.

Type:

float

D

The final vacancy diffusivity (m²/s). Populated after .calculate() is called.

Type:

float

D_rand

The random-walk diffusivity (m²/s). Populated after .calculate() is called.

Type:

float

tau

The average vacancy residence time (ps). Populated after .calculate() is called.

Type:

float

a

Effective hopping distance (Å). Populated after .calculate() is called.

Type:

float

hopping_history

A detailed log of every hop for each vacancy, available after initialization.

Type:

list

counts

An array containing the counts for each predefined hopping path.

Type:

numpy.ndarray

Raises:

  • FileNotFoundError – If the specified path_traj does not exist.

  • ValueError – If critical data is missing from the trajectory or site information.

Examples

>>> # 1. Initialize the Site and CalculatorSingle objects
>>> site_info = Site("POSCAR", symbol="O")
>>> calc = CalculatorSingle(
...     path_traj="TRAJ_O_1000K.h5",
...     site=site_info,
...     t_interval=0.1
... )
>>>
>>> # 2. Compute the final physical properties
>>> calc.calculate()
>>>
>>> # 3. View the results
>>> calc.summary()
>>> print(f"Correlation Factor: {calc.f:.4f}")
calculate(**kwargs) → None[source]

Calculates the final physical properties from the initial analysis.

This method should be called after the CalculatorSingle object has been initialized. It computes derived quantities like diffusivity, correlation factor, and residence time from the already-processed hop and encounter data.

plot_counts(title: str | None = None, save: bool = True, filename: str = 'counts.png', dpi: int = 300) → None[source]

Generates a bar plot showing the total counts for each migration path.

This plot visualizes the frequency of both predefined (known) and dynamically discovered (unknown) hopping events.

Parameters:

  • title (str | None, optional) – A custom title for the plot. Defaults to None.

  • save (bool, optional) – If True, saves the figure to a file. Defaults to True.

  • filename (str, optional) – Filename for the saved plot. Defaults to ‘counts.png’.

  • dpi (int, optional) – Resolution in dots per inch for the saved figure. Defaults to 300.

Returns:

This method displays a plot and optionally saves it to a file.

Return type:

None

save_trajectory(filename: str = 'trajectory.json') → None[source]

Saves the unwrapped Cartesian trajectories of vacancies to a JSON file.

The output JSON contains simulation metadata and the time-series coordinates for each vacancy, keyed as ‘Vacancy0’, ‘Vacancy1’, etc.

Parameters:

filename (str, optional) – The name of the output JSON file. Defaults to ‘trajectory.json’.

Returns:

This method writes a file to disk.

Return type:

None

show_hopping_history() → None[source]

Prints a detailed, time-ordered table of the hopping sequence for each vacancy.

Returns:

This method prints a table to the console.

Return type:

None

show_hopping_paths() → None[source]

Prints a summary table of all observed hopping paths and their counts.

This includes both the paths pre-defined in the Site object and any new “unknown” paths discovered during the trajectory analysis.

Returns:

This method prints a table to the console.

Return type:

None

summary() → None[source]

Prints a comprehensive, formatted summary of the analysis results.

The summary includes input parameters and all key calculated physical properties like diffusivity, correlation factor, and residence time. It automatically calls .calculate() if it has not been run yet.

Returns:

This method prints a summary to the console.

Return type:

None

class vachoppy.trajectory.Encounter(analyzer: TrajectoryAnalyzer, use_incomplete_encounter: bool = True, verbose: bool = True)[source]

Analyzes atom-vacancy encounters to calculate diffusion correlation factors.

An “encounter” is a sequence of correlated hops involving a specific atom and a specific vacancy. This sequence continues as long as the atom interacts with the same vacancy, even if it hops away and returns.

The encounter is considered terminated when the atom performs a hop by exchanging with a different vacancy. At that moment, a new encounter begins with the new vacancy. This class identifies these events to compute the correlation factor (f).

Parameters:

  • analyzer (TrajectoryAnalyzer) – An initialized TrajectoryAnalyzer object containing the full hopping statistics from a trajectory.

  • use_incomplete_encounter (bool, optional) – If True, encounters that were still in progress at the end of the simulation are included in the statistical analysis. This can improve statistics for short simulations but may slightly skew results. Defaults to True.

  • verbose (bool, optional) – Verbosity flag. Defaults to True.

f_cor

The calculated correlation factor (f), a measure of how correlated successive jumps of an atom are.

Type:

float

msd

The mean squared displacement (Ų) of atoms, averaged over all analyzed encounters.

Type:

float

path_count

An array counting the total number of times each pre-defined path was traversed across all encounters.

Type:

numpy.ndarray

num_encounter

The total number of encounters used in the analysis.

Type:

int

encounter_complete

A list of all encounter events that were fully completed within the simulation time.

Type:

list[dict]

encounter_in_process

A list of encounter events that were still ongoing when the simulation ended.

Type:

list[dict]

Raises:

AttributeError – If the input analyzer object is missing required, pre-computed attributes (e.g., hopping_sequence).

Examples

>>> # Assuming site_info and traj_analysis objects have been created
>>> analyzer = TrajectoryAnalyzer(trajectory=traj_analysis)
>>> encounter_stats = Encounter(analyzer=analyzer, verbose=True)
# A summary is printed upon initialization if encounters are found.
# Access results directly:
# print(f"Correlation Factor (f): {encounter_stats.f_cor:.4f}")
summary() → None[source]

Prints a comprehensive, formatted summary of the encounter analysis.

The summary includes key calculated values like the correlation factor and MSD, statistics on the number and type of encounters, and a detailed table of path-wise hop counts within the encounters.

class vachoppy.trajectory.Trajectory(path_traj: str, site: Site, t_interval: float, force_margin: float = 0.1, cos_margin: float = 0.1, verbose: bool = True)[source]

Analyzes a single MD trajectory to trace atomic and vacancy hops.

This class reads a trajectory from an HDF5 file, identifies which lattice site each atom occupies at each time step, validates hops using a robust transition state criterion, and reconstructs the movement paths of vacancies. It serves as the primary engine for analyzing vacancy diffusion events and provides methods for both interactive (Plotly) and static (matplotlib) visualization of the results.

Parameters:

  • path_traj (str) – Path to the HDF5 trajectory file.

  • site (Site) – An initialized Site object containing pre-analyzed information about the crystal lattice sites.

  • t_interval (float) – The time interval in picoseconds (ps) between each analysis step. This determines the coarse-graining level of the analysis.

  • force_margin (float, optional) – The minimum force magnitude (eV/Å) required for the directional transition state check. Defaults to 0.1.

  • cos_margin (float, optional) – The required cosine difference to reject a hop during the transition state check. A higher value makes the check stricter. Defaults to 0.1.

  • verbose (bool, optional) – Verbosity flag. Defaults to True.

occupation

A 2D array of shape (num_atoms, num_steps) storing the lattice site index occupied by each atom at each step.

Type:

numpy.ndarray

hopping_history

A chronological list of all validated hop events. Each entry contains details such as the time step, hopping atom index, and the initial and final site indices.

Type:

list[dict]

vacancy_trajectory_index

A dictionary mapping each time step to the indices of occupied vacancy sites.

Type:

dict

vacancy_trajectory_coord_cart

A dictionary mapping each time step to the Cartesian coordinates (Å) of occupied vacancy sites within the unit cell.

Type:

dict

unwrapped_vacancy_trajectory_coord_cart

A dictionary mapping each time step to the continuous, unwrapped Cartesian coordinates of vacancies, representing the true diffusion path.

Type:

dict

hopping_sequence

A dictionary mapping each time step to the reconstructed vacancy hop paths between sites.

Type:

dict

Raises:

  • FileNotFoundError – If the path_traj file is not found.

  • ValueError – If the trajectory file has an invalid format, missing data, or if parameters (t_interval, symbol, etc.) are inconsistent.

  • IOError – If the HDF5 file cannot be read.

animate_occupation(index: list | str = 'all', step_init: int = 0, step_final: int | None = None, vac: bool = True, gif: bool = True, filename: str = 'occupation_video.gif', foldername: str = 'snapshots', update_alpha: float = 0.9, fps: int = 10, loop: int = 0, dpi: int = 150, n_jobs: int = -1, legend: bool = False, label: bool = False, verbose: bool = True) → None[source]

Generates a GIF animation visualizing the time evolution of site occupations.

This method creates a series of 3D snapshot images for each time step and compiles them into a GIF. Each frame displays the crystal lattice and shows the position of color-coded atoms based on which site they occupy at that moment in time.

This provides a dynamic, visual representation of how individual atoms hop between lattice sites and how vacancies consequently move through the crystal structure.

Parameters:

  • index (list | str, optional) – Indices of atoms to display. Defaults to ‘all’.

  • step_init (int, optional) – The starting step for the animation. Defaults to 0.

  • step_final (int | None, optional) – The ending step for the animation. If None, animates to the end. Defaults to None.

  • vac (bool, optional) – If True, highlights vacancy and transient vacancy sites. Defaults to True.

  • gif (bool, optional) – If True, creates a GIF file from the snapshots. Defaults to True.

  • filename (str, optional) – Output GIF file name. Defaults to ‘occupation_video.gif’.

  • foldername (str, optional) – Directory to save temporary snapshot images. Defaults to ‘snapshots’.

  • update_alpha (float, optional) – Fading rate for atomic hop trace arrows. Defaults to 0.9.

  • fps (int, optional) – Frames per second for the output GIF. Defaults to 10.

  • loop (int, optional) – Number of loops for the GIF (0 for infinite). Defaults to 0.

  • dpi (int, optional) – Resolution in dots per inch for snapshots. Defaults to 150.

  • n_jobs (int, optional) – The number of CPU cores for parallel processing. -1 uses all available cores. Defaults to -1.

  • legend (bool, optional) – If True, displays a legend for atoms. Defaults to False.

  • label (bool, optional) – If True, displays numeric labels for lattice sites. Defaults to False.

Returns:

This method saves image files and a GIF to disk.

Return type:

None

animate_vacancy_trajectory(vacancy_indices: int | list, step_init: int = 0, step_final: int | None = None, unwrap: bool = False, max_trace_length: int = 10, update_alpha: float = 0.8, fps: int = 5, save: bool = True, filename: str = 'trajectory_video.html', verbose: bool = True) → None[source]

Generates an interactive 3D animation of vacancy trajectories using Plotly.

The animation includes play/pause controls and a slider to navigate through time. The real-time position of each vacancy is shown, and its recent path fades over time to indicate the direction of movement.

Parameters:

  • vacancy_indices (int | list) – Index or list of indices for the vacancies to be animated.

  • step_init (int, optional) – The starting step for the animation. Defaults to 0.

  • step_final (int | None, optional) – The ending step for the animation. If None, animates to the end. Defaults to None.

  • unwrap (bool, optional) – If True, plots the continuous, unwrapped path. Defaults to False.

  • max_trace_length (int, optional) – The number of past path segments to display as a fading tail. Defaults to 10.

  • update_alpha (float, optional) – Fading rate for the tail. Closer to 0 makes paths fade faster. Defaults to 0.8.

  • fps (int, optional) – Frames per second for animation playback. Defaults to 5.

  • save (bool, optional) – If True, saves the animation as a standalone HTML file. Defaults to True.

  • filename (str, optional) – The name of the output HTML file if save is True. Defaults to “trajectory_video.html”.

  • verbose (bool, optional) – Verbosity flag. Defaults to True.

Returns:

This method saves an HTML file or displays a plot.

Return type:

None

Raises:

ValueError – If the specified step_init or step_final is out of bounds.

distance_PBC(coord1: ndarray, coord2: ndarray) → float | ndarray[source]

Calculates the PBC-aware distance between fractional coordinates.

This method computes the shortest distance between one or more initial points (coord1) and a final point (coord2), respecting the periodic boundary conditions of the lattice.

Parameters:

  • coord1 (np.ndarray) – Initial coordinate(s) in fractional form. Can be a single point (1D array) or multiple points (2D array).

  • coord2 (np.ndarray) – Final coordinate in fractional form (1D array).

Returns:

The calculated distance(s) in Cartesian units. Returns a float if coord1 is 1D, or a 1D array of distances if coord1 is 2D.

Return type:

float | np.ndarray

plot_vacancy_trajectory(vacancy_indices: int | list, step_init: int = 0, step_final: int | None = None, unwrap: bool = False, alpha: float = 0.6, disp: bool = True, save: bool = False, filename: str = 'trajectory.html') → None[source]

Generates an interactive 3D plot of vacancy trajectories using Plotly.

This method creates a static but interactive (rotatable, zoomable) 3D plot of the complete vacancy paths over a specified time range.

Parameters:

  • vacancy_indices (int | list) – Index or list of indices for the vacancies to be plotted.

  • step_init (int, optional) – The starting step for the trajectory plot. Defaults to 0.

  • step_final (int | None, optional) – The ending step for the plot. If None, plots to the end. Defaults to None.

  • unwrap (bool, optional) – If True, plots the continuous, unwrapped path. Defaults to False.

  • alpha (float, optional) – Opacity for trajectory lines. Defaults to 0.6.

  • disp (bool, optional) – If True, displays the plot interactively. Defaults to True.

  • save (bool, optional) – If True, saves the plot as a standalone HTML file. Defaults to False.

  • filename (str, optional) – The name of the output HTML file if save is True. Defaults to “trajectory.html”.

Returns:

This method saves an HTML file or displays a plot.

Return type:

None

Raises:

ValueError – If the specified step_init or step_final is out of bounds.

class vachoppy.trajectory.TrajectoryAnalyzer(trajectory: Trajectory, site: Site | None = None, eps: float = 0.001, verbose: bool = True)[source]

Analyzes and quantifies hopping statistics from Trajectory and Site objects.

This class serves as a post-processor for the Trajectory analysis. It takes pre-computed lattice information (from a Site object) and a detailed hop analysis (from a Trajectory object) to calculate key diffusion statistics, such as hop counts per path, site residence times, and the theoretical mean squared displacement from a random walk perspective.

The main workflow is to initialize the class with a fully processed Trajectory object. All calculations are performed automatically upon initialization, and results can be viewed using the .summary() method.

Parameters:

  • trajectory (Trajectory) – An initialized and fully processed Trajectory object.

  • site (Site | None, optional) – An initialized Site object. If None, the site object associated with the trajectory object will be used. Defaults to None.

  • eps (float, optional) – A tolerance value for floating-point comparisons when categorizing hopping paths. Defaults to 1e-3.

  • verbose (bool, optional) – Verbosity flag. Defaults to True.

hopping_history

A nested list containing a time-ordered sequence of hop dictionaries for each vacancy.

Type:

list[list[dict]]

counts

A 2D array of shape (num_vacancies, num_paths) counting the occurrences of each pre-defined hop path.

Type:

numpy.ndarray

counts_unknown

A 2D array counting occurrences of dynamically discovered “unknown” hop paths that were not in the initial Site definition.

Type:

numpy.ndarray

residence_time

A 2D array of shape (num_vacancies, num_sites) storing the total time (in ps) each vacancy spent at each inequivalent site type.

Type:

numpy.ndarray

msd_rand

The Mean Squared Displacement (Ų) calculated from all observed hops, based on random walk theory.

Type:

float

Raises:

AttributeError – If the input trajectory or site objects are missing required attributes for the analysis.

Examples

>>> # First, create Site and Trajectory objects
>>> site_info = Site(path_structure='POSCAR', symbol='O')
>>> traj_analysis = Trajectory(
...     path_traj='TRAJ_O.h5',
...     site=site_info,
...     t_interval=0.1
... )
>>> # Now, create the analyzer with the trajectory results
>>> analyzer = TrajectoryAnalyzer(trajectory=traj_analysis, verbose=True)
# A full summary of hopping statistics is printed upon initialization.
summary() → None[source]

Prints a comprehensive, multi-part summary of the hopping analysis.

The summary includes tables for: - Path Counts: The number of times each defined (and unknown) path was traversed by each vacancy. - Residence Time: The total time each vacancy spent at each inequivalent site type. - Hopping Sequence: A detailed, time-ordered log of every hop for each vacancy.

class vachoppy.trajectory.TrajectoryBundle(path_traj: str, symbol: str, prefix: str = 'TRAJ', depth: int = 2, eps: float = 0.001, verbose: bool = False)[source]

Manages and validates one or more HDF5 trajectory files.

This class handles two main scenarios:

  1. Single File Mode: Processes a single, specified HDF5 trajectory file.

  2. Directory Search Mode: Recursively searches a directory for HDF5 files, groups them by temperature, and validates their consistency.

It ensures that all processed files are from consistent simulations (e.g., same timestep, atom counts, lattice). The primary workflow is to initialize the class, which triggers file discovery and validation. Results can then be saved to a summary file using the .summary() method.

Parameters:

  • path_traj (str) – Path to a single HDF5 file or a root directory to search for files.

  • symbol (str) – The chemical symbol of the target element, used to filter files.

  • prefix (str, optional) – The prefix of trajectory files to search for (e.g., “TRAJ”). Used only when searching a directory. Defaults to “TRAJ”.

  • depth (int, optional) – The maximum directory depth to search for files. Used only when searching a directory. Defaults to 2.

  • eps (float, optional) – The tolerance for comparing floating-point values in metadata (e.g., temperature, dt, lattice vectors). Defaults to 1.0e-3.

  • verbose (bool, optional) – Verbosity flag. Defaults to False.

temperatures

A sorted list of unique temperatures found across all valid files.

Type:

list[float]

traj

A nested list where each sublist contains the full file paths for a corresponding temperature in self.temperatures.

Type:

list[list[str]]

atom_count

The number of atoms for the specified symbol, confirmed to be consistent across all files.

Type:

int

lattice

The 3x3 lattice vectors as a NumPy array, confirmed to be consistent.

Type:

numpy.ndarray

Raises:

  • FileNotFoundError – If the provided path_traj does not exist, or if no valid trajectory files matching the criteria are found during a directory search.

  • ValueError – If depth is less than 1, or if inconsistent simulation parameters (dt, atom_counts, lattice) are found among the files.

  • IOError – If a trajectory file or its metadata cannot be read.

summary(filename: str = 'Bundle.txt') → None[source]

Creates a text file summarizing the found trajectories.

This method generates a detailed text summary that includes: - Consistent system information (symbol, atom count, lattice). - A list of all found trajectory files, grouped by temperature. - The simulation time for each file and the total time per temperature.

The summary is saved to the specified file.

Parameters:

filename (str, optional) – The path and name of the output summary file. Defaults to ‘bundle.txt’.

Returns:

This method does not return a value; it writes a file to disk.

Return type:

None

Examples

>>> bundle = TrajectoryBundle(...)
>>> # Save summary to the default 'bundle.txt'
>>> bundle.summary()

>>> # Save summary to a custom file
>>> bundle.summary(filename='simulation_summary.log')