ldos

LDOS calculation class.

class LDOS(params: Parameters)

Bases: Target

Postprocessing / parsing functions for the local density of states.

Parameters:

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

static backconvert_units(array, out_units)

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

MALA units for the LDOS means 1/(eV*A^3).

Parameters:

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

• out_units (string) –

  Desired units of output array. Currently supported are:

  • 1/(eV*A^3) (no conversion, MALA unit)

  • 1/(eV*Bohr^3)

  • 1/(Ry*Bohr^3)

Returns:

converted_array – Data in out_units.

Return type:

numpy.array

static convert_units(array, in_units='1/(eV*A^3)')

Convert the units of an array into the MALA units.

MALA units for the LDOS 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*A^3) (no conversion, MALA unit)

  • 1/(eV*Bohr^3)

  • 1/(Ry*Bohr^3)

Returns:

converted_array – Data in 1/(eV*A^3).

Return type:

numpy.array

classmethod from_cube_file(params, path_name_scheme, units='1/(Ry*Bohr^3)', use_memmap=None)

Create an LDOS calculator from multiple cube files.

The files have to be located in the same directory.

Parameters:

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

• path_name_scheme (string) – Naming scheme for the LDOS .cube files. Every asterisk will be replaced with an appropriate number for the LDOS files. Before the file name, please make sure to include the proper file path.

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

• use_memmap (string) – If not None, a memory mapped file with this name will be used to gather the LDOS. If run in MPI parallel mode, such a file MUST be provided.

classmethod from_numpy_array(params, array, units='1/(eV*A^3)')

Create an LDOS calculator from a numpy array in memory.

By using this function rather then setting the local_density_of_states object directly, proper unit coversion is ensured.

Parameters:

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

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

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

Returns:

ldos_calculator – LDOS calculator object.

Return type:

mala.targets.ldos.LDOS

classmethod from_numpy_file(params, path, units='1/(eV*A^3)')

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

Parameters:

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

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

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

Returns:

ldos_calculator – LDOS calculator object.

Return type:

mala.targets.ldos.LDOS

classmethod from_openpmd_file(params, path)

Create an LDOS calculator from an OpenPMD file.

Supports all OpenPMD supported file endings.

Parameters:

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

• path (string) – Path to OpenPMD file.

Returns:

ldos_calculator – LDOS calculator object.

Return type:

mala.targets.ldos.LDOS

classmethod from_xsf_file(params, path_name_scheme, units='1/(eV*A^3)', use_memmap=None)

Create an LDOS calculator from multiple xsf files.

The files have to be located in the same directory.

Parameters:

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

• path_name_scheme (string) – Naming scheme for the LDOS .xsf files. Every asterisk will be replaced with an appropriate number for the LDOS files. Before the file name, please make sure to include the proper file path.

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

• use_memmap (string) – If not None, a memory mapped file with this name will be used to gather the LDOS. If run in MPI parallel mode, such a file MUST be provided.

get_atomic_forces(ldos_data, dE_dd, used_data_handler, snapshot_number=0)

Get the atomic forces, currently work in progress.

Will eventually give \(\frac{dE}{d \underline{\boldsymbol{R}}}\). Will currently only give \(\frac{dd}{dB}\).

Parameters:

• ldos_data (torch.Tensor) – Scaled (!) torch tensor holding the LDOS data for the snapshot for which the atomic force should be calculated.

• dE_dd (np.array) – (WIP) Derivative of the total energy w.r.t the LDOS. Later on, this will be evaluated within this subroutine. For now it is provided from outside.

• used_data_handler (mala.data.data_handler.DataHandler) – DataHandler that was used to predict the LDOS for which the atomic forces are supposed to be calculated.

• snapshot_number – Snapshot number (number within the data handler) for which this LDOS prediction was performed. Always 0 in the inference case.

Returns:

dd_dB – (WIP) Returns the scaled (!) derivative of the LDOS w.r.t to the descriptors.

Return type:

torch.tensor

get_band_energy(ldos_data=None, fermi_energy=None, temperature=None, voxel=None, grid_integration_method='summation', energy_integration_method='analytical')

Calculate the band energy from given LDOS data.

Parameters:

• ldos_data (numpy.array) – LDOS data, either as [gridsize, energygrid] or [gridx,gridy,gridz,energygrid]. If None, the cached LDOS will be used for the calculation.

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

• temperature (float) – Temperature in K.

• grid_integration_method (str) –

  Integration method used to integrate the LDOS on the grid. Currently supported:

  • ”trapezoid” for trapezoid method (only for cubic grids).

  • ”simpson” for Simpson method (only for cubic grids).

  • ”summation” for summation and scaling of the values (recommended)

• energy_integration_method (string) –

  Integration method to integrate the DOS. Currently supported:

  • ”trapezoid” for trapezoid method

  • ”simpson” for Simpson method.

  • ”analytical” for analytical integration. (recommended)

• voxel (ase.cell.Cell) – Voxel to be used for grid intergation.

Returns:

band_energy – Band energy in eV.

Return type:

float

get_density(ldos_data=None, fermi_energy=None, temperature=None, conserve_dimensions=False, integration_method='analytical', gather_density=False)

Calculate the density from given LDOS data.

Parameters:

conserve_dimensions (bool) – If True, the density is returned in the same dimensions as the LDOS was entered. If False, the density is always given as [gridsize, 1]. If None, the cached LDOS will be used for the calculation.

fermi_energyfloat

Fermi energy level in eV.

temperaturefloat

Temperature in K.

integration_methodstring

Integration method to be used. Currently supported:

• “trapezoid” for trapezoid method

• “simpson” for Simpson method.

• “analytical” for analytical integration. Recommended.

ldos_datanumpy.array

LDOS data, either as [gridsize, energygrid] or [gridx,gridy,gridz,energygrid].

integration_methodstring

Integration method to integrate LDOS on energygrid. Currently supported:

• “trapezoid” for trapezoid method

• “simpson” for Simpson method.

• “analytical” for analytical integration. Recommended.

gather_densitybool

Only important if MPI is used. If True, the density will be gathered on rank 0. Helpful when using multiple CPUs for descriptor calculations and only one for network pass.

Returns:

density_data – Density data, dimensions depend on conserve_dimensions and LDOS dimensions.

Return type:

numpy.array

get_density_of_states(ldos_data=None, voxel=None, integration_method='summation', gather_dos=True)

Calculate the density of states from given LDOS data.

Parameters:

ldos_data (numpy.array) – LDOS data, either as [gridsize, energygrid] or [gridx,gridy,gridz,energygrid]. If None, the cached LDOS will be used for the calculation.

voxelase.cell.Cell

Voxel to be used for grid intergation. Needs to reflect the symmetry of the simulation cell. In Bohr.

integration_methodstr

Integration method used to integrate LDOS on the grid. Currently supported:

• “trapezoid” for trapezoid method (only for cubic grids).

• “simpson” for Simpson method (only for cubic grids).

• “summation” for summation and scaling of the values (recommended)

gather_dosbool

Only important if MPI is used. If True, the DOS will be are gathered on rank 0. Helpful when using multiple CPUs for descriptor calculations and only one for network pass.

Returns:

dos_values – The DOS.

Return type:

np.array

get_energy_grid()

Get energy grid.

Returns:

e_grid – Energy grid on which the LDOS is defined.

Return type:

numpy.array

get_entropy_contribution(ldos_data=None, fermi_energy=None, temperature=None, voxel=None, grid_integration_method='summation', energy_integration_method='analytical')

Calculate the entropy contribution from given LDOS data.

Parameters:

• ldos_data (numpy.array) – LDOS data, either as [gridsize, energygrid] or [gridx,gridy,gridz,energygrid]. If None, the cached LDOS will be used for the calculation.

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

• temperature (float) – Temperature in K.

• grid_integration_method (str) –

  Integration method used to integrate the LDOS on the grid. Currently supported:

  • ”trapezoid” for trapezoid method (only for cubic grids).

  • ”simpson” for Simpson method (only for cubic grids).

  • ”summation” for summation and scaling of the values (recommended)

• energy_integration_method (string) –

  Integration method to integrate the DOS. Currently supported:

  • ”trapezoid” for trapezoid method

  • ”simpson” for Simpson method.

  • ”analytical” for analytical integration. (recommended)

• voxel (ase.cell.Cell) – Voxel to be used for grid intergation.

Returns:

band_energy – Band energy in eV.

Return type:

float

get_number_of_electrons(ldos_data=None, voxel=None, fermi_energy=None, temperature=None, grid_integration_method='summation', energy_integration_method='analytical')

Calculate the number of electrons from given LDOS data.

Parameters:

• ldos_data (numpy.array) – LDOS data, either as [gridsize, energygrid] or [gridx,gridy,gridz,energygrid]. If None, the cached LDOS will be used for the calculation.

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

• temperature (float) – Temperature in K.

• grid_integration_method (str) –

  Integration method used to integrate the LDOS on the grid. Currently supported:

  • ”trapezoid” for trapezoid method (only for cubic grids).

  • ”simpson” for Simpson method (only for cubic grids).

  • ”summation” for summation and scaling of the values (recommended)

• energy_integration_method (string) –

  Integration method to integrate the DOS. Currently supported:

  • ”trapz” for trapezoid method

  • ”simpson” for Simpson method.

  • ”analytical” for analytical integration. (recommended)

• voxel (ase.cell.Cell) – Voxel to be used for grid intergation.

Returns:

number_of_electrons – Number of electrons.

Return type:

float

get_self_consistent_fermi_energy(ldos_data=None, voxel=None, temperature=None, grid_integration_method='summation', energy_integration_method='analytical')

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:

• ldos_data (numpy.array) – LDOS data, either as [gridsize, energygrid] or [gridx,gridy,gridz,energygrid]. If None, the cached LDOS will be used for the calculation.

• temperature (float) – Temperature in K.

• grid_integration_method (str) –

  Integration method used to integrate the LDOS on the grid. Currently supported:

  • ”trapezoid” for trapezoid method (only for cubic grids).

  • ”simpson” for Simpson method (only for cubic grids).

  • ”summation” for summation and scaling of the values (recommended)

• energy_integration_method (string) –

  Integration method to integrate the DOS. Currently supported:

  • ”trapezoid” for trapezoid method

  • ”simpson” for Simpson method.

  • ”analytical” for analytical integration. (recommended)

• voxel (ase.cell.Cell) – Voxel to be used for grid intergation. Needs to reflect the symmetry of the simulation cell. In Bohr.

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:

local_density_of_states – Electronic local density of states as a volumetric array. May be 4D- or 2D depending on workflow.

Return type:

numpy.ndarray

get_total_energy(ldos_data=None, dos_data=None, density_data=None, fermi_energy=None, temperature=None, voxel=None, grid_integration_method='summation', energy_integration_method='analytical', atoms_Angstrom=None, qe_input_data=None, qe_pseudopotentials=None, create_qe_file=True, return_energy_contributions=False)

Calculate the total energy from LDOS or given DOS + density data.

If neither LDOS nor DOS+Density data is provided, the cached LDOS will be attempted to be used for the calculation.

Parameters:

• ldos_data (numpy.array) – LDOS data, either as [gridsize, energygrid] or [gridx,gridy,gridz,energygrid]. If None, dos_data and density_data cannot be None.

• dos_data (numpy.array) – DOS data, as [energygrid].

• density_data (numpy.array) – Density data, either as [gridsize] or [gridx,gridy,gridz].

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

• temperature (float) – Temperature in K.

• voxel (ase.cell.Cell) – Voxel to be used for grid intergation. Needs to reflect the symmetry of the simulation cell. In Bohr.

• grid_integration_method (str) –

  Integration method used to integrate the density on the grid. Currently supported:

  • ”trapezoid” for trapezoid method (only for cubic grids).

  • ”simpson” for Simpson method (only for cubic grids).

  • ”summation” for summation and scaling of the values (recommended)

• energy_integration_method (string) –

  Integration method to integrate the DOS. Currently supported:

  • ”trapezoid” for trapezoid method

  • ”simpson” for Simpson method.

  • ”analytical” for analytical integration. (recommended)

• atoms_Angstrom (ase.Atoms) – ASE atoms object for the current system. If None, MALA will create one.

• qe_input_data (dict) – Quantum Espresso parameters dictionary for the ASE<->QE interface. If None (recommended), MALA will create one.

• qe_pseudopotentials (dict) – Quantum Espresso pseudopotential dictionaty for the ASE<->QE interface. If None (recommended), MALA will create one.

• create_qe_file (bool) – If True, a QE input file will be created by MALA during the calculation. This is the default, however there may be cases in which it makes sense for the user to provide a custom one.

• return_energy_contributions (bool) – If True, a dictionary of energy contributions will be provided alongside the total energy. The default is False.

Returns:

total_energy – Total energy of the system (in eV).

Return type:

float

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*A^3)')

Read the LDOS data from a numpy array.

Parameters:

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

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

read_from_cube(path_scheme, units='1/(Ry*Bohr^3)', use_memmap=None, **kwargs)

Read the LDOS data from multiple cube files.

The files have to be located in the same directory.

Parameters:

• path_scheme (string) – Naming scheme for the LDOS .cube files. Every asterisk will be replaced with an appropriate number for the LDOS files. Before the file name, please make sure to include the proper file path.

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

• use_memmap (string) – If not None, a memory mapped file with this name will be used to gather the LDOS. Only has an effect in MPI parallel mode. Usage will reduce RAM footprint while SIGNIFICANTLY impacting disk usage and

read_from_xsf(path_scheme, units='1/(eV*A^3)', use_memmap=None, **kwargs)

Read the LDOS data from multiple .xsf files.

The files have to be located in the same directory. .xsf files are used by XCrysDen.

Parameters:

• path_scheme (string) – Naming scheme for the LDOS .xsf files. Every asterisk will be replaced with an appropriate number for the LDOS files. Before the file name, please make sure to include the proper file path.

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

• use_memmap (string) – If not None, a memory mapped file with this name will be used to gather the LDOS. Only has an effect in MPI parallel mode. Usage will reduce RAM footprint while SIGNIFICANTLY impacting disk usage and

uncache_properties()

Uncache all cached properties of this calculator.

property band_energy

Band energy of the system, calculated via cached LDOS.

property data_name

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

property density

Electronic density as calculated by the cached LDOS.

property density_of_states

DOS as calculated by the cached LDOS.

property energy_grid

Energy grid on which the LDOS is expressed.

property entropy_contribution

Band energy of the system, calculated via cached LDOS.

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 LDOS

property local_density_of_states

Local density of states as 1D or 3D array.

property number_of_electrons

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

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.

property total_energy

Total energy of the system, calculated via cached LDOS.