dfttoolkit.utils package

Submodules

dfttoolkit.utils.file_crawler module

dfttoolkit.utils.file_crawler.find_aims_output_file(calc_dir, allow_all_out_files=False)

Searches directory for output files

dfttoolkit.utils.file_crawler.find_all_aims_output_files(directory, include_restart=True, allow_all_out_files=False)

Recursively searches for AIMS output files and returns their full filenames as a list

dfttoolkit.utils.file_crawler.find_file(calc_dir, allow_all_out_files=False, list_of_filenames=[])

Searches directory for output files

dfttoolkit.utils.file_crawler.find_vasp_output_file(calc_dir)

Searches directory for output files

dfttoolkit.utils.file_utils module

dfttoolkit.utils.file_utils.aims_bin_path_prompt(change_bin: bool | str, save_dir) → str

Prompt the user to enter the path to the FHI-aims binary, if not already found in .aims_bin_loc.txt

If it is found in .aims_bin_loc.txt, the path will be read from there, unless change_bin is True, in which case the user will be prompted to enter the path again.

Parameters:

• change_bin (Union[bool, str]) – whether the user wants to change the binary path. If str == “change_bin”, the user will be prompted to enter the path to the binary again.

• save_dir (str) – the directory to save or look for the .aims_bin_loc.txt file

Returns:

binary – path to the location of the FHI-aims binary

Return type:

str

dfttoolkit.utils.file_utils.check_required_files(files: list, *args: str, any=False) → None

Raise an error if a necessary file was not given.

Parameters:

• files (list) – supported files to reference provided files against

• *args (str) – the files that are required to be provided

• any (bool) – whether at least one of the files is required or all of them

Raises:

ValueError – if a necessary file was not given

dfttoolkit.utils.geometry_utils module

dfttoolkit.utils.geometry_utils.read_xyz_animation(filename) → list

Reads an XYZ animation file, i.e. an XYZ file containing serveral geometries.

Parameters:

filename (str) – path to xyz animation file

Returns:

list of XYZGeometries

Return type:

list

dfttoolkit.utils.math_utils module

dfttoolkit.utils.math_utils.apply_gaussian_window(data, std=0.4)

Apply a Gaussian window to an array.

Parameters:

• data (np.array) – Input data array to be windowed.

• std (float) – Standard deviation of the Gaussian window.

Returns:

windowed_data – Windowed data array.

Return type:

np.array

dfttoolkit.utils.math_utils.apply_hann_window(data)

Apply a Hann window to an array.

Parameters:

data (np.ndarray) – Input data array to be windowed.

Returns:

Windowed data array.

Return type:

np.ndarray

dfttoolkit.utils.math_utils.gaussian_window(N, std=0.4)

Generate a Gaussian window.

Parameters:

• N (int) – Number of points in the window.

• std (float) – Standard deviation of the Gaussian window, normalized such that the maximum value occurs at the center of the window.

Returns:

window – Gaussian window of length N.

Return type:

np.array

dfttoolkit.utils.math_utils.get_angle_between_vectors(vector_1: ndarray[Any, dtype[_ScalarType_co]], vector_2: ndarray[Any, dtype[_ScalarType_co]]) → ndarray[Any, dtype[_ScalarType_co]]

Determines angle between two vectors.

Parameters:

• vector_1 (npt.NDArray)

• vector_2 (npt.NDArray)

Returns:

angle – Angle in radiants.

Return type:

float

dfttoolkit.utils.math_utils.get_autocorrelation_function_manual_lag(signal: ndarray[Any, dtype[_ScalarType_co]], max_lag: int) → ndarray[Any, dtype[_ScalarType_co]]

Alternative method to determine the autocorrelation function for a given signal that used numpy.corrcoef. This function allows to set the lag manually.

Parameters:

• signal (1D npt.NDArray) – Siganl for which the autocorrelation function should be calculated.

• max_lag (Union[None, int]) – Autocorrelation will be calculated for a range of 0 to max_lag, where max_lag is the largest lag for the calculation of the autocorrelation function

Returns:

autocorrelation – Autocorrelation function from 0 to max_lag.

Return type:

npt.NDArray

dfttoolkit.utils.math_utils.get_cartesian_coords(frac_coords: ndarray[Any, dtype[_ScalarType_co]], lattice_vectors: ndarray[Any, dtype[_ScalarType_co]]) → ndarray[Any, dtype[_ScalarType_co]]

Transform fractional coordinates into cartesian coordinates.

Parameters:

• frac_coords ([N x N_dim] numpy array) – Fractional coordinates of atoms (can be Nx2 or Nx3)

