Tools

A number of utility functions, for example for dealing with autocorrelation functions, Fourier transforms, and smoothing.

dynasor.tools.acfs.compute_acf(Z, delta_t=1.0, method='scipy')

Computes the autocorrelation function (ACF) for a one-dimensional signal \(Z\) in time as

\[ACF(\tau) = \frac{\left < Z(t) Z^*(t+\tau) \right >}{\left < Z(t) Z^*(t) \right >}\]

Here, only the real part of the ACF is returned since if \(Z\) is complex the imaginary part should average out to zero for any stationary signal.

Parameters:

• Z (ndarray[tuple[int, ...], dtype[float]]) – complex time signal

• delta_t (float) – spacing in time between two consecutive values in \(Z\)

• method – implementation to use; possible values: numpy and scipy (default and usually faster)

dynasor.tools.acfs.fermi_dirac(t, t_0, t_width)

Evaluates a Fermi-Dirac-like function in time \(f(t)\), which can be applied to an ACF in time to artificially damp it, i.e., forcing it to go to zero for long times without affecting the short-time correlations too much.

\[f(t) = \frac{1}{\exp{[(t-t_0)/t_\mathrm{width}}] + 1}\]

Parameters:

• t (ndarray[tuple[int, ...], dtype[float]]) – time array

• t_0 (float) – starting time for decay

• t_width (float) – width of the decay

dynasor.tools.acfs.gaussian_decay(t, t_sigma)

Evaluates a gaussian distribution in time \(f(t)\), which can be applied to an ACF in time to artificially damp it, i.e., forcing it to go to zero for long times.

\[f(t) = \exp{\left [-\frac{1}{2} \left (\frac{t}{t_\mathrm{sigma}}\right )^2 \right ] }\]

Parameters:

• t (ndarray[tuple[int, ...], dtype[float]]) – time array

• t_sigma (float) – width (standard deviation of the gaussian) of the decay

dynasor.tools.acfs.psd_from_acf(acf, dt=1, angular=True, even=True)

Computes the power spectral density from auto-correlation function

Parameters:

• acf – The acf as an array

• dt – The timestep between samples

• angular – Whether to return normal or angular freqs

• even – Whether to mirror the acf and force psd to be purely real

dynasor.tools.acfs.smoothing_function(data, window_size, window_type='hamming')

Smoothing function for 1D arrays. This functions employs pandas rolling window average

Parameters:

• data (ndarray[tuple[int, ...], dtype[float]]) – 1D data array

• window_size (int) – The size of smoothing/smearing window

• window_type (str) – What type of window-shape to use, e.g. 'blackman', 'hamming', 'boxcar' (see pandas and scipy documentaiton for more details)

dynasor.tools.damped_harmonic_oscillator.acf_position_dho(t, w0, gamma, A=1.0)

The damped damped harmonic oscillator (DHO) autocorrelation function for the position. The definition of this function can be found in the dynasor documentation <dynasor.materialsmodeling.org/theory.html#damped-harmonic-oscillator-model>_.

Parameters:

• t (ndarray[tuple[int, ...], dtype[float]]) – Time, usually as an array.

• w0 (float) – Natural angular frequency of the DHO.

• gamma (float) – Damping of DHO.

• A (float) – Amplitude of the DHO.

dynasor.tools.damped_harmonic_oscillator.acf_velocity_dho(t, w0, gamma, A=1.0)

The damped damped harmonic oscillator (DHO) autocorrelation function for the velocity. The definition of this function can be found in the dynasor documentation <dynasor.materialsmodeling.org/theory.html#damped-harmonic-oscillator-model>_.

Parameters:

• t (ndarray[tuple[int, ...], dtype[float]]) – Time, usually as an array.

• w0 (float) – Natural angular frequency of the DHO.

• gamma (float) – Damping of DHO.

• A (float) – Amplitude of the DHO.

dynasor.tools.damped_harmonic_oscillator.psd_position_dho(w, w0, gamma, A=1.0)

The power spectral density (PSD) function for the damped harmonic oscillator (DHO) (i.e., the Fourier transform of the autocorrelation function) for the position.

The definition of this function can be found in the dynasor documentation <dynasor.materialsmodeling.org/theory.html#damped-harmonic-oscillator-model>_.

Parameters:

• w (ndarray[tuple[int, ...], dtype[float]]) – Angular frequency, usually as an array.

• w0 (float) – Natural angular frequency of the DHO.

• gamma (float) – Damping of DHO.

• A (float) – Amplitude of the DHO.

dynasor.tools.damped_harmonic_oscillator.psd_velocity_dho(w, w0, gamma, A=1.0)

The power spectral density (PSD) function for the damped harmonic oscillator (DHO) (i.e., the Fourier transform of the autocorrelation function) for the position.

The definition of this function can be found in the dynasor documentation <dynasor.materialsmodeling.org/theory.html#damped-harmonic-oscillator-model>_.

Parameters:

• w (ndarray[tuple[int, ...], dtype[float]]) – Angular frequency, usually as an array.

• w0 (float) – Natural angular frequency of the DHO.

• gamma (float) – Damping of DHO.

• A (float) – Amplitude of the DHO.

dynasor.tools.structures.align_structure(atoms, atol=1e-05)

Rotates and realigns a structure such that * the first cell vector points along the x-directon * the second cell vector lies in the xy-plane

Note that this function modifies the atoms object in place.

Parameters:

• atoms (Atoms) – Input structure to be rotated aligned with the x,y,z coordinte system.

• atol (float) – Absolute tolerance used for sanity checking the cell.

dynasor.tools.structures.find_permutation(atoms, atoms_ref)

Returns the best permutation of atoms for mapping one configuration onto another.

Parameters:

• atoms – Configuration to be permuted.

• atoms_ref – Configuration onto which to map.

Examples

After obtaining the permutation via p = find_permutation(atoms1, atoms2) the reordered structure atoms1[p] will give the closest match to atoms2.

dynasor.tools.structures.get_P_matrix(c, S)

Returns the P matrix, i.e., the 3x3 integer matrix \(P\) that satisfies

$$ P c = S $$

Here, \(c\) is the primitive cell metric and \(S\) is the supercell metric as row vectors. Note that the above condition is equivalent to:

$$ c^T P^T = S^T $$

Parameters:

• c (ndarray)

• S (ndarray)

Return type:

ndarray

dynasor.tools.structures.get_displacements(atoms, atoms_ideal, check_mic=True, cell_tol=0.0001)

Returns the the smallest possible displacements between a displaced configuration relative to an ideal (reference) configuration.

Parameters:

• atoms (Atoms) – Structure with displaced atoms.

• ideal – Ideal configuration relative to which displacements are computed.

• check_mic (bool) – Whether to check minimum image convention.

• cell_tol (float) – Cell tolerance; if cell missmatch more than tol value error is raised.

Return type:

ndarray

dynasor.tools.structures.get_displacements_from_u(u, cell, check_mic=True)

wraps displacements using mic

dynasor.tools.structures.get_offset_index(primitive, supercell, tol=0.01, wrap=True)

Returns the basis index and primitive cell offsets for a supercell.

This implementation uses a simple iteration procedure which should be fairly quick. If more stability is needed consider the following approach:

• find the P-matrix: P = ideal.cell @ prim.cell_inv.T

• compensate for strain: P *= len(ideal)/len(prim)/det(P)

• generate the reference structure: ref_atoms = make_supercell(round(P), prim)

• find the assignment using ref_atoms via the Hungarian algorithm using the mic distances

Parameters:

• primitive (Atoms) – Primitive cell.

• supercell (Atoms) – Some ideal repetition of the primitive cell.

• tol (float) – Tolerance length parameter. Increase to allow for slgihtly rattled or strained cells.

• wrap (bool) – It might happen that the ideal cell boundary cuts through a unit cell whose lattice points lie inside the ideal cell. If there is a basis, an atom belonging to this unit cell might get wrapped while another is not. Then the wrapped atom now belongs to a lattice point outside the P matrix so to say. This would result in more lattice points than expected from N_unit = len(ideal)/len(prim).

Returns:

• offsets – The lattice points as integers in (N, 3)-array.

• index – The basis indices as integers in (N,)-array.