density

Electronic density calculation class.

class Density(params: Parameters)[source]

Bases: Target

Postprocessing / parsing functions for the electronic density.

Parameters:

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

static backconvert_units(array, out_units)[source]

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

MALA units for the density means 1/A^3.

Parameters:

  • array (numpy.array) – Data in 1/A^3.

  • out_units (string) –

    Desired units of output array. Currently, supported are:

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

    • 1/Bohr^3

Returns:

converted_array – Data in out_units.

Return type:

numpy.array

static convert_units(array, in_units='1/A^3')[source]

Convert the units of an array into the MALA units.

MALA units for the density means 1/A^3.

Parameters:

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

  • in_units (string) –

    Units of array. Currently, supported are:

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

    • 1/Bohr^3

Returns:

converted_array – Data in 1/A^3.

Return type:

numpy.array

classmethod from_cube_file(params, path, units='1/Bohr^3')[source]

Create a Density calculator from a cube file.

Parameters:

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

  • path (string) – Name of the cube file.

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

Returns:

dens_object – Density object created from LDOS object.

Return type:

mala.targets.density.Density

classmethod from_ldos_calculator(ldos_object)[source]

Create a Density calculator 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:

dens_object – Density object created from LDOS object.

Return type:

mala.targets.density.Density

classmethod from_numpy_array(params, array, units='1/A^3')[source]

Create a Density calculator from a numpy array in memory.

By using this function rather then setting the density 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 density is saved in.

Returns:

dens_object – Density calculator object.

Return type:

mala.targets.density.Density

classmethod from_numpy_file(params, path, units='1/A^3')[source]

Create a Density 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 density is saved in.

Returns:

dens_object – Density calculator object.

Return type:

mala.targets.density.Density

classmethod from_openpmd_file(params, path)[source]

Create an Density calculator from an OpenPMD file.

Supports all OpenPMD supported file endings.

Parameters:
Returns:

density_calculator – Density calculator object.

Return type:

mala.targets.density.Density

classmethod from_xsf_file(params, path, units='1/A^3')[source]

Create a Density calculator from a xsf file.

Parameters:

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

  • path (string) – Name of the xsf file.

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

Returns:

dens_object – Density object created from LDOS object.

Return type:

mala.targets.density.Density

get_atomic_forces(density_data=None, create_file=True, atoms_Angstrom=None, qe_input_data=None, qe_pseudopotentials=None)[source]

Calculate the atomic forces.

This function uses an interface to QE. The atomic forces are calculated via the Hellman-Feynman theorem, although only the local contributions are calculated. The non-local contributions, as well as the SCF correction (so anything wavefunction dependent) are ignored. Therefore, this function is best used for data that was created using local pseudopotentials.

Parameters:

  • density_data (numpy.array) – Density data on a grid. If None, then the cached density will be used for the calculation.

  • create_file (bool) – If False, the last mala.pw.scf.in file will be used as input for Quantum Espresso. If True (recommended), MALA will create this file according to calculation parameters.

  • 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.

Returns:

atomic_forces – An array of the form (natoms, 3), containing the atomic forces in eV/Ang.

Return type:

numpy.ndarray

get_density(density_data=None, convert_to_threedimensional=False, grid_dimensions=None)[source]

Get the electronic density, based on density data.

This function only does reshaping, no calculations.

Parameters:

  • density_data (numpy.array) – Electronic density data, this array will be returned unchanged depending on the other parameters. If None, then the cached density will be used for the calculation.

  • convert_to_threedimensional (bool) – If True, then a density saved as a 1D array will be converted to a 3D array (gridsize -> gridx * gridy * gridz)

  • grid_dimensions (list) – Provide a list of dimensions to be used in the transformation 1D -> 3D. If None, MALA will attempt to use the values read with Target.read_additional_read_additional_calculation_data . If that cannot be done, this function will raise an exception.

Returns:

density_data – Electronic density data in the desired shape.

Return type:

numpy.array

get_energy_contributions(density_data=None, create_file=True, atoms_Angstrom=None, qe_input_data=None, qe_pseudopotentials=None)[source]

Extract density based energy contributions from Quantum Espresso.

Done via a Fortran module accesible through python using f2py. Returns: e_rho_times_v_hxc, e_hartree, e_xc, e_ewald

Parameters:

  • density_data (numpy.array) – Density data on a grid. If None, then the cached density will be used for the calculation.

  • create_file (bool) – If False, the last mala.pw.scf.in file will be used as input for Quantum Espresso. If True (recommended), MALA will create this file according to calculation parameters.

  • 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.

Returns:

energies –

A dict containing the following entries:

  • \(n\,V_\mathrm{xc}\)

  • \(E_\mathrm{H}\)

  • \(E_\mathrm{xc}\)

  • \(E_\mathrm{Ewald}\)

Return type:

dict

get_number_of_electrons(density_data=None, voxel=None, integration_method='summation')[source]

Calculate the number of electrons from given density data.

Parameters:

density_data (numpy.array) – Electronic density on the given grid. Has to either be of the form gridpoints or (gridx, gridy, gridz). If None, then the cached density 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.

integration_methodstr

Integration method used to integrate 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)

static get_scaled_positions_for_qe(atoms)[source]

Get the positions correctly scaled for QE.

QE (for ibrav=0) scales a little bit different then ASE would. ASE uses all provided cell parameters, while QE simply sets the first entry in the cell parameter matrix as reference and divides all positions by this value.

Parameters:

atoms (ase.Atoms) – The atom objects for which the scaled positions should be calculated.

Returns:

scaled_positions – The scaled positions.

Return type:

numpy.array

get_target()[source]

Get the target quantity.

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

Returns:

density – Electronic charge density as a volumetric array. May be 4D or 2D depending on workflow.

Return type:

numpy.ndarray

invalidate_target()[source]

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/A^3')[source]

Read the density data from a numpy array.

Parameters:

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

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

read_from_cube(path, units='1/Bohr^3', **kwargs)[source]

Read the density data from a cube file.

Parameters:

  • path (string) – Name of the cube file.

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

read_from_xsf(path, units='1/A^3', **kwargs)[source]

Read the density data from an xsf file.

Parameters:

  • path (string) – Name of the xsf file.

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

uncache_properties()[source]

Uncache all cached properties of this calculator.

write_to_cube(file_name, density_data=None, atoms=None, grid_dimensions=None)[source]

Write the density data in a cube file.

Parameters:

  • file_name (string) – Name of the file.

  • density_data (numpy.ndarray) – 1D or 3D array of the density.

  • atoms (ase.Atoms) – Atoms to be written to the file alongside the density data. If None, and the target object has an atoms object, this will be used. Ignored, unless density_data is provided.

  • grid_dimensions (list) – Grid dimensions. Ignored, unless density_data is provided.

write_to_openpmd_file(path, array=None, additional_attributes={}, internal_iteration_number=0)[source]

Write data to a numpy file.

Parameters:

  • path (string) – File to save into. If no file ending is given, .h5 is assumed.

  • array (numpy.ndarray) – Target data to save. If None, the data stored in the calculator will be used.

  • additional_attributes (dict) – Dict containing additional attributes to be saved.

  • internal_iteration_number (int) – Internal OpenPMD iteration number. Ideally, this number should match any number present in the file name, if this data is part of a larger data set.

property data_name

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

property density

Electronic density.

property feature_size

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

property number_of_electrons

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

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.

te_mutex = False
property total_energy_contributions

All density based contributions to the total energy.

Calculated via the cached density.