• lattice_vectors ([N_dim x N_dim] numpy array:) – Matrix of lattice vectors: Each ROW corresponds to one lattice vector!

Returns:

cartesian_coords – Cartesian coordinates of atoms

Return type:

[N x N_dim] numpy array

dfttoolkit.utils.math_utils.get_cross_correlation_function(signal_0: ndarray[Any, dtype[_ScalarType_co]], signal_1: ndarray[Any, dtype[_ScalarType_co]], detrend: bool = False) → ndarray[Any, dtype[_ScalarType_co]]

Calculate the autocorrelation function for a given signal.

Parameters:

• signal_0 (1D npt.NDArray) – First siganl for which the correlation function should be calculated.

• signal_1 (1D npt.NDArray) – Second siganl for which the correlation function should be calculated.

Returns:

correlation – Autocorrelation function from 0 to max_lag.

Return type:

npt.NDArray

dfttoolkit.utils.math_utils.get_fourier_transform(signal: ndarray[Any, dtype[_ScalarType_co]], time_step: float) → tuple

Calculate the fourier transform of a given siganl.

Parameters:

• signal (1D npt.NDArray) – Siganl for which the autocorrelation function should be calculated.

• time_step (float) – Time step of the signal in seconds.

Returns:

Frequencs and absolute values of the fourier transform.

Return type:

(npt.NDArray, npt.NDArray)

dfttoolkit.utils.math_utils.get_fractional_coords(cartesian_coords: ndarray[Any, dtype[_ScalarType_co]], lattice_vectors: ndarray[Any, dtype[_ScalarType_co]]) → ndarray[Any, dtype[_ScalarType_co]]

Transform cartesian coordinates into fractional coordinates.

Parameters:

• cartesian_coords ([N x N_dim] numpy array) – Cartesian coordinates of atoms (can be Nx2 or Nx3)

• lattice_vectors ([N_dim x N_dim] numpy array:) – Matrix of lattice vectors: Each ROW corresponds to one lattice vector!

Returns:

fractional_coords – Fractional coordinates of atoms

Return type:

[N x N_dim] numpy array

dfttoolkit.utils.math_utils.get_mirror_matrix(normal_vector: ndarray[Any, dtype[_ScalarType_co]]) → ndarray[Any, dtype[_ScalarType_co]]

Generates a transformation matrix for mirroring through plane given by the normal vector.

Parameters:

normal_vector (npt.NDArray) – Normal vector of the mirror plane.

Returns:

M – Mirror matrix

Return type:

npt.NDArray

dfttoolkit.utils.math_utils.get_moving_average(signal: ndarray[Any, dtype[float64]], window_size: int)

Cacluated the moving average and the variance around the moving average.

Parameters:

• signal (npt.NDArray[np.float64]) – Signal for which the moving average should be calculated.

• window_size (int) – Window size for the mocing average.

Returns:

• moving_avg (TYPE) – Moving average.

• variance (TYPE) – Variance around the moving average.

dfttoolkit.utils.math_utils.get_rotation_matrix(vec_start: ndarray[Any, dtype[_ScalarType_co]], vec_end: ndarray[Any, dtype[_ScalarType_co]]) → ndarray[Any, dtype[_ScalarType_co]]

Given a two (unit) vectors, vec_start and vec_end, this function calculates the rotation matrix U, so that U * vec_start = vec_end.

U the is rotation matrix that rotates vec_start to point in the direction of vec_end.

https://math.stackexchange.com/questions/180418/calculate-rotation-matrix-to-align-vector-a-to-vector-b-in-3d/897677

Parameters:

• vec_start (npt.NDArray[np.float64]) – Two vectors that should be aligned. Both vectors must have a l2-norm of 1.

• vec_end (npt.NDArray[np.float64]) – Two vectors that should be aligned. Both vectors must have a l2-norm of 1.

• Returns

• --------

• R – The rotation matrix U as npt.NDArray with shape (3,3)

dfttoolkit.utils.math_utils.get_rotation_matrix_around_axis(axis: ndarray[Any, dtype[_ScalarType_co]], phi: float) → ndarray[Any, dtype[_ScalarType_co]]

Generates a rotation matrix around a given vector.

Parameters:

• axis (npt.NDArray) – Axis around which the rotation is done.

• phi (float) – Angle of rotation around axis in radiants.

Returns:

R – Rotation matrix

Return type:

npt.NDArray

dfttoolkit.utils.math_utils.get_rotation_matrix_around_z_axis(phi: float) → ndarray[Any, dtype[_ScalarType_co]]

Generates a rotation matrix around the z axis.

Parameters:

phi (float) – Angle of rotation around axis in radiants.

Returns:

Rotation matrix

Return type:

npt.NDArray

dfttoolkit.utils.math_utils.hann_window(N)

Generate a Hann window.

Parameters:

N (int) – Number of points in the window.

Returns:

Hann window of length N.

Return type:

np.ndarray

dfttoolkit.utils.math_utils.lorentzian(x: float | ndarray[Any, dtype[_ScalarType_co]], a: float, b: float, c: float) → float | ndarray[Any, dtype[_ScalarType_co]]

Returns a Lorentzian function.

Parameters:

• x (Union[float, npt.NDArray]) – Argument x of f(x) –> y.

• a (float) – Maximum of Lorentzian.

• b (float) – Width of Lorentzian.

• c (float) – Magnitude of Lorentzian.

Returns:

f – Outupt of a Lorentzian function.

Return type:

Union[float, npt.NDArray]

dfttoolkit.utils.math_utils.mae(delta: ndarray) → floating

Calculated the mean absolute error from a list of value differnces.

Parameters:

delta (np.ndarray) – Array containing differences

Returns:

mean absolute error

Return type:

float

dfttoolkit.utils.math_utils.norm_matrix_by_dagonal(matrix: ndarray[Any, dtype[_ScalarType_co]]) → ndarray[Any, dtype[_ScalarType_co]]

Norms a matrix such that the diagonal becomes 1.

a_11 a_12 a_13 | | 1 a’_12 a’_13 |

a_21 a_22 a_23 | –> | a’_21 1 a’_23 |

a_31 a_32 a_33 | | a’_31 a’_32 1 |

Parameters:

matrix (npt.NDArray) – Matrix that should be normed.

Returns:

matrix – Normed matrix.

Return type:

npt.NDArray

dfttoolkit.utils.math_utils.rel_mae(delta: ndarray, target_val: ndarray) → floating

Calculated the relative mean absolute error from a list of value differnces, given the target values.

Parameters:

• delta (np.ndarray) – Array containing differences

• target_val (np.ndarray) – Array of target values against which the difference should be compared

Returns:

relative mean absolute error

Return type:

float

dfttoolkit.utils.math_utils.rel_rmse(delta: ndarray, target_val: ndarray) → float

Calculated the relative root mean sqare error from a list of value differnces, given the target values.

Parameters:

• delta (np.ndarray) – Array containing differences

• target_val (np.ndarray) – Array of target values against which the difference should be compared

Returns:

relative root mean sqare error

Return type:

float

dfttoolkit.utils.math_utils.rmse(delta: ndarray) → float

Calculated the root mean sqare error from a list of value differnces.

Parameters:

delta (np.ndarray) – Array containing differences

Returns:

root mean square error

Return type:

float

dfttoolkit.utils.periodic_table module

class dfttoolkit.utils.periodic_table.PeriodicTable

Bases: object

Create a periodic table object

Returns:

a dictionary representing the periodic table

Return type:

dict

get_atomic_mass(element: str | int) → float

Returns the atomic mass if given the species as a string.

Parameters:

species (str or int) – Name or chemical sysmbol of the atomic species.

Returns:

atomic mass in atomic units.

Return type:

float

get_atomic_number(element: str | int) → int

Returns the atomic number if given the species as a string.

Parameters:

species (str or int) – Name or chemical sysmbol of the atomic species.

Returns:

atomic number.

Return type:

int

get_chemical_symbol(element: str | int) → float

Returns the chemical symbol if given the species as an atomic number.

Parameters:

species (str or int) – Name or chemical sysmbol of the atomic species.

Returns:

atomic mass in atomic units.

Return type:

float

get_covalent_radius(element: str | int) → float

Returns the chemical symbol if given the species as an atomic number.

Parameters:

species (str or int) – Name or chemical sysmbol of the atomic species.

Returns:

Covalent radius in atomic units.

Return type:

float

get_element_dict(element: str | int) → dict

get_species_colors(element: str | int) → List[float]

Returns the chemical symbol if given the species as an atomic number.

Parameters:

species (str or int) – Name or chemical sysmbol of the atomic species.

Returns:

Covalent radius in atomic units.

Return type:

float

load() → dict

dfttoolkit.utils.run_utils module

dfttoolkit.utils.run_utils.no_repeat(original_func=None, *, output_file: str = 'aims.out', calc_dir: str = './', force: bool = False)

Don’t repeat the calculation if aims.out exists in the calculation directory.

Parameters:

• output_file (str, default='aims.out') – The name of the output file to check for.

• calc_dir (str, default="./") – The directory where the calculation is performed

• force (bool, default=False) – If True, the calculation is performed even if aims.out exists in the calculation directory.

Raises:

ValueError – if the calc_dir kwarg is not a directory

dfttoolkit.utils.units module

dfttoolkit.utils.vibrations_utils module

dfttoolkit.utils.vibrations_utils.get_cross_correlation_function(signal_0: ndarray[Any, dtype[_ScalarType_co]], signal_1: ndarray[Any, dtype[_ScalarType_co]], bootstrapping_blocks: int = 1) → ndarray[Any, dtype[_ScalarType_co]]

dfttoolkit.utils.vibrations_utils.get_cross_spectrum(signal_0: ~numpy.ndarray[~typing.Any, ~numpy.dtype[~numpy._typing._array_like._ScalarType_co]], signal_1: ~numpy.ndarray[~typing.Any, ~numpy.dtype[~numpy._typing._array_like._ScalarType_co]], time_step: float, bootstrapping_blocks: int = 1, bootstrapping_overlap: int = 0, zero_padding: int = 0, cutoff_at_last_maximum: bool = False, window_function: str = 'none') -> (<built-in function array>, <built-in function array>)

Determine the cross spectrum for a given signal using bootstrapping:

• Splitting the sigmal into blocks and for each block:

  • Determining the cross correlation function of the signal

  • Determining the fourire transform of the autocorrelation function to get the power spectrum for the block

• Calculating the average power spectrum by averaging of the power spectra of all blocks

Parameters:

• signal_0 (1D np.array) – First siganl for which the correlation function should be calculated.

• signal_1 (1D np.array) – Second siganl for which the correlation function should be calculated.

• time_step (float) – DESCRIPTION.

• bootstrapping_blocks (int, default=1) – DESCRIPTION

• bootstrapping_overlap (int, default=0) – DESCRIPTION

• zero_padding (int, default=0) – Pad the cross correlation function with zeros to increase the frequency resolution of the FFT. This also avoids the effect of varying spectral leakage. However, it artificially broadens the resulting cross spectrum and introduces wiggles.

• cutoff_at_last_maximum (bool, default=False) – Cut off the cross correlation function at the last maximum to hide spectral leakage.

Returns:

• frequencies (np.array) – Frequiencies of the power spectrum in units depending on the tims_step.

• cross_spectrum (np.array) – Power spectrum.

dfttoolkit.utils.vibrations_utils.get_cross_spectrum_mem(signal_0: ndarray[Any, dtype[_ScalarType_co]], signal_1: ndarray[Any, dtype[_ScalarType_co]], time_step, model_order, n_freqs=512)

Estimate the power spectral density (PSD) of a time series using the Maximum Entropy Method (MEM).

Parameters: - x: array-like, time series data. - p: int, model order (number of poles). Controls the smoothness and resolution of the PSD. - n_freqs: int, number of frequency bins for the PSD.

Returns: - freqs: array of frequency bins. - psd: array of PSD values at each frequency.

dfttoolkit.utils.vibrations_utils.get_last_maximum(x: ndarray[Any, dtype[_ScalarType_co]])

dfttoolkit.utils.vibrations_utils.get_line_widths(frequencies, power_spectrum, filter_maximum=True, use_lorentzian=True)

dfttoolkit.utils.vibrations_utils.get_normal_mode_decomposition(velocities: ndarray[Any, dtype[_ScalarType_co]], eigenvectors: ndarray[Any, dtype[_ScalarType_co]], use_numba: bool = True) → ndarray[Any, dtype[_ScalarType_co]]

Calculate the normal-mode-decomposition of the velocities. This is done by projecting the atomic velocities onto the vibrational eigenvectors. See equation 10 in: https://doi.org/10.1016/j.cpc.2017.08.017

Parameters:

• velocities (np.array) – Array containing the velocities from an MD trajectory structured in the following way: [number of time steps, number of atoms, number of dimensions].

• eigenvectors (np.array) – Array of eigenvectors structured in the following way: [number of frequencies, number of atoms, number of dimensions].

Returns:

velocities_projected – Velocities projected onto the eigenvectors structured as follows: [number of time steps, number of frequencies]

Return type:

np.array

dfttoolkit.utils.vibrations_utils.get_peak_parameters(frequencies, power_spectrum)

dfttoolkit.utils.vibrations_utils.lorentzian_fit(frequencies, power_spectrum, p_0=None, filter_maximum=0)

Module contents