Additional functions

calorine.tools.analyze_data(data, max_lag=None)[source]

Carries out an extensive analysis of the data series.

Parameters:

  • data (ndarray) – data series to compute autocorrelation function for

  • max_lag (Optional[int]) – maximum lag between two data points, used for computing autocorrelation

Returns:

calculated properties of the data including, mean, standard deviation, correlation length and a 95% error estimate.

Return type:

dict

calorine.tools.get_autocorrelation_function(data, max_lag=None)[source]

Returns autocorrelation function.

The autocorrelation function is computed using pandas.Series.autocorr.

Parameters:

  • data (ndarray) – data series to compute autocorrelation function for

  • max_lag (Optional[int]) – maximum lag between two data points

Return type:

ndarray

Returns:

calculated autocorrelation function

calorine.tools.get_correlation_length(data)[source]

Returns estimate of the correlation length of data.

The correlation length is taken as the first point where the autocorrelation functions is less than \(\exp(-2)\). If the correlation function never drops below \(\exp(-2)\) np.nan is returned.

If the correlation length cannot be computed since the auto-correlation function is unconverged the function returns None.

Parameters:

data (ndarray) – data series for which to the compute autocorrelation function

Return type:

Optional[int]

Returns:

correlation length

calorine.tools.get_elastic_stiffness_tensor(structure, clamped=False, epsilon=0.001, **kwargs)[source]

Calculate and return the elastic stiffness tensor in units of GPa for the given structure in Voigt form.

Parameters:

  • structure (Atoms) – input structure; should be fully relaxed

  • clamped (bool) – if False (default) return the relaxed elastic stiffness tensor; if True return the clamped ion elastic stiffness tensor

  • epsilon (float) – magnitude of the applied strain

  • kwargs – keyword arguments forwarded to the relax_structure function used for relaxing the structure when computing the relaxed stiffness tensor; it should not be necessary to change the default for the vast majority of use cases; use with care

Return type:

Stiffness tensor in units of GPa

calorine.tools.get_error_estimate(data, confidence=0.95)[source]

Returns estimate of standard error \(\mathrm{error}\) with confidence interval.

\[\mathrm{error} = t_\mathrm{factor} * \mathrm{std}(\mathrm{data}) / \sqrt{N_s}\]

where \(t_{factor}\) is the factor corresponding to the confidence interval and \(N_s\) is the number of independent measurements (with correlation taken into account).

If the correlation length cannot be computed since the auto-correlation function is unconverged the function returns None.

Parameters:

data (ndarray) – data series for which to estimate the error

Return type:

Optional[float]

Returns:

error estimate

calorine.tools.get_force_constants(structure, calculator, supercell_matrix, kwargs_phonopy={}, kwargs_generate_displacements={})[source]

Calculates the force constants for a given structure using phonopy, which needs to be cited if this function is used for generating data for publication. The function returns a Phonopy object that can be used to calculate, e.g., the phonon dispersion, the phonon density of states as well as related quantities such as the thermal displacements and the free energy.

Parameters:

  • structure (Atoms) – structure for which to compute the phonon dispersion; usually this is a primitive cell

  • calculator (SinglePointCalculator) – ASE calculator to use for the calculation of forces

  • supercell_matrix (ndarray) – specification of supercell size handed over to phonopy; should be a tuple of three values or a matrix

  • kwargs_phonopy (Dict[str, Any]) – Expert option: keyword arguments used when initializing the Phonopy object; this includes, e.g., the tolerance used when determining the symmetry (symprec) and parameters for the non-analytical corrections (nac_params)

  • kwargs_generate_displacements (Dict[str, Any]) – Expert option: keyword arguments to be handed over to the generate_displacements method; this includes in particular the distance keyword, which specifies the magnitude of the atomic displacement imposed when calculating the force constant matrix

Return type:

Phonopy

calorine.tools.get_rtc_from_hac(hac, V, T, dt)[source]

Returns the running thermal conductivity (RTC) in W/m/K using a heat auto-correlation (HAC) as input.

Parameters:

  • hac (ndarray) – The HAC \(\langle j(t)j(0)\rangle\) in units of eV3/amu as given by GPUMD

  • V (float) – Volume of cell in Å3

  • T (float) – Temperature in Kelvin

  • dt (float) – Time step in the HAC in ps running thermal conductivity in W/m/K

Return type:

ndarray

calorine.tools.relax_structure(structure, fmax=0.001, steps=500, minimizer='bfgs', constant_cell=False, constant_volume=False, scalar_pressure=0.0, **kwargs)[source]

Relaxes the given structure.

Parameters:

  • structure (Atoms) – Atomic configuration to relax.

  • fmax (float) – Stop relaxation if the absolute force for all atoms falls below this value.

  • steps (int) – Maximum number of relaxation steps the minimizer is allowed to take.

  • minimizer (str) – Minimizer to use; possible values: ‘bfgs’, ‘lbfgs’, ‘fire’, ‘gpmin’, ‘bfgs-scipy’.

  • constant_cell (bool) – If True do not relax the cell or the volume.

  • constant_volume (bool) – If True relax the cell shape but keep the volume constant.

  • kwargs – Keyword arguments to be handed over to the minimizer; possible arguments can be found in the ASE documentation https://wiki.fysik.dtu.dk/ase/ase/filters.html#the-frechetcellfilter-class.

  • scalar_pressure (float) – External pressure in GPa.

Return type:

None