dfttoolkit package

Submodules

dfttoolkit.base_parser module

class dfttoolkit.base_parser.BaseParser(supported_files, **kwargs)

Bases: object

Generic routines for all parsers.

…

file_paths

the paths to the parsed files

Type:

dict

file_contents

the contents of parsed files

Type:

dict

property lines: List[str]

property path: str

dfttoolkit.benchmarking module

class dfttoolkit.benchmarking.BenchmarkAims(benchmark_dirs: List[str])

Bases: AimsOutput

Calculate benchmarking metrics for FHI-aims calculations.

…

benchmark_dirs

The paths to the aims.out files.

Type:

List[str]

get_timings_per_benchmark() → List[ndarray[Any, dtype[float64]]]

Calculate the average time taken per SCF iteration for each benchmark.

Returns:

The average time taken per SCF iteration for each benchmark.

Return type:

List[np.ndarray]

dfttoolkit.custom_ase module

class dfttoolkit.custom_ase.CustomAims(*args, **kwargs)

Bases: Aims

A custom FHI-aims calculator which addresses bugs in the default ASE implementation.

Please refer to the ASE calculator for the documentation: https://wiki.fysik.dtu.dk/ase/ase/calculators/FHI-aims.html#module-ase.calculators.aims

write_input(atoms, properties=None, system_changes=None, ghosts=None, geo_constrain=None, scaled=False, velocities=None)

dfttoolkit.friction_tensor module

dfttoolkit.geometry module

class dfttoolkit.geometry.AimsGeometry(filename: str | None = None)

Bases: Geometry

get_text(is_fractional=None)

If symmetry_params are to be used, the coordinates need to be fractional. So, if symmetry_params are found, is_fractional is overridden to true.

parse(text)

Parses text from AIMS geometry file and sets all necessary parameters in AimsGeometry.

Parameters:

text (str) – line wise text file of AIMS geometry.

class dfttoolkit.geometry.Geometry(filename: str | None = None)

Bases: object

This class represents a geometry file for (in principle) any DFT code. In practice it has only been fully implemented for FHI-aims geometry.in files.

add_atoms(cartesian_coords, species, constrain_relax=None, initial_moment=None, initial_charge=None, external_force=None, calculate_friction=None) → None

Add additional atoms to the current geometry file.

Parameters:

• cartesion_coords (List of numpy arrays of shape [nx3]) – coordinates of new atoms

• species (list of strings) – element symbol for each atom

• constrain_relax (list of lists of bools (optional)) – [bool,bool,bool] (for [x,y,z] axis) for all atoms that should be constrained during a geometry relaxation

• Retruns

• -------

• None.

add_geometry(geometry) → None

Adds full geometry to initial geometry.

Parameters:

geometry (Instance of geometry) – New geometry to be added to current geometry.

Return type:

None.

add_multipoles(multipoles: List[float] | List[list]) → None

Adds multipoles to the the geometry.

Parameters:

multipoles (Union[List[float], List[list]]) – Each multipole is defined as a list -> [x, y, z, order, charge] With x,y,z cartesian coordinates order: 0 for monopoles, 1 for dipoles charge: charge

Return type:

None

add_top_comment(comment_string: str) → None

Adds comments that are saved at the top of the geometry file.

Parameters:

comment_string (str) – Comment string.

Return type:

None.

align_cartiesian_axis_to_vector(vector, axis_index)

Aligns a lattice vector and the atomic coordiantes to a given axis.

Parameters:

• vector (array) – vector for alignment

• axis_index (int) – index of the axis that should be aligned

align_into_xy_plane(atom_indices)

Rotates a planar molecule (defined by 3 atom indices) into the XY plane. Double check results, use with caution

Parameters:

atom_indices – Indices of atoms that should be aligned.

Return type:

None.

align_lattice_vector_to_vector(vector, lattice_vector_index)

Aligns a lattice vector and the atomic coordiantes to a given axis.

Parameters:

• vector (array) – vector for alignment

• lattice_vector_index (int) – index of the lattice vector that should be aligned

Return type:

None

align_main_axis_along_xyz() → None

Align coordinates of rodlike molecules along specified axis

align_vector_to_vector(vector: ndarray[Any, dtype[float64]], vector_to_align: ndarray[Any, dtype[float64]])

Aligns a vector and the atomic coordiantes to a given vector.

Parameters:

• vector (npt.NDArray[np.float64]) – vector for alignment

• vector_to_align (npt.NDArray[np.float64]) – index of the lattice vector that should be aligned

Return type:

None

align_with_view_direction(view_direction: ndarray[Any, dtype[float64]]) → None

align_with_z_vector(new_z_vec: ndarray[Any, dtype[float64]]) → None

Transforms the coordinate system of the geometry file to a new z-vector calculates rotation martrix for coordinate transformation to new z-vector and uses it to transform coordinates of geometry object

Parameters:

new_z_vec (npt.NDArray[np.float64]) – The vector to align with the z-axis.

Return type:

None

average_with(other_geometries) → None

Average self.coords with those of other_geometries and apply on self ATTENTION: this can change bond lengths etc.!Ok n

Parameters:

• other_geometries (List of Geometrys ... might be nice to accept list of)

• too (coords)

Return type:

None

center_coordinates(ignore_center_attribute: bool = False, dimensions=array([0, 1, 2]))

Shift the coordinates of a geometry such that the “center of mass” or specified center lies at (0,0,0)

Parameters:

• ignore_center_attribute (bool) – Switch usage of center attribute off/on. The default is False.

• dimensions (np.array) – Dimensions that should be cnetered. The default is False [0, 1, 2].

Return type:

None.

check_symmetry(tolerance: float, R: ndarray[Any, dtype[float64]], t: ndarray[Any, dtype[float64]] = array([0., 0., 0.]), return_symmetrical: bool = False)

Returns True if the geometry is symmetric with respect to the transformation, and False if it is not. If the geometry is periodic, transformation can be tuple (rotation, translation) or np.array (only rotation), otherwise it can only be np.array

Parameters:

• float (tolerance ;) – Tolerance for checking symmetry.

• R (npt.NDArray[np.float64]) – Symmetry transformation agaist which geometry should be checked.

• t (npt.NDArray[np.float64]) – Translation vector

• return_symmetrical (bool) – Return the corresponding transformed geometry together with the result.

Returns:

• is_symmetric (bool)

• symm_geometry (Geometry)

• or

• is_symmetric (bool)

crop(xlim=(-inf, inf), ylim=(-inf, inf), zlim=(-inf, inf), auto_margin: bool = False) → None

Removes all atoms that are outside specified bounds.

Parameters:

• xlim (tuple, optional) – Limit in x-direction. The default is (-np.inf, np.inf).

• ylim (tuple, optional) – Limit in y-direction. The default is (-np.inf, np.inf).

• zlim (tuple, optional) – Limit in z-direction. The default is (-np.inf, np.inf).

• auto_margin (TYPE, optional) – If auto_margin == True then an additional margin of the maximum covalent radius is added to all borders. The default is False.

Return type:

None.

crop_inverse(xlim=(-inf, inf), ylim=(-inf, inf), zlim=(-inf, inf), auto_margin=False) → None

Removes all atoms that are inside specified bounds.

Parameters:

• xlim (tuple, optional) – Limit in x-direction. The default is (-np.inf, np.inf).

• ylim (tuple, optional) – Limit in y-direction. The default is (-np.inf, np.inf).

• zlim (tuple, optional) – Limit in z-direction. The default is (-np.inf, np.inf).

• auto_margin (TYPE, optional) – If auto_margin == True then an additional margin of the maximum covalent radius is added to all borders. The default is False.

Return type:

None.

crop_to_unit_cell(lattice=None, frac_coord_factors=[0, 1])

Removes all atoms that are outside the given unit cell. Similar to self.crop() but allows for arbitrary unit cells

Parameters:

• lattice (array like, optional) – Lattice vectors. The default is None.

• frac_coord_factors (list, optional) – The default is [0, 1].

Return type:

None.

