dos

DOS calculation class.

class DOS(params: Parameters)

Bases: Target

Postprocessing / parsing functions for the density of states (DOS).

Parameters:

params (mala.common.parameters.Parameters) – Parameters used to create this TargetBase object.

static backconvert_units(array, out_units)

Convert the units of an array from MALA units into desired units.

MALA units for the DOS means 1/eV.

Parameters:

• array (numpy.array) – Data in 1/eV.

• out_units (string) – Desired units of output array.

Returns:

converted_array – Data in out_units.

Return type:

numpy.array

static convert_units(array, in_units='1/eV')

Convert the units of an array into the MALA units.

MALA units for the DOS means 1/eV.

Parameters:

• array (numpy.array) – Data for which the units should be converted.

• in_units (string) –

  Units of array. Currently supported are:

  • 1/eV (no conversion, MALA unit)

  • 1/Ry

Returns:

converted_array – Data in 1/eV.

Return type:

numpy.array

classmethod from_ldos_calculator(ldos_object)

Create a DOS object from an LDOS object.

If the LDOS object has data associated with it, this data will be copied.

Parameters:

ldos_object (mala.targets.ldos.LDOS) – LDOS object used as input.

Returns:

dos_object – DOS object created from LDOS object.

Return type:

mala.targets.dos.DOS

classmethod from_numpy_array(params, array, units='1/eV')

Create an DOS calculator from a numpy array in memory.

By using this function rather then setting the local_density_of_states object directly, proper

Parameters:

• params (mala.common.parameters.Parameters) – Parameters used to create this DOS object.

• array (numpy.ndarray) – Path to file that is being read.

• units (string) – Units the DOS is saved in.

Returns:

dos_calculator – DOS calculator object.

Return type:

mala.targets.dos.DOS

classmethod from_numpy_file(params, path, units='1/eV')

Create an DOS calculator from a numpy array saved in a file.

Parameters:

• params (mala.common.parameters.Parameters) – Parameters used to create this DOS object.

• path (string) – Path to file that is being read.

• units (string) – Units the DOS is saved in.

Returns:

dos_calculator – DOS calculator object.

Return type:

mala.targets.dos.DOS

classmethod from_qe_dos_txt(params, path)

Create a DOS calculator from a Quantum Espresso generated file.

These files do not have a specified file ending, so I will call them qe.dos.txt here. QE saves the DOS in 1/eV.

Parameters:

• params (mala.common.parameters.Parameters) – Parameters used to create this DOS object.

• path (string) – Path of the file containing the DOS.

Returns:

dos_calculator – DOS calculator object.

Return type:

mala.targets.dos.DOS

classmethod from_qe_out(params, path)

Create a DOS calculator from a Quantum Espresso output file.

This will only work if the QE calculation has been performed with very verbose output and contains the bands at all k-points. As much information will be read from the QE output files as possible. There is no need to call read_additional_calculation_data afterwards.

Parameters:

• params (mala.common.parameters.Parameters) – Parameters used to create this DOS object.

• path (string) – Path of the file containing the DOS.

Returns:

dos_calculator – DOS calculator object.

Return type:

mala.targets.dos.DOS

get_band_energy(dos_data=None, fermi_energy=None, temperature=None, integration_method='analytical', broadcast_band_energy=True)

Calculate the band energy from given DOS data.

Parameters:

• dos_data (numpy.array) – DOS data with dimension [energygrid]. If None, then the cached DOS will be used for the calculation.

• fermi_energy (float) – Fermi energy level in eV.

• temperature (float) – Temperature in K.

• integration_method (string) –

  Integration method to be used. Currently supported:

  • ”trapezoid” for trapezoid method

  • ”simpson” for Simpson method.

  • ”analytical” for analytical integration. Recommended.

• broadcast_band_energy (bool) – If True then the band energy will only be calculated on one rank and thereafter be distributed to all other ranks.

Returns:

band_energy – Band energy in eV.

Return type:

float

get_density_of_states(dos_data=None)

Get the density of states.

This function currently doesn’t do much. In the LDOS and density equivalents of it, certain dimensionality reorderings may happen, this function purely exists for consistency reasons. In the future, that may change.

get_energy_grid()

Get energy grid.

Returns:

e_grid – Energy grid on which the DOS is defined.

Return type:

numpy.array

get_entropy_contribution(dos_data=None, fermi_energy=None, temperature=None, integration_method='analytical', broadcast_entropy=True)

Calculate the entropy contribution to the total energy.

Parameters:

• dos_data (numpy.array) – DOS data with dimension [energygrid]. If None, then the cached DOS will be used for the calculation.

• fermi_energy (float) – Fermi energy level in eV.

• temperature (float) – Temperature in K.

• integration_method (string) –

  Integration method to be used. Currently supported:

  • ”trapezoid” for trapezoid method

  • ”simpson” for Simpson method.

  • ”analytical” for analytical integration. Recommended.

