vachoppy.frequency

vachoppy.frequency

Provides the AttemptFrequency class for calculating the attempt frequency (ν) of vacancy hopping events.

In the context of diffusion, the jump rate (Γ) is often described by the Arrhenius equation: Γ = ν * exp(-Ea / kT). This module is dedicated to calculating the pre-exponential factor, ν, which represents the frequency at which an atom attempts to overcome an energy barrier.

Main Components

  • AttemptFrequency: A class that integrates statistical results from a CalculatorEnsemble analysis (via a parameters.json file) with activation energies (Ea) from an external source, typically a Nudged Elastic Band (NEB) calculation (via a .csv file). It calculates both path-wise and effective attempt frequencies.

Typical Usage

The typical workflow involves using the output from a previous CalculatorEnsemble run and a separate file containing NEB results.

from vachoppy.frequency import AttemptFrequency

# Assuming 'parameters.json' was generated by CalculatorEnsemble
# and 'neb_barriers.csv' contains path names and activation energies.

# Initialize the class to run the calculation
freq_analyzer = AttemptFrequency(
    parameter_json='parameters.json',
    neb_csv='neb_barriers.csv',
    verbose=True
)

# A summary is printed automatically if verbose=True.
# Visualize the results.
freq_analyzer.plot_nu()
freq_analyzer.plot_z()
class vachoppy.frequency.AttemptFrequency(parameter_json: str, neb_csv: str, verbose: bool = True)[source]

Calculates path-wise and effective attempt frequencies for diffusion.

This class integrates pre-computed simulation parameters (from CalculatorEnsemble) with Nudged Elastic Band (NEB) results to calculate temperature-dependent attempt frequencies (ν) and effective coordination numbers (z).

The main workflow is to initialize the class with the paths to the two required input files. The entire calculation pipeline is executed upon initialization. Results can then be inspected using the .summary() method or visualized with

the .plot_nu() and .plot_z() methods.

Parameters:

  • parameter_json (str) – Path to the JSON file containing aggregated parameters from a CalculatorEnsemble analysis.

  • neb_csv (str) – Path to the CSV file containing NEB-calculated activation barriers for each unique hopping path.

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

nu

The effective attempt frequency (THz) for each temperature.

Type:

numpy.ndarray

nu_path

The path-wise attempt frequency (THz) for each path at each temperature.

Type:

numpy.ndarray

z

The effective coordination number for each temperature.

Type:

numpy.ndarray

Ea_path

Activation energy (eV) for each unique path, loaded from the NEB file.

Type:

numpy.ndarray

temperatures

An array of the unique temperatures (K) from the parameter file.

Type:

numpy.ndarray

Raises:

  • FileNotFoundError – If the parameter_json or neb_csv file is not found.

  • KeyError – If the parameter_json file is missing required data fields.

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) as a function of temperature.

Parameters:

  • title (str | None, optional) – A custom title for the plot. Defaults to “Attempt Frequency vs. Temperature”.

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

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

  • filename (str, optional) – The path and name of the file to save the plot. Defaults to “attempt_frequency.png”.

  • dpi (int, optional) – The resolution for the saved figure. Defaults to 300.

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) as a function of temperature.

Parameters:

  • title (str | None, optional) – A custom title for the plot. Defaults to “Coordination Number vs. Temperature”.

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

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

  • filename (str, optional) – The path to save the plot. Defaults to “coordination_number.png”.

  • dpi (int, optional) – The resolution for the saved figure. Defaults to 300.

summary() → None[source]

Prints a comprehensive summary of the attempt frequency analysis results, including temperature-dependent data and path-wise details in tables.

update_json(filename: str | None = None) → None[source]

Updates the source JSON file with newly calculated parameters.

This method reads the original parameter JSON file, adds or updates fields calculated by this class (e.g., nu, z, Ea_path), and writes the data back to a file. NumPy arrays are converted to lists for JSON compatibility.

Parameters:

filename (str | None, optional) – The path to the output JSON file. If None, the original input file (self.parameter_json) is overwritten. Defaults to None.