displace_atoms(displacement_strength: float, displacement_indices: ndarray[Any, dtype[int64]]) → None

Displaces atoms randomly.

Parameters:

• displacement_strength (float) – Scaling factor for the strenght of the dispacements.

• displacement_indices (npt.NDArray[np.int64]) – Indices where atoms should be dispaced.

Return type:

None

free_all_calculate_friction() → None

Set calculate electronic friction to false on all atoms.

Return type:

None

free_all_constraints() → None

Frees all constraints.

Return type:

None

free_all_external_forces() → None

Set calculate electronic friction to false on all atoms.

Return type:

None

free_homogeneous_field()

get_adsorbate_indices(primitive_substrate=None) → ndarray[Any, dtype[int64]]

This method returns the indices of all atoms that are NOT part of the substrate. In a classical organic monolayer on a metal substrate these are simply all molecules. But the substrate can also be organic in which case it can’t be picked by being a metal. And there might be multiple adsorbate layers in which case only the molecules of the highest layer shall be counted as adsorbates.

Returns:

indices of all adsorbate atoms

Return type:

npt.NDArray[np.int64]

get_adsorbates(primitive_substrate=None)

get_area() → float64

Returns the area of the surface described by lattice_vectors 0 and 1 of the geometry, assuming that the lattice_vector 2 is orthogonal to both.

Returns:

area – Area of the unit cell.

Return type:

float

get_area_in_atom_numbers(substrate_indices: ndarray[Any, dtype[float64]] | None = None, substrate=None) → float

Returns the area of the unit cell in terms of substrate atoms in the topmost substrate layer. The substrate is determined by default by the function self.getSubstrate(). For avoiding a faulty substrate determination it can be either given through indices or through the substrate geometry itself

Parameters:

• substrate_indices (Union[np.array, None], optional) – List of indices of substrate atoms. The default is None.

• substrate (TYPE, optional) – Geometry of substrate. The default is None.

Returns:

Area of the unit cell in units of the area of the substrate.

Return type:

float

get_as_ase() → None

Convert geometry file to ASE object.

Return type:

None.

get_atom_layers_indices(threshold: float = 0.01) → dict

Returns a dict of the following form.

Parameters:

threshold (float, optional) – Treshold within which atoms are considered to be in the same layer. The default is 1e-2.

Returns:

layers – {<Element symbol>: {height: [indices of atoms of element at height]}}.

Return type:

dict

get_atom_layers_indices_by_height(threshold: float = 0.01) → dict

Similarly to get_atom_layers_indices this function returns a dict continaing info about height and the indices of atoms at that height.

Parameters:

threshold (float, optional) – reshold within which atoms are considered to be in the same layer. The default is 1e-2.

Returns:

layers_by_height – {height: [indices of atoms at that height]}.

Return type:

dict

get_atomic_masses() → ndarray[Any, dtype[float64]]

Determines the atomic mass for all atoms.

Returns:

masses – List of atomic masses for all atoms in the same order as the atoms.

Return type:

np.array

get_atomic_numbers_of_atoms() → ndarray[Any, dtype[float64]]

Get the atomic numbers of all atoms in the geometry file

get_atoms_by_indices(atom_indices: ndarray[Any, dtype[int64]]) → Geometry

Return a geometry instance with the atoms listed in atom_indices

Parameters:

atom_indices (Union[int, np.array]) – List of integers, indices of those atoms which should be copied to new geometry

Returns:

new_geom

Return type:

Geometry

get_atoms_by_species(species) → Geometry

get new geometry file with specific atom species

get_bond_lengths(bond_factor: float = 1.5) → ndarray[Any, dtype[float64]]

Parameters:

atom-distance (Parameter for bond detection based on) – DESCRIPTION. The default is 1.5.

Returns:

bond_lengths – List of bond lengths for neighbouring atoms.

Return type:

npt.NDArray[np.float64]

get_center_of_mass() → ndarray[Any, dtype[float64]]

Mind the difference to self.get_geometric_center

Returns:

center_of_mass – The 3D-coordinate of the center of mass

Return type:

npt.NDArray[np.float64]

get_closest_atoms(indices, species=None, n_closest=1)

Get the indices of the closest atom(s) for the given index or list of indices

Parameters:

• index (int or iterable) – atoms for which the closest indices are to be found

• species (None or list of species identifiers) – species to consider for closest atoms. This allows to get only the closest atoms of the same or another species

• n_closest (int) – number of closest atoms to return

Returns:

closest_atoms_list – closest atoms for each entry in index

Return type:

list or list of lists

get_colliding_groups(distance_threshold=0.01, check_3D=False)

Remove atoms that are too close too each other from the geometry file. This approach is useful if one maps back atoms into a different cell and then needs to get rid of overlapping atoms

Parameters:

distance_threshold (float) – maximum distance between atoms below which they are counted as duplicates

get_constrained_atoms() → ndarray[Any, dtype[int64]]

Returns indice of constrained atoms.

Returns:

inds – Indice of constrained atoms.

Return type:

npt.NDArray[np.int64]

get_cropped_geometry(xlim=(-inf, inf), ylim=(-inf, inf), zlim=(-inf, inf), auto_margin=False)

Returns a copy of the object to which self.crop has been applied

get_cropping_indices(xlim=(-inf, inf), ylim=(-inf, inf), zlim=(-inf, inf), auto_margin=False, inverse=False) → ndarray[Any, dtype[int64]]

Gets indices of all atoms that are outside specified bounds. If auto_margin == True then an additional margin of the maximum covalent radius is added to all borders :param inverse : if True, gets indices of all atoms INSIDE specified bounds

get_displaced_atoms(displacement_strength: float, displace_only_unconstrained: bool = True)

Returns a copy of the geometry, where the atoms have been displaced randomly.

Parameters:

• displacement_strength (float) – Scaling factor for the strenght of the dispacements.

• displace_only_unconstrained (bool) – Indices where atoms should be dispaced. The default is True.

Return type:

geometry.

get_distance_between_all_atoms() → ndarray[Any, dtype[float64]]

Get the distance between all atoms in the current Geometry object. Gives an symmetric array where distances between atom i and j are denoted in the array elements (ij) and (ji).

get_distance_between_two_atoms(atom_indices: list) → float64

Get the distance between two atoms in the current Geometry object.

get_distance_to_equivalent_atoms(other_geometry) → float64

Calculate the maximum distance that atoms of geom would have to be moved, to coincide with the atoms of self.

get_fractional_coords(lattice_vectors=None)

get_fractional_lattice_vectors(lattice_vectors=None)

Calculate the fractional representation of lattice vectors of the geometry file in another basis. Useful to calculate epitaxy matrices

get_from_ase_atoms_object(atoms) → None

Reads an ASE.Atoms object. Taken from ase.io.aims and adapted. Only basic features are implemented.

Parameters:

atoms (ASE atoms object) – Atoms object from ASE that should be converted into geometry.

Raises:

RuntimeError – If atoms object is erroneous.

Return type:

None.

get_geometric_center(ignore_center_attribute=False, indices=None) → ndarray[Any, dtype[float64]]

Returns the center of the geometry. If the attribute center is set, it is used as the definition for the center of the geometry.

Parameters:

• ignore_center_attribute (Bool) – If True, the attribute self.center is used Otherwise, the function returns the geometric center of the structure, i.e. the average over the position of all atoms.

• indices (iterable of indices or None) – indices of all atoms to consider when calculating the center. Useful to calculate centers of adsorbates only if None, all atoms are used

Returns:

center – Center of the geometry

Return type:

npt.NDArray[np.float64]

get_homogeneous_field()

Field is a numpy array (Ex, Ey, Ez) with the Field in V/A

get_indices_of_all_atoms(species=None)

get_indices_of_metal() → ndarray[Any, dtype[int64]]

Gets indices of all atoms with atomic number > 18 and atomic numbers 3,4,11,12,13,14

Returns:

metal_atoms – Inidices of metallic atoms.

Return type:

npt.NDArray[np.int64]

get_indices_of_molecules(substrate_species=None) → ndarray[Any, dtype[int64]]

Fetches the indices of the substrate atoms, but it defaults to just returning all non-metal atom’s indices!

If substrate_species is given indices of all atoms that are not of the substrate species are returned.

get_indices_of_species(species) → ndarray[Any, dtype[int64]]

Returns all indices of atoms the are of species defined in the input. species can be a string of a list

get_instance_of_other_type(geometry_type)

get_is_periodic() → bool

Checks if the geometry is periodic.

Returns:

Ture if geometry is periodic.

Return type:

bool

get_largest_atom_distance(dims_to_consider=(0, 1, 2)) → float

Find largest distance between atoms in geometry. #search tags; molecule length, maximum size

Parameters:

dims_to_consider (list) – Dimensions along which largest distance should be calculated.

Returns:

geometry_size – Largest distance between two atoms in the unit cell.

Return type:

float

get_layers(layer_indices: list, threshold: float = 0.01)

Get substrate layer by indices. The substrate is determined by default by the function self.get_substrate. For avoiding a faulty substrate determination it can be either given through indices or through the substrate geometry itself.

Parameters:

• layer_indices (list) – List of indices of layers that shall be returned.

• substrate_indices (Union[None, list], optional) – List of indices of substrate atoms. The default is None.

• substrate (Union[None, Geometry()], optional) – Geometry of substrate. The default is None.

• threshold (float, optional) – DESCRIPTION. The default is 1e-2.

• primitive_substrate (Geometry, optional) – DESCRIPTION. The default is None.

Returns:

geometry_of_layer – Geometry of layer.

Return type:

Geometry

get_list_of_neighbouring_atoms(bond_factor: float = 1.5) → dict

Get a dictionary of neighbouring atoms.

Parameters:

bond_factor (float, optional) – Multiply for covelent radius. If the distance between two atoms is smaller thand (r_0+r_1)*bond_factor, the atoms are considered neighbours. The default is 1.5.

Returns:

neighbouring_atoms – {(index_0, index_1) : [(element_0, element_1), atom distance]}.

Return type:

dict

get_main_axes(weights: str | ndarray[Any, dtype[float64]] = 'unity') → Tuple[ndarray[Any, dtype[float64]], ndarray[Any, dtype[float64]]]

Get main axes and eigenvalues of a molecule https://de.wikipedia.org/wiki/Tr%C3%A4gheitstensor

Parameters:

weights (Union[str, npt.NDArray[np.float64]] = "unity") – Specifies how the atoms are weighted. “unity”: all same weight “Z”: weighted by atomic number. The default is ‘unity’.

Returns:

• vals (npt.NDArray[np.float64]) – TODO DESCRIPTION.

• vecs (npt.NDArray[np.float64]) – TODO DESCRIPTION.

get_number_of_atom_layers(threshold: float = 0.01) → Tuple[dict, float]

Return the number of atom layers.

Parameters:

threshold (float, optional) – Threshold to determine the number of layers. The default is 1e-2.

Returns:

• dict – Number of layers per atom species.

• float – Total number of layers.

get_number_of_electrons() → float

Determines the number of electrons.

Returns:

Number of electrons.

Return type:

float

get_orientation_of_main_axis() → float

Get the orientation of the main axis relative to the x axis

This is transformed such that it always points in the upper half of cartesian space

Returns:

float

angle between main axis and x axis in degree

get_periodic_replica(replications: tuple, lattice: ndarray[Any, dtype[float64]] | None = None, explicit_replications: list | None = None)

Return a new geometry file that is a periodic replica of the original file. Repeats the geometry N-1 times in all given directions: (1,1,1) returns the original file

Parameters:

• types (TODO Fix)

• replications (tuple or list) – number of replications for each dimension

• lattice (numpy array of shape [3x3]) – super-lattice vectors to use for periodic replication if lattice is None (default) the lattice vectors from the current geometry file are used.

• explicit_replications (iterable of iterables) – a way to explicitly define which replicas should be made. example: [[-1, 0, 1], [0, 1, 2, 3], [0]] will repeat 3 times in x (centered) and 4 times in y (not centered)

Return type:

New geometry

get_primitive_slab(surface, threshold=1e-06)

Generates a primitive slab unit cell with the z-direction perpendicular to the surface.

Arguments:

surfacearray_like

miller indices, eg. (1,1,1)

thresholdfloat

numerical threshold for symmetry operations

Returns:

primitive_slab : Geometry

get_principal_moments_of_inertia() → ndarray[Any, dtype[float64]]

Calculates the eigenvalues of the moments of inertia matrix

Returns:

moments – principal moments of inertia in kg * m**2

Return type:

np.array, shape=(3,), dtype=np.float64

get_reassembled_molecule(threshold: float = 2.0)

get_reciprocal_lattice_vectors() → ndarray[Any, dtype[float64]]

Calculate the reciprocal lattice of the Geometry lattice_vectors in standard form For convention see en.wikipedia.org/wiki/Reciprocal_lattice

Returns:

recip_lattice – Row-wise reciprocal lattice vectors (3x3)

Return type:

npt.NDArray[np.float64]

get_scaled_copy(scaling_factor: float | List) → object

Returns a copy of the geometry, scaled by scaling_factor.

Both the coordinates of the atoms and the length of the lattice vectors are affected

Parameters:

scaling_factor (Union[float, Iterator]) – Scaling factor for the geometry. If float, the volume of the geometry will be scaled accordingly. If iterable, the length of the lattice vectors will be scaled accordingly.

Returns:

scaled_geometry – Geometry object with scaled coordinates and lattice vectors

Return type:

Geometry

get_slab(layers: int, surface: ndarray[Any, dtype[int64]] | None = None, threshold: float = 1e-06, surface_replica: Tuple[int, int] = (1, 1), vacuum_height: float | None = None, bool_shift_slab_to_bottom: bool = False) → Geometry

Generates a slab.

Parameters:

• layers (int) – Number of layers of the slab.

• surface (npt.NDArray[np.int64] | None, optional) – miller indices, eg. (1,1,1)

• threshold (float, optional) – numerical threshold for symmetry operations

• surface_replica (Tuple[int, int], optional) – Replications of surface. The default is (1,1).

• vacuum_height (float | None, optional) – DESCRIPTION. The default is None.

• bool_shift_slab_to_bottom (bool, optional) – DESCRIPTION. The default is False.

Returns:

slab_new – New Geometry

Return type:

Geometry

get_spglib_cell() → Tuple[ndarray[Any, dtype[float64]], ndarray[Any, dtype[int64]], list]

Returns the unit cell in a format that can be used in spglib (to find symmetries)

returntuple

(lattice vectors, frac coordinates of atoms, atomic numbers)

get_split_into_molecules(threshold) → list

Splits a structure into individual molecules. Two distinct molecules A and B are defined as two sets of atoms, such that no atom in A is closer than the selected thresold to any atom of B

get_substrate(primitive_substrate=None)

get_substrate_indices(primitive_substrate=None, dimension=2, threshold=0.3) → ndarray[Any, dtype[int64]]

This method returns the indices of all atoms that are part of the substrate. Often these are simply all metal atoms of the geometry. But the substrate can also be organic in which case it can’t be picked by being a metal. And there might be multiple adsorbate layers in which case only the molecules of the highest layer shall be counted as adsorbates and the others are part of the substrate.

dimension: int only used if primitive_substrate is not None threshold: float only used if primitive_substrate is not None

Returns:

indices of all substrate atoms

Return type:

npt.NDArray[np.int64]

get_substrate_indices_from_parts(do_warn=True) → None | ndarray[Any, dtype[int64]]

Returns indices of those atoms that a part of the substrate. The definition of the substrate does NOT rely of it being a metal or the height or something like that. Instead a geometry part named ‘substrate’ must be defined.

Parameters:

do_warn (boolean) – Can be set to False to suppress warnings

Returns:

substrate_indices

Return type:

npt.NDArray[np.int64]

get_substrate_layers(layer_indices: list, threshold: float = 0.01, primitive_substrate=None, substrate_indices: None | ndarray[Any, dtype[int64]] = None)

Get substrate layer by indices. The substrate is determined by default by the function self.get_substrate. For avoiding a faulty substrate determination it can be either given through indices or through the substrate geometry itself.

Parameters:

• layer_indices (list) – List of indices of layers that shall be returned.

• threshold (float, optional) – DESCRIPTION. The default is 1e-2.

• primitive_substrate (TYPE, optional) – DESCRIPTION. The default is None.

• substrate_indices (Union[None, list], optional) – List of indices of substrate atoms. The default is None.

Returns:

geometry_of_layer – Geometry of substrate layer.

Return type:

TYPE

get_symmetries(symmetry_precision: float = 1e-05, remove_refelction_in_z: bool = False)

Returns symmetries (rotation and translation matrices) from spglig. works only for unitcell and supercell geometries (lattice vecotrs must not be 0)

Beware: The returned symmetry matrices are given with respect to fractional coordinates, not Cartesian ones!

See https://atztogo.github.io/spglib/python-spglib.html#get-symmetry for details

Parameters:

save_directorystr

save directory in string format, file will be name symmetry.pickle (default = None –> symmetry is not saved)

Raises:

ValueError: If lattice vectors are 0

get_text(**kwargs)

get_total_mass() → float

Determines the atomic mass of the entrie geometry.

Returns:

atomic_mass – Atomic mass of the entrie geometry.

Return type:

float

get_transformation_indices(other_geometry, get_distances=False, periodic_2D=False)

Associates every atom in self to the closest atom of the same specie in other_geometry.

If self should be orderd like other_geometry then this is done in the following way: >>> transformation_indices = other_geometry.get_transformation_indices(self) >>> self.reorder_atoms(transformation_indices)

Parameters:

• other_geometry (geometry)

• norm_threshold (float)

• get_distances (bool) – The default is False.

• periodic_2D (bool) – The default is False.

Returns:

transformation_indices – The positions on the array correspond to the atoms in self; the values of the array correspond to the atoms in other_geometry

Return type:

np.array.

get_unconstrained_atoms() → ndarray[Any, dtype[int64]]

Returns indice of unconstrained atoms.

Returns:

inds – Indice of unconstrained atoms.

Return type:

npt.NDArray[np.int64]

get_unit_cell_parameters() → Tuple[float64, float64, float64, float, float, float]

Determines unit cell parameters.

Returns:

• a (float) – Length of lattice vector 1.

• b (float) – Length of lattice vector 2.

• c (float) – Length of lattice vector 3.

• alpha (float) – Angle between lattice vectors 1 and 2.

• beta (float) – Angle between lattice vectors 2 and 3.

• gamma (float) – Angle between lattice vectors 1 and 3.

get_volume_of_unit_cell() → float64

Calcualtes the volume of the unit cell.

Returns:

volume – Volume of the unit cell.

Return type:

float

is_equivalent(geom, tolerance=0.01, check_neightbouring_cells=False) → bool

Check if this geometry is equivalent to another given geometry. The function checks that the same atoms sit on the same positions (but possibly in some permutation)

Parameters:

check_neightbouring_cells – for periodic structures, recognizes two structures as equivalent, even if one of them has its atoms distributed in different unit cells compared to the other. More complete, but slower.

is_equivalent_up_to_translation(geom, get_translation=False, tolerance=0.01, check_neighbouring_cells=False)

returns True if self can be transformed into geom by a translation

(= without changing the geometry itself).

Parameters:

• geom (geometry) – Geometry to compare to.

• get_translation (bool) – Additionally return the found translation

• tolerance (float) – Tolerance threshold for larget mismatch between two atoms, below which they are still considered to be at the sameposition.

• check_neightbouring_cells (bool) – For periodic structures, recognizes two structures as equivalent, even if one of them has its atoms distributed in different unit cells compared to the other. More complete, but slower.

Returns:

• is_equivalent (bool) – True if equivalent.

• translation (np.array) – Translation vetror between equivalent geometries

map_center_of_atoms_to_first_unit_cell(lattice_vectors=None)

map_to_first_unit_cell(lattice_vectors=None, dimensions=array([0, 1, 2])) → None

aps the coordinate of a geometry in multiples of the substrate lattice vectors to a point that is closest to the origin

Parameters:

• lattice_vectors (float-array, optional) – Lattice vectors of the substrate. The default is None.

• dimensions (float-array, optional) – Dimensions (x, y, z) where the mapping should be done. The default is np.array(range(3)).

Return type:

None.

mirror_through_plane(normal_vector: ndarray[Any, dtype[float64]]) → None

Mirrors the geometry through the plane defined by the normal vector.

Parameters:

normal_vector (npt.NDArray[np.float64]) – Normal vector of mirror plane.

Return type:

None.

move_adsorbates(shift, primitive_substrate=None)

shifts the adsorbates in Cartesian coordinates

move_all_atoms(shift)

Translates the whole geometry by vector ‘shift’

move_all_atoms_by_fractional_coords(frac_shift, lattice_vectors=None)

move_multipoles(shift: ndarray[Any, dtype[float64]]) → None

Moves all the multipoles by a shift vector :param shift: list or array, len==3 :return:

parse(text)

read_from_file(filename: str) → None

Parses a geometry file

Parameters:

filename (str) – Path to input file.

Return type:

None.

remove_adsorbates(primitive_substrate=None) → None

Removes all atoms that are not part of the substrate

Return type:

None.

remove_atoms(atom_inds: ndarray[Any, dtype[int64]]) → None

Remove atoms with indices atom_inds. If no indices are specified, all atoms are removed.

Parameters:

atom_inds (np.array) – Indices of atoms to be removed.

Return type:

None

remove_atoms_by_species(species: str) → None

Removes all atoms of a given species.

Parameters:

species (str) – Atom species to be removed.

Return type:

None

remove_collisions(keep_latest: bool | slice = True) → None

Removes all atoms that are in a collision group as given by GeometryFile.getCollidingGroups.

Parameters:

keep_latest (Union[bool, slice], optional) – Whether to keep the earliest or latest added. If a slice object is given, the selection is used to determine which atoms to keep. Defaults to True.

Return type:

None.

remove_constrained_atoms() → None

Remove all atoms where all coordinates are constrained.

Return type:

None

remove_metal_atoms() → None

Removes all atoms with atomic number > 18 and atomic numbers 3,4,11,12,13,14

Return type:

None.

remove_non_metallic_atoms() → None

Removes all atoms that are not metal

Return type:

None.

remove_periodicity()

Makes geometry non-periodic by setting its lattice vectors to zero

remove_substrate(primitive_substrate) → None

Removes all substrate atoms given the primitive substrate by identifying species and height

Parameters:

• primitive_substrate (Geometry) – primitive substrate file of system

• dimension (int) – dimension to use as z-axis

• threshold (float) – height threshold in A

remove_unconstrained_atoms()

Remove all atoms where all coordinates are constrained.

Return type:

None

reorder_atoms(inds: ndarray[Any, dtype[int64]]) → None

eorders Atoms with index list

Parameters:

inds (npt.NDArray[np.int64]) – Array of indices with new order of atoms.

Return type:

None

rotate_coords_around_axis(angle_in_degree: float, axis: ndarray[Any, dtype[float64]] = array([0., 0., 1.]), center=None, indices=None) → None

Rotates structure COUNTERCLOCKWISE around a point defined by <center>.

Parameters:

• angle_in_degree (float) – Angle of rotation.

• axis (npt.NDArray[np.float64], optional) – Axis of rotation. The default is np.array([0.0, 0.0, 1.0]).

• center (npt.NDArray[np.float64], optional) – If center == None, the geometric center of the structure (as defined by self.get_geometric_center()). The default is None.

• indices (list, optional) – Indices of atoms to be manipulated. If indices == None, all atoms will be used. The default is None.

Return type:

None.

rotate_lattice_around_axis(angle_in_degree: float, axis: ndarray[Any, dtype[float64]] = array([0., 0., 1.])) → None

Rotates lattice around a given axis.

Parameters:

• angle_in_degree (float) – angle of rotation

• axis (np.array) – Axis around which to rotate. The default is

Return type:

None.

save_to_file(filename, **kwargs)

set_calculate_friction(indices_of_atoms: list, calculate_friction: bool = True) → None

Sets to calculate electronic friction for atoms specified by the given list of indices.

Parameters:

• indices_of_atoms (list) – List of atoms from which electronic friction should be calculated.

• calculate_friction (bool, optional) – Calculate friction for these atims. The default is True.

Return type:

None

set_constraints(indices_of_atoms_to_constrain: list, constrain_dim_flags=None)

Sets a constraint for a few atoms in the system (identified by ‘indices_of_atoms_to_constrain’) for a geometry relaxation. Since the relaxation constraint can be in any and/or all dimensions the second parameter, ‘constraint_dim_flags’, makes it possible to set which dimension(s) should be constrained for which molecule. By default all dimensions are to be constrained for all atoms are constrained. If the dimension to constrain should be set individually for different atoms, you need to provide a list of booleans of the shap len(indices_of_atoms_to_constrain) x 3, which contains the constrain flags for each dimension for each atom.

Parameters:

• indices_of_atoms_to_constrain (list) – List of atoms to constrain.

• constrain_dim_flags (list[boolean]) – The default is: [True, True, True].

Return type:

None

set_constraints_based_on_space(xlim=(-inf, inf), ylim=(-inf, inf), zlim=(-inf, inf), constrain_dim_flags=None)

Constrain all atoms that are within a cuboid (defined by limits in all dimensions: xlim, etc.) for a geometry relaxation.

It is possible to define which dimension will be constrained, but since the number of atoms in the cuboid is only calculated at runtime the dimensions may only be set for all atoms at once. If you need to set them individually please use set_constraints.

Parameters:

• zlim

• xlim

• ylim

• constrain_dim_flags (list[boolean]) – The default is: [True, True, True].

Return type:

None

set_external_forces(indices_of_atoms: int | ndarray[Any, dtype[int64]], external_force: ndarray[Any, dtype[float64]]) → None

Sets a constraint for a few atoms in the system (identified by ‘indices_of_atoms_to_constrain’) for a geometry relaxation. Since the relaxation constraint can be in any and/or all dimensions the second parameter, ‘constraint_dim_flags’, makes it possible to set which dimension(s) should be constrained for which molecule. By default all dimensions are to be constrained for all atoms are constrained. If the dimension to constrain should be set individually for different atoms, you need to provide a list of booleans of the shape len(indices_of_atoms_to_constrain) x 3, which contains the constrain flags for each dimension for each atom.

Parameters:

• indices_of_atoms_to_constrain (int or npt.NDArray[np.int64]) – Index of atoms to which atoms should should be applied.

• constrain_dim_flags (npt.NDArray[np.float64]) – Force that should act on a given atom.

set_homogeneous_field(E)

Field should be a numpy array (Ex, Ey, Ez) with the Field in V/A

set_multipoles_charge(charge: ndarray[Any, dtype[float64]]) → None

Sets the charge of all multipoles

Parameters:

charge (list or float or int)

Return type:

None

set_vacuum_height(vac_height, bool_shift_to_bottom=False) → None

set_vacuum_level(vacuum_level: float) → None

Sets vacuum level of geometry calculation

Parameters:

vacuum_level (float) – Height of the vacuum level.

Return type:

None

shift_to_bottom()

Shifts the coordiantes such that the coordinate with the samllest z-value ists at (x, y, 0).

Return type:

None.

swap_lattice_vectors(axis_1=0, axis_2=1)

Can be used to interchange two lattice vectors Attention! Other values - for instance k_grid - will stay unchanged!! :param axis_1 integer [0,1,2] :param axis_2 integer [0,1,2] axis_1 !=axis_2 :return:

symmetrize(symmetry_operations, center=None)

Symmetrizes Geometry with given list of symmetry operation matrices after transferring it to the origin. Do not include the unity matrix for symmetrizing, as it is already the first geometry! ATTENTION: use symmetrize_periodic to reliably symmetrize periodic structures

transform(R: ndarray[Any, dtype[float64]], t: ndarray[Any, dtype[float64]] = array([0, 0, 0]), rotation_center: ndarray[Any, dtype[float64]] | None = None, atom_indices: ndarray[Any, dtype[int64]] | None = None) → None

Performs a symmetry transformation of the coordinates by rotation and translation. The transformation is applied as x_new[3x1] = x_old[3x1] x R[3x3] + t[3x1]

Parameters:

• R (np.array) – Rotation matrix in Catesian coordinates.

• t (np.array, optional) – Translation vector in Catesian coordinates. The default is np.array([0,0,0]).

• rotation_center (np.array | None, optional) – Centre of rotation. The default is None.

• atom_indices (np.array | None, optional) – List of indexes of atoms that should be transformed. The default is None.

Return type:

None

transform_fractional(R: ndarray[Any, dtype[float64]], t: ndarray[Any, dtype[float64]], lattice=None)

Transforms the coordinates by rotation and translation, where R,t are given in fractional coordinates The transformation is applied as c_new[3x1] = R[3x3] * c_old[3x1] + t[3x1]

transform_lattice(R: ndarray[Any, dtype[float64]], t: ndarray[Any, dtype[float64]] = array([0, 0, 0])) → None

Transforms the lattice vectors by rotation and translation. The transformation is applied as x_new[3x1] = x_old[3x1] x R[3x3] + t[3x1] Notice that this works in cartesian coordinates. Use transform_fractional if you got your R and t from get_symmetries

Parameters:

• R (np.array) – Rotation matrix in Catesian coordinates.

• t (np.array, optional) – Translation vector in Catesian coordinates. The default is np.array([0,0,0]).

Return type:

None

transform_lattice_fractional(R, t, lattice)

Transforms the lattice vectors by rotation and translation. The transformation is applied as x_new[3x1] = x_old[3x1] x R[3x3] + t[3x1]

truncate(n_atoms: int) → None

Keep only the first n_atoms atoms

Parameters:

n_atoms (int) – Number of atoms to be kept.

Return type:

None

visualise(axes=[0, 1], min_zorder=0, value_list=None, maxvalue=None, minvalue=None, cbar_label='', hide_axes=False, axis_labels=True, auto_limits=True, crop_ratio=None, brightness_modifier=None, print_lattice_vectors=False, alpha=1.0, linewidth=1, lattice_linewidth=None, lattice_color='k', atom_scale=1, highlight_inds=[], highlight_color='C2', color_list=None, cmap=None, ax=None, xlim=None, ylim=None, zlim=None, plot_method='circles', invert_colormap=False, edge_color=None, show_colorbar=True, reverse_sort_inds=False, axis_labels_format='/') → None

Generates at plt-plot of the current geometry. This function has a large number of options. In most cases the following examples will work well:

• Visualise the geometry:

geometry.visualise()

• Turn aff axis:

geometry.visualise(hide_axes=True)

• Turn off axis and set limits:

geometry.visualise(hide_axes=True, xlim=(-10, 10))

• If you want to look at the geoemtry in the xz-plane:

geometry.visualise(axes=[0,2], hide_axes=True, xlim=(-10, 10))

Visualise is one of the most useful things about geometry. Reading through this code you may think that it is very ugly and on to of that if has it’s own imports. Still it is a great function and it must be part of geometry. If you think otherwise you are wrong.

Note from Dylan: I completely agree if you think it’s ugly and should be killed with fire. Do not listen to Lukas. He is wrong. Fortunately I managed to convince him to get rid of the function-scoped imports so you’re welcome.

Parameter:

axeslist of 2 int elements

axis that should be visualized, x=0, y=1, z=2 By default, we look at the geometry from: the “top” (our viewpoint is at z = +infinity) when we visualize the xy plane; the “right” (our viewpoint is at x = +infinity) when we visualize the yz plane; the “front” (our viewpoint is at y = -infinity) when we visualize the xz plane. In order to visualize the geometry from the opposite viewpoints, one needs to use the reverse_sort_inds flag, and invert the axis when necessary (= set axis limits so that the first value is larger than the second value)

min_zorderint

plotting layer

value_list : None or list of length nr. atoms

maxvalue : None

cbar_label : str

hide_axesbool

hide axis

axis_labelsbool

generates automatic axis labels

auto_limitsbool

set xlim, ylim automatically

crop_ratio: float

defines the ratio between xlim and ylim if auto_limits is enabled

brightness_modifierfloat or list/array with length equal to the number of atoms

modifies the brightness of selected atoms. If brightness_modifier is a list/array, then brightness_modifier[i] sets the brightness for atom i, otherwise all atoms are set to the same brightness value. This is done by tweaking the ‘lightness’ value of said atoms’ color in the HSL (hue-saturation-lightness) colorspace. Effect of brightness_modifier in detail: -1.0 <= brightness_modifier < 0.0 : darker color brightness_modifier == 0.0 or None : original color 0.0 < brightness_modifier <= 1.0 : brighter color

print_lattice_vectorsbool

display lattice vectors

print_unit_cellbool

display original unit cell

alpha : float between 0 and 1

color_listlist or string

choose colors for visualizing each atom. If only one color is passed, all atoms will have that color.

plot_method: str

circles: show filled circles for each atom wireframe: show molecular wireframe, standard settings: don’t show H,

reverse_sort_inds: bool

if set to True, inverts the order at which atoms are visualized, allowing to visualise the geometry from the “bottom”, from the “left” or from the “back”. Example: if one wants to visualise the geometry from the “left” (= viewpoint at x=-infinity), atoms at lower x values should be visualised after atoms at high x values, and hide them. This is the opposite of the default behavior of this function, and can be achieved with reverse_sort_inds=True NOTE: in order to correctly visualize the structure from these non-default points of view, setting this flag to True is not sufficient: one must also invert the XY axes of the plot where needed. Example: when visualising from the “left”, atoms with negative y values should appear on the right side of the plot, and atoms with positive y values should appear on the left side of the plot. But if one simply sets reverse_sort_inds=True, atoms with negative y values will appear on the left side of the plot (because the x axis of the plot, the horizontal axis, goes from left to right!) and vice-versa. This is equivalent to visualising a mirrored image of the structure. To visualise the structure correctly, one should then set the x_limits of the plot with a first value smaller than the second value, so the x axis is inverted, and shows y-negative values on the left and viceversa.

rtype:

None

class dfttoolkit.geometry.VaspGeometry(filename: str | None = None)

Bases: Geometry

get_text(comment='POSCAR file written by Geometry.py')

parse(text)

Read the VASP structure definition in the typical POSCAR format (also used by CONTCAR files, for example) from the file with the given filename

Returns:

dic:

The dictionary holds the following keys: systemname: The name of the system as given in the first line of the POSCAR file. vecs: The unit cell vector as a 3x3 numpy.array. vecs[0,:] is the first unit cell vector, vecs[:,0] are the x-coordinates of the three unit cell cevtors. scaling: The scaling factor of the POSCAR as given in the second line. However, this information is not processed, it is up to the user to use this information to scale whatever needs to be scaled. coordinates: The coordinates of all the atoms. Q[k,:] are the coordinates of the k-th atom (the index starts with 0, as usual). Q[:,0] are the x-coordinates of all the atoms. These coordinates are always given in Cartesian coordinates. elementtypes: A list of as many entries as there are atoms. Gives the type specification for every atom (typically the atom name). elementtypes[k] is the species of the k-th atom. typenames: The names of all the species. This list contains as many elements as there are species. numberofelements: Gives the number of atoms per species. This list contains as many elements as there are species. elementid: Gives the index (from 0 to the number of atoms-1) of the first atom of a certain species. This list contains as many elements as there are species. cartesian: A logical value whether the coordinates were given in Cartesian form (True) or as direct coordinates (False). originalcoordinates: The original coordinates as read from the POSCAR file. It has the same format as coordinates. For Cartesian coordinates (cartesian == True) this is identical to coordinates, for direct coordinates (cartesian == False) this contains the direct coordinates. selective: True or False: whether selective dynamics is on. selectivevals: Consists of as many rows as there are atoms, three colums: True if selective dynamics is on for this coordinate for the atom, else False. Only if selective is True.

class dfttoolkit.geometry.XSFGeometry(filename: str | None = None)

Bases: Geometry

get_text()

class dfttoolkit.geometry.XYZGeometry(filename: str | None = None)

Bases: Geometry

get_text(comment='XYZ file written by Geometry.py')

parse(text)

Reads a .xyz file. Designed to work with .xyz files produced by Avogadro

dfttoolkit.geometry.get_file_format_from_ending(filename)

dfttoolkit.output module

class dfttoolkit.output.AimsOutput(aims_out: str = 'aims.out')

Bases: Output

FHI-aims output file parser.

…

lines

The contents of the aims.out file.

Type:

List[str]

path

The path to the aims.out file.

Type:

str

Examples

>>> ao = AimsOutput(aims_out="./aims.out")

check_exit_normal() → bool

Check if the FHI-aims calculation exited normally.

Returns:

whether the calculation exited normally or not

Return type:

bool

check_spin_polarised() → bool

Check if the FHI-aims calculation was spin polarised.

Returns:

Whether the calculation was spin polarised or not

Return type:

bool

get_HOMO_energy(n_occurrence: None | int = -1, energy_invalid_indicator: list[str] = []) → float | ndarray[Any, dtype[float64]]

get_LUMO_energy(n_occurrence: None | int = -1, energy_invalid_indicator: list[str] = []) → float | ndarray[Any, dtype[float64]]

get_all_ks_eigenvalues() → dict | Tuple[dict, dict]

Get all Kohn-Sham eigenvalues from a calculation.

Returns:

dict

the kohn-sham eigenvalues

Tuple[dict, dict]

dict

the spin-up kohn-sham eigenvalues

dict

the spin-down kohn-sham eigenvalues

Return type:

Union[dict, Tuple[dict, dict]]

Raises:

• ItemNotFoundError – the ‘output_level full’ keyword was not found in the calculation

• ValueError – could not determine if the calculation was spin polarised

get_change_of_forces(n_occurrence=-1, energy_invalid_indicator=None) → float | ndarray[Any, dtype[float64]]

get_change_of_sum_of_eigenvalues(n_occurrence=-1, energy_invalid_indicator=None) → float | ndarray[Any, dtype[float64]]

get_change_of_total_energy(n_occurrence: int | None = -1, energy_invalid_indicator=None) → float | ndarray[Any, dtype[float64]]

get_convergence_parameters() → dict

Get the convergence parameters from the aims.out file.

Returns:

The convergence parameters from the aims.out file

Return type:

dict

get_cx_potential_correction(n_occurrence: None | int = -1, energy_invalid_indicator: list[str] = []) → float | ndarray[Any, dtype[float64]]

get_density_embedding_energy(n_occurrence: None | int = -1, energy_invalid_indicator: list[str] = []) → float | ndarray[Any, dtype[float64]]

The energy of the electrons (electron density) in the potential of the external electric field.

get_electrostatic_energy(n_occurrence: None | int = -1, energy_invalid_indicator: list[str] = []) → float | ndarray[Any, dtype[float64]]

get_energy_corrected(n_occurrence: int | None = -1, skip_E_after_mixer: bool = True, all_scfs: bool = False, energy_invalid_indicator: list[str] = []) → float | ndarray[Any, dtype[float64]]

Return the total corrected energy.

Parameters:

• n_occurrence (Union[int, None]) – If there are multiple energies in a file (e.g. during a geometry optimization) this parameters allows to select which energy is returned. If set to -1 the last one is returned (e.g. result of a geometry optimization), if set to None, all values will be returned as a numpy array.

• skip_E_after_mixer (bool, default=True) – If the scf cycles of one geometry optimisation step didn’t converge, aims will restart the mixer and this optimisation step. However, it still prints out the total energy, which can be totally nonsense. if skip_E_after_mixer==True ignore first total energy after ‘restarting mixer to attempt better convergence’

Examples

>>> AimsOutput.get_energy_corrected()
-2080.83225450528

get_energy_uncorrected(n_occurrence: None | int = -1, skip_E_after_mixer: bool = True, energy_invalid_indicator: list[str] = []) → float | ndarray[Any, dtype[float64]]

Return uncorrected (without smearing correction) energy

Parameters:

• n_occurrence (Union[int, None]) – see getEnergyCorrected()

• skip_E_after_mixer (bool) – If the scf cycles of one geometry optimisation step didn’t converge, aims will restart the mixer and this optimisation step. However, it still prints out the total energy, which can be totally nonsense. if skip_E_after_mixer==True: ignore first total energy after ‘restarting mixer to attempt better convergence’

Returns:

Uncorrected energy

Return type:

Union[float, npt.NDArray[np.float64]]

get_energy_without_vdw(n_occurrence: None | int = -1, energy_invalid_indicator: list[str] = []) → float | ndarray[Any, dtype[float64]]

get_entropy_correction(n_occurrence: None | int = -1, energy_invalid_indicator: list[str] = []) → float | ndarray[Any, dtype[float64]]

get_exchange_correlation_energy(n_occurrence: None | int = -1, energy_invalid_indicator: list[str] = []) → float | ndarray[Any, dtype[float64]]

get_external_embedding_energy(n_occurrence: None | int = -1, energy_invalid_indicator: list[str] = []) → float | ndarray[Any, dtype[float64]]

This is the sum of all the embedding energies. I.e. ionic + (electronic) density + nonlocal.

get_final_energy() → float | None

Get the final energy from a FHI-aims calculation.

Returns:

The final energy of the calculation

Return type:

Union[float, None]

get_final_ks_eigenvalues() → dict | Tuple[dict, dict]

Get the final Kohn-Sham eigenvalues from a calculation.

Returns:

dict

the final kohn-sham eigenvalues

Tuple[dict, dict]

dict

the spin-up kohn-sham eigenvalues

dict

the spin-down kohn-sham eigenvalues

Return type:

Union[dict, Tuple[dict, dict]]

Raises:

• ValueError – the calculation was not spin polarised

• ValueError – the final KS states were not found in aims.out file

get_forces(n_occurrence: None | int = -1) → ndarray[Any, dtype[float64]]

Return forces on all atoms

get_free_atom_electrostatic_energy(n_occurrence: None | int = -1, energy_invalid_indicator: list[str] = []) → float | ndarray[Any, dtype[float64]]

get_geometry() → AimsGeometry

Extract the geometry file from the aims output and return it as a Geometry object

Returns:

Geometry object

Return type:

AimsGeometry

get_geometry_steps_of_optimisation(n_occurrence=None) → list

Get a list of all geometry steps performed.

Parameters:

n_occurrence (int or None) – If there are multiple energies in a file (e.g. during a geometry optimization) this parameters allows to select which energy is returned. If set to -1 the last one is returned (e.g. result of a geometry optimization), if set to None, all values will be returned as a numpy array.

Returns:

geometry_files – List of geometry objects.

Return type:

list

get_hartree_energy_correction(n_occurrence: None | int = -1, energy_invalid_indicator: list[str] = []) → float | ndarray[Any, dtype[float64]]

get_i_scf_conv_acc() → dict

Get SCF convergence accuracy values from the aims.out file.

Returns:

The scf convergence accuracy values from the aims.out file

Return type:

dict

get_ionic_embedding_energy(n_occurrence: None | int = -1, energy_invalid_indicator: list[str] = []) → float | ndarray[Any, dtype[float64]]

The energy of the nuclei in the potential of the external electric field.

get_kinetic_energy(n_occurrence: None | int = -1, energy_invalid_indicator: list[str] = []) → float | ndarray[Any, dtype[float64]]

get_maximum_force(n_occurrence=-1, energy_invalid_indicator=None) → float | ndarray[Any, dtype[float64]]

get_n_initial_ks_states(include_spin_polarised=True) → int

Get the number of Kohn-Sham states from the first SCF step.

Parameters:

include_spin_polarised (bool, default=True) – Whether to include the spin-down states in the count if the calculation is spin polarised.

Returns:

The number of kohn-sham states

Return type:

int

get_n_relaxation_steps() → int

Get the number of relaxation steps from the aims.out file.

Returns:

the number of relaxation steps

Return type:

int

get_n_scf_iters() → int

Get the number of SCF iterations from the aims.out file.

Returns:

The number of scf iterations

Return type:

int

get_nonlocal_embedding_energy(n_occurrence: None | int = -1, energy_invalid_indicator: list[str] = []) → float | ndarray[Any, dtype[float64]]

Energy of non local electron interaction (i think?) in the potential of the electric field.

get_number_of_atoms() → int

Return number of atoms in unit cell

Returns:

Number of atoms in the unit cell

Return type:

int

get_parameters() → AimsControl

Extract the control file from the aims output and return it as an AimsControl object

Returns:

AimsControl object

Return type:

AimsControl

get_pert_soc_ks_eigenvalues() → dict

Get the perturbative SOC Kohn-Sham eigenvalues from a calculation.

Returns:

The perturbative SOC kohn-sham eigenvalues

Return type:

dict

Raises:

ValueError – the final KS states were not found in aims.out file

get_sum_of_eigenvalues(n_occurrence: None | int = -1, energy_invalid_indicator: list[str] = []) → float | ndarray[Any, dtype[float64]]

get_time_per_scf() → ndarray[Any, dtype[float64]]

Calculate the average time taken per SCF iteration.

Returns:

The average time taken per SCF iteration.

Return type:

npt.NDArray[np.float64]

get_total_energy_T0(n_occurrence: None | int = -1, skip_E_after_mixer: bool = True, energy_invalid_indicator: list[str] = []) → float | ndarray[Any, dtype[float64]]

get_vdw_energy(n_occurrence: None | int = -1, energy_invalid_indicator: list[str] = []) → float | ndarray[Any, dtype[float64]]

class dfttoolkit.output.ELSIOutput(elsi_out: str)

Bases: Output

Parse matrix output written in a binary csc format from ELSI.

…

lines

Contents of ELSI output file.

n_basis

Number of basis functions

Type:

int

n_non_zero

Number of non-zero elements in the matrix

Type:

int

get_elsi_csc_header() → ndarray[Any, dtype[int64]]

Get the contents of the ELSI file header

Returns:

The contents of the ELSI csc file header

Return type:

tuple

property n_basis: int

property n_non_zero: int

read_elsi_as_csc(csc_format: bool = False) → csc_matrix | ndarray[Any, dtype[float64]]

Get a CSC matrix from an ELSI output file

Parameters:

csc_format (bool, default=True) – Whether to return the matrix in CSC format or a standard numpy array

Returns:

The CSC matrix or numpy array

Return type:

Tuple[sp.csc_matrix, np.ndarray]

class dfttoolkit.output.Output(**kwargs: str)

Bases: BaseParser

Base class for parsing output files from electronic structure calculations.

If contributing a new parser, please subclass this class, add the new supported file type to _supported_files, call the super().__init__ method, include the new file type as a kwarg in the super().__init__ call. Optionally include the self.lines line in examples.

…

supported_files

List of supported file types.

Type:

List[str]

Examples

class AimsOutput(Output):

def __init__(self, aims_out: str = “aims.out”):

super().__init__(aims_out=aims_out) self.lines = self._file_contents[“aims_out”]

property supported_files: List[str]

dfttoolkit.parameters module

class dfttoolkit.parameters.AimsControl(control_in: str = 'control.in', parse_file: bool = True)

Bases: Parameters

FHI-aims control file parser.

…

lines

The contents of the control.in file.

Type:

List[str]

path

The path to the control.in file.

Type:

str

add_keywords(**kwargs: dict) → None

Add keywords to the control.in file.

Parameters:

**kwargs (dict) – Keywords to be added to the control.in file.

get_keywords() → dict

Get the keywords from the control.in file.

Returns:

A dictionary of the keywords in the control.in file.

Return type:

dict

remove_keywords(*args: str, output: Literal['overwrite', 'print', 'return'] = 'return') → None | List[str]

Remove keywords from the control.in file.

Parameters:

• *args (str) – Keywords to be removed from the control.in file.

• output (Literal["overwrite", "print", "return"], default="overwrite") – Overwrite the original file, print the modified file to STDOUT, or return the modified file as a list of ‘n’ separated strings.

Returns:

If output is “return”, the modified file is returned as a list of ‘n’ separated strings.

Return type:

Union[None, List[str]]

class dfttoolkit.parameters.Parameters(**kwargs: str)

Bases: BaseParser

Handle files that control parameters for electronic structure calculations.

If contributing a new parser, please subclass this class, add the new supported file type to _supported_files, call the super().__init__ method, include the new file type as a kwarg in the super().__init__ call. Optionally include the self.lines line in examples.

…

_supported_files

List of supported file types.

Type:

list

property supported_files: List[str]

dfttoolkit.vibrations module

class dfttoolkit.vibrations.AimsVibrations(filename=None)

Bases: Vibrations, AimsGeometry

class dfttoolkit.vibrations.VaspVibrations(filename=None)

Bases: Vibrations, VaspGeometry

class dfttoolkit.vibrations.Vibrations

Bases: object

property eigenvalues

property eigenvectors

get_atom_type_index()

get_coupling_matrix(velocities: ndarray[Any, dtype[float64]], time_step: float, bootstrapping_blocks: int = 1, bootstrapping_overlap: int = 0)

get_cross_correlation_function(velocities: ndarray[Any, dtype[float64]], time_step: float, bootstrapping_blocks: int = 1, bootstrapping_overlap: int = 0)

Parameters:

• velocities (npt.NDArray[np.float64]) – DESCRIPTION.

• time_step (float) – DESCRIPTION.

• bootstrapping_blocks (int, default=1) – DESCRIPTION

• bootstrapping_overlap (int, default=0) – DESCRIPTION

Returns:

• autocorr_t (np.array) – DESCRIPTION.

• autocorr (np.array) – DESCRIPTION.

get_cross_spectrum(velocities: ndarray[Any, dtype[float64]], time_step: float, use_mem: bool = False, bootstrapping_blocks: int = 1, bootstrapping_overlap: int = 0, model_order: int = 15)

get_displacements(displacement: float = 0.0025) → list

Applies a given displacement for each degree of freedom of self and generates a new vibration with it.

Parameters:

displacement (float, default=0.0025) – Displacement for finte difference calculation of vibrations in Angstrom.

Returns:

List of geometries where atoms have been displaced.

Return type:

list

get_eigenvalues_and_eigenvectors(hessian: ndarray[Any, dtype[float64]] | None = None, only_real: bool = True, symmetrize_hessian: bool = True) → Tuple[ndarray[Any, dtype[float64]], ndarray[Any, dtype[float64]]]

This function is supposed to return all eigenvalues and eigenvectors of the matrix self.hessian

Parameters:

• hessian (npt.NDArray[np.float64], optional) – Hessian. The default is None.

• only_real (bool, default=True) – Returns only real valued eigenfrequencies + eigenmodes (ATTENTION: if you want to also include instable modes, you have to symmetrize the hessian as provided below).

• symmetrize_hessian (bool, default=True) – Symmetrise the hessian only for this function (no global change).

Returns:

• omega2 (np.array) – Direct eigenvalues as squared angular frequencies instead of inverse wavelengths.

• eigenvectors (np.array) – List of numpy arrays, where each array is a normalized displacement for the corresponding eigenfrequency, such that new_coords = coords + displacement * amplitude..

get_eigenvalues_in_Hz(omega2: None | ndarray[Any, dtype[float64]] = None) → ndarray[Any, dtype[float64]]

Determine vibration frequencies in cm^-1.

Parameters:

omega2 (Union[None, np.array]) – Eigenvalues of the mass weighted hessian.

Returns:

omega_SI – Array of the eigenfrequencies in Hz.

Return type:

np.array

get_eigenvalues_in_inverse_cm(omega2: None | ndarray[Any, dtype[float64]] = None) → ndarray[Any, dtype[float64]]

Determine vibration frequencies in cm^-1.

Parameters:

omega2 (Union[None, np.array]) – Eigenvalues of the mass weighted hessian.

Returns:

f_inv_cm – Array of the eigenfrequencies in cm^(-1).

Return type:

np.array

get_hessian(set_constrained_atoms_zero: bool = False) → ndarray[Any, dtype[float64]]

Calculates the Hessian from the forces. This includes the atmoic masses since F = m*a.

Parameters:

set_constrained_atoms_zero (bool, default=False) – Set elements in Hessian that code for constrained atoms to zero.

Returns:

H – Hessian.

Return type:

np.array

get_instance_of_other_type(vibrations_type)

get_mass_tensor() → ndarray[Any, dtype[float64]]

Determine a NxN tensor containing sqrt(m_i*m_j).

Returns:

mass_tensor – Mass tensor in atomic units.

Return type:

np.array

get_normal_mode_decomposition(velocities: ndarray[Any, dtype[float64]], use_numba: bool = True) → ndarray[Any, dtype[float64]]

Calculate the normal-mode-decomposition of the velocities. This is done by projecting the atomic velocities onto the vibrational eigenvectors. See equation 10 in: https://doi.org/10.1016/j.cpc.2017.08.017

Parameters:

velocities (npt.NDArray[np.float64]) – Array containing the velocities from an MD trajectory structured in the following way: [number of time steps, number of atoms, number of dimensions].

Returns:

velocities_projected – Velocities projected onto the eigenvectors structured as follows: [number of time steps, number of frequencies]

Return type:

npt.NDArray[np.float64]

get_symmetrized_hessian(hessian=None)

Symmetrieses the Hessian by using the lower triangular matrix

Parameters:

hessian (TYPE, default=None) – DESCRIPTION

Return type:

None.

get_velocity_mass_average(velocities: ndarray[Any, dtype[float64]]) → ndarray[Any, dtype[float64]]

Weighs velocities by atomic masses.

Parameters:

velocities (npt.NDArray[np.float64])

Returns:

velocities_mass_average – Velocities weighted by atomic masses.

Return type:

np.array

property hessian

output_cross_spectrum(velocities: ndarray[Any, dtype[float64]], time_step: float, use_mem: bool = False, bootstrapping_blocks: int = 1, bootstrapping_overlap: int = 0, model_order: int = 15, processes=1, frequency_cutoff=None, dirname='cross_spectrum')

project_onto_wave_vector(velocities: ndarray[Any, dtype[float64]], wave_vector: ndarray[Any, dtype[float64]], project_on_atom: int = -1) → ndarray[Any, dtype[float64]]

property vibration_coords

property vibration_forces

dfttoolkit.visualise module

class dfttoolkit.visualise.VisualiseAims(aims_out: str = 'aims.out')

Bases: AimsOutput

FHI-aims visualisation tools.

…

scf_conv_acc_params

the SCF convergence accuracy parameters

Type:

dict

convergence(scf_conv_acc_params=None, title=None, forces=False, ks_eigenvalues=False, fig_size=(24, 6))

Plot the SCF convergence accuracy parameters.

convergence(conv_params=None, scf_conv_acc_params=None, title=None, forces=False, ks_eigenvalues=False, fig_size=(24, 6)) → Figure

Plot the SCF convergence accuracy parameters.

Parameters:

• conv_params (dict) – convergence parameters which determine if the SCF cycle has converged

• scf_conv_acc_params (dict) – the scf convergence accuracy parameters

• title (str) – system name to use in title of the plot

• forces (bool) – whether to plot the change of forces and forces on atoms

• ks_eigenvalues (bool) – whether to plot the kohn-sham eigenvalues

• fig_size (tuple) – the total size of the figure

Returns:

matplotlib figure object

Return type:

figure.Figure

Module contents