• broadcast_entropy (bool) – If True then the entropy will only be calculated on one rank and thereafter be distributed to all other ranks.

Returns:

entropy_contribution – S/beta in eV.

Return type:

float

get_number_of_electrons(dos_data=None, fermi_energy=None, temperature=None, integration_method='analytical')

Calculate the number of electrons from given DOS data.

Parameters:

• dos_data (numpy.array) – DOS data with dimension [energygrid]. If None, then the cached DOS will be used for the calculation.

• fermi_energy (float) – Fermi energy level in eV.

• temperature (float) – Temperature in K.

• integration_method (string) –

  Integration method to be used. Currently supported:

  • ”trapezoid” for trapezoid method

  • ”simpson” for Simpson method.

  • ”analytical” for analytical integration. Recommended.

Returns:

number_of_electrons – Number of electrons.

Return type:

float

get_self_consistent_fermi_energy(dos_data=None, temperature=None, integration_method='analytical', broadcast_fermi_energy=True)

Calculate the self-consistent Fermi energy.

“Self-consistent” does not mean self-consistent in the DFT sense, but rather the Fermi energy, for which DOS integration reproduces the exact number of electrons. The term “self-consistent” stems from how this quantity is calculated.

Parameters:

• dos_data (numpy.array) – DOS data with dimension [energygrid]. If None, then the cached DOS will be used for the calculation.

• temperature (float) – Temperature in K.

• integration_method (string) –

  Integration method to be used. Currently supported:

  • ”trapezoid” for trapezoid method

  • ”simpson” for Simpson method.

  • ”analytical” for analytical integration. Recommended.

• broadcast_fermi_energy (bool) – If True then the Fermi energy will only be calculated on one rank and thereafter be distributed to all other ranks.

Returns:

fermi_energy_self_consistent – \(\epsilon_F\) in eV.

Return type:

float

get_target()

Get the target quantity.

This is the generic interface for cached target quantities. It should work for all implemented targets.

Returns:

density_of_states – Electronic density of states.

Return type:

numpy.ndarray

invalidate_target()

Invalidates the saved target wuantity.

This is the generic interface for cached target quantities. It should work for all implemented targets.

read_from_array(array, units='1/eV')

Read the density data from a numpy array.

Parameters:

• array (numpy.ndarray) – Numpy array containing the DOS.

• units (string) – Units the density is saved in. Usually none.

read_from_numpy_file(path, units=None, array=None, reshape=False)

Read the data from a numpy file.

Parameters:

• path (string) – Path to the numpy file.

• units (string) – Units the data is saved in.

• array (np.ndarray) – If not None, the array to save the data into. The array has to be 4-dimensional.

Returns:

data – If array is None, a numpy array containing the data. Elsewise, None, as the data will be saved into the provided array.

Return type:

numpy.ndarray or None

read_from_qe_dos_txt(path)

Read the DOS from a Quantum Espresso generated file.

These files do not have a specified file ending, so I will call them qe.dos.txt here. QE saves the DOS in 1/eV.

Parameters:

path (string) – Path of the file containing the DOS.

Returns:

DOS data in 1/eV.

Return type:

dos_data

read_from_qe_out(path=None, smearing_factor=2)

Calculate the DOS from a Quantum Espresso DFT output file.

The DOS will be read calculated via the eigenvalues and the equation

\[D(E) = \sum_i \sum_k w_k \delta(\epsilon-\epsilon_{ik})\]

Parameters:

• path (string) – Path to the QE out file. If None, the QE output that was loaded via read_additional_calculation_data will be used.

• smearing_factor (int) – Smearing factor relative to the energy grid spacing. Default is 2.

Returns:

DOS data in 1/eV.

Return type:

dos_data

uncache_properties()

Uncache all cached properties of this calculator.

property band_energy

Band energy of the system, calculated via cached DOS.

property data_name

Get a string that describes the target (for e.g. metadata).

property density_of_states

Density of states as array.

property energy_grid

Energy grid on which the DOS is expressed.

property entropy_contribution

Entropy contribution to the energy calculated via cached DOS.

property feature_size

Get dimension of this target if used as feature in ML.

property fermi_energy

“Self-consistent” Fermi energy of the system.

“Self-consistent” does not mean self-consistent in the DFT sense, but rather the Fermi energy, for which DOS integration reproduces the exact number of electrons. The term “self-consistent” stems from how this quantity is calculated. Calculated via cached DOS.

property number_of_electrons

Number of electrons in the system, calculated via cached DOS.

Does not necessarily match up exactly with KS-DFT provided values, due to discretization errors.

property si_dimension

Dictionary containing the SI unit dimensions in OpenPMD format.

property si_unit_conversion

Numeric value of the conversion from MALA (ASE) units to SI.

Needed for OpenPMD interface.