dfttoolkit package

Submodules

dfttoolkit.base_parser module

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[tuple[int, ...], 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[NDArray[float64]]

dfttoolkit.custom_ase module

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

Bases: Aims

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) → 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

Represent a geometry file for (in principle) any DFT code.

In practice it has only been fully implemented for FHI-aims geometry.in files.

Parameters:

• Filename (str) – Path to text file of geometry.

• center (dict) – atom indices and linear combination of them to define the center of a molecule. Used only for mapping to first unit cell. Example: if the center should be the middle between the first three atoms, center would be {1:1/3,2:1/3,3:1/3}

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

Add 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

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

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[tuple[int, ...], dtype[float64]], vector_to_align: ndarray[tuple[int, ...], 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[tuple[int, ...], dtype[float64]]) → None

align_with_z_vector(new_z_vec: ndarray[tuple[int, ...], 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)

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[tuple[int, ...], dtype[float64]], t: ndarray[tuple[int, ...], 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: list[int] | None = None) → None

Remove 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[tuple[int, ...], 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[tuple[int, ...], dtype[int64]]

Get 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[tuple[int, ...], dtype[float64]] | None = None, substrate=None) → float

Calculate the unit cell area using atoms in the topmost substrate layer.

By default, the substrate is determined using self.getSubstrate(). To avoid incorrect automatic detection, the substrate can also be specified manually, either by providing atom indices or by passing the substrate geometry directly.

Parameters:

• substrate_indices (npt.NDArray[np.float64] | None, default = None) – List of indices of substrate atoms

• substrate (TODO, default = None) – Geometry of the substrate

Returns:

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

Return type:

float

get_as_ase() → Atoms

Convert geometry file to ASE object.

Returns:

ASE atoms object

Return type:

ase.Atoms

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[tuple[int, ...], 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[tuple[int, ...], dtype[float64]]

Get the atomic numbers of all atoms in the geometry file.

get_atoms_by_indices(atom_indices: ndarray[tuple[int, ...], 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[tuple[int, ...], dtype[float64]]

Parameters:

atom-distance (Parameter for bond detection based on) – TODO

Returns:

bond_lengths – List of bond lengths for neighbouring atoms.

Return type:

NDArray[float64]

get_center_of_mass() → ndarray[tuple[int, ...], 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: int | Collection[int], species: list | None = None, n_closest: int = 1) → list

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

Parameters:

• index (int | Collection[int]) – atoms for which the closest indices are to be found

• species (list | None) – 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

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[tuple[int, ...], 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: tuple[float, float] = (-inf, inf), ylim: tuple[float, float] = (-inf, inf), zlim: tuple[float, float] = (-inf, inf), auto_margin: bool = False, inverse: bool = False) → ndarray[tuple[int, ...], 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[tuple[int, ...], dtype[floating]]

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) → floating

Get the distance between two atoms in the current Geometry.

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: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[floating]]

Compute fractional lattice vectors of a geometry in a different basis.

Useful to calculate epitaxy matrices.

get_from_ase_atoms_object(atoms: Atoms) → None

Read 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: bool = False, indices: Collection[int] | None = None) → ndarray[tuple[int, ...], dtype[float64]]

Get 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 (Collection[int] | 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() → ndarray[tuple[int, ...], dtype[Any]] | None

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[tuple[int, ...], dtype[int64]]

Get indices of all metals.

These are 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[tuple[int, ...], 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[tuple[int, ...], 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[tuple[int, ...], dtype[float64]] = 'unity') → tuple[ndarray[tuple[int, ...], dtype[float64]], ndarray[tuple[int, ...], dtype[float64]]]

Get main axes and eigenvalues of a molecule.

https://de.wikipedia.org/wiki/Tr%C3%A4gheitstensor

Parameters:

weights (str | npt.NDArray[np.float64], default = "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:

angle between main axis and x axis in degree

Return type:

float

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

Get 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

rtype:

Geometry

get_principal_moments_of_inertia() → ndarray[tuple[int, ...], 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[tuple[int, ...], 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

Return 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 (float | list) – Scaling factor for the geometry. If float, the volume of the geometry will be scaled accordingly. If a list, 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[tuple[int, ...], 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[tuple[int, ...], dtype[float64]], ndarray[tuple[int, ...], dtype[int64]], list]

Returns the unit cell in a format that can be used in spglib.

Used 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: int = 2, threshold: float = 0.3) → ndarray[tuple[int, ...], dtype[int64]]

Get 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. There might also 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.

Parameters:

• primitive_substrate (TODO | None) – TODO

• dimension (int, default = 2) – TODO

• threshold (float, default = 0.3) – TODO

Returns:

indices of all substrate atoms

Return type:

NDArray[int64]

get_substrate_indices_from_parts(warn: bool = True) → None | ndarray[tuple[int, ...], dtype[int64]]

Get the 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. Instead a geometry part named substrate must be defined.

Parameters:

warn (bool) – Can be set to False to suppress warnings

Returns:

TODO

Return type:

NDArray[int64]

get_substrate_layers(layer_indices: list, threshold: float = 0.01, primitive_substrate=None, substrate_indices: ndarray[tuple[int, ...], dtype[int64]] | None = 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, default=1e-2) – TODO

• primitive_substrate (TODO) – TODO

• substrate_indices (TODO) – List of indices of substrate atoms

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_directory (str) – 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[tuple[int, ...], dtype[int64]]

Returns indice of unconstrained atoms.

Returns:

inds – Indice of unconstrained atoms.

Return type:

npt.NDArray[np.int64]

get_unit_cell_parameters() → tuple[floating, floating, floating, float, float, float]

Determine the unit cell parameters.

Returns:

float

Length of lattice vector 1.

float

Length of lattice vector 2.

float

Length of lattice vector 3.

float

Angle between lattice vectors 1 and 2.

float

Angle between lattice vectors 2 and 3.

float

Angle between lattice vectors 1 and 3.

Return type:

tuple

get_volume_of_unit_cell() → ndarray[tuple[int, ...], dtype[float64]]

Calcualtes the volume of the unit cell.

Returns:

volume – Volume of the unit cell.

Return type:

npt.NDArray[np.float64]

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[tuple[int, ...], 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[tuple[int, ...], 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[tuple[int, ...], 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()

Make a 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[tuple[int, ...], dtype[int64]]) → None

Reorders Atoms with index list.

Parameters:

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

rotate_coords_around_axis(angle_in_degree: float, axis: ndarray[tuple[int, ...], 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[tuple[int, ...], 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[tuple[int, ...], dtype[int64]], external_force: ndarray[tuple[int, ...], dtype[float64]]) → None

Set a constraint for a few atoms in the system for a geometry relaxation.

These are 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_initial_magnetic_moments(moments: list[float]) → None

set_multipoles_charge(charge: ndarray[tuple[int, ...], 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() → None

Shift coordinates so the one with smallest z sits at (x, y, 0).

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[tuple[int, ...], dtype[floating[Any]]], t: ndarray[tuple[int, ...], dtype[float64]] = array([0, 0, 0]), rotation_center: ndarray[tuple[int, ...], dtype[float64]] | None = None, atom_indices: ndarray[tuple[int, ...], dtype[int64]] | None = None) → None

Apply a symmetry transformation via rotation and translation of coordinates.

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

transform_fractional(R: ndarray[tuple[int, ...], dtype[float64]], t: ndarray[tuple[int, ...], 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[tuple[int, ...], dtype[float64]], t: ndarray[tuple[int, ...], 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:

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.

Return type:

dic

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.

…

path

path to the aims.out file

Type:

str

lines

contents of the aims.out file

Type:

List[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_geometry_optimisation_has_completed() → bool

Check whether present geometry is converged.

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] | None = None) → float | ndarray[tuple[int, ...], dtype[float64]]

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

get_all_ks_eigenvalues() → dict[str, ndarray[tuple[int, ...], dtype[int64 | float64]]] | tuple[dict[str, ndarray[tuple[int, ...], dtype[int64 | float64]]], dict[str, ndarray[tuple[int, ...], dtype[int64 | float64]]]]

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_basis_sets() → dict[str, str]

get_change_of_charge_density(n_occurrence: int | None = -1, energy_invalid_indicator: str | None = None) → float | ndarray[tuple[int, ...], dtype[float64]]

get_change_of_forces(n_occurrence: int | None = -1, energy_invalid_indicator: str | None = None) → float | ndarray[tuple[int, ...], dtype[float64]]

get_change_of_sum_of_eigenvalues(n_occurrence: int | None = -1, energy_invalid_indicator: str | None = None) → float | ndarray[tuple[int, ...], dtype[float64]]

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

get_control_file() → list[str]

Extract the control file from the aims output.

Returns:

Lines from the control file found in the aims output

Return type:

list[str]

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] | None = None) → float | ndarray[tuple[int, ...], dtype[float64]]

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

Get the energy of the electrons in the potential of the electric field.

Electrons given as electron density

get_electrostatic_energy(n_occurrence: None | int = -1, energy_invalid_indicator: list[str] | None = None) → float | ndarray[tuple[int, ...], 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] | None = None) → float | ndarray[tuple[int, ...], dtype[float64]]

Return the total corrected energy.

Parameters:

• n_occurrence (int | None) – If there are multiple energies in a file (e.g. during a geometry op) this parameters allows to select which energy is returned. If set to -1 the last one is returned (e.g. result of a geometry opt) 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] | None = None) → float | ndarray[tuple[int, ...], 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:

float | npt.NDArray[np.float64]

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

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

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

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

Calculate the sum of all the embedding energies.

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[str, ndarray[tuple[int, ...], dtype[int64 | float64]]] | tuple[dict[str, ndarray[tuple[int, ...], dtype[int64 | float64]]], dict[str, ndarray[tuple[int, ...], dtype[int64 | float64]]]]

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_final_spin_moment() → tuple | None

Get the final spin moment from a FHI-aims calculation.

Returns:

The final spin moment of the calculation, if it exists

Return type:

tuple | None

get_force_components(nr_of_occurrence: int = -1) → dict

Return the force component specified in “component” for all atoms.

These are the Hellmann-Feynman, Ionic, Multipole, Pulay + GGA, Van der Waals, and total forces

Parameters:

nr_of_occurrence (int, default=-1) – Currently not used. The default is -1.

Returns:

forces – Dictionary with the force components as keys and the forces as values. The forces are in the form of a numpy array with shape (n_atoms, 3).

Return type:

dict

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

Return forces on all atoms.

get_forces_without_vdw(nr_of_occurrence: int = -1) → ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Return the uncleaned forces with the vdW component.

Note that for the final output, which you get when envoding self.get_forces() you get the cleaned forces. Look up “final_forces_cleaned” in the AIMS manual for more info.

Parameters:

nr_of_occurrence (int, default=-1) – Currently not used. The default is -1.

Returns:

gradients_without_vdW

Return type:

npt.NDArray

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

get_geometry() → AimsGeometry

Extract the geometry file from the aims output.

Returns:

Geometry object

Return type:

AimsGeometry

get_geometry_steps_of_optimisation(n_occurrence: int | None = None) → AimsGeometry | list[AimsGeometry]

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] | None = None) → float | ndarray[tuple[int, ...], 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] | None = None) → float | ndarray[tuple[int, ...], dtype[float64]]

Get the energy of the nuclei in the potential of the electric field.

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

get_maximum_force(n_occurrence: int | None = -1, energy_invalid_indicator: str | None = None) → float | ndarray[tuple[int, ...], dtype[float64]]

get_n_initial_ks_states(include_spin_polarised: bool = 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

Raises:

ValueError – No KS states found in aims.out file

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] | None = None) → float | ndarray[tuple[int, ...], dtype[float64]]

Non-local electron interaction energy in the electric field potential.

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() → dict

Parse the parameters of the FHI-aims control file from the aims output.

Returns:

The parameters of the FHI-aims control file found in the aims output

Return type:

dict

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] | None = None) → float | ndarray[tuple[int, ...], dtype[float64]]

get_time_per_scf() → ndarray[tuple[int, ...], 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] | None = None) → float | ndarray[tuple[int, ...], dtype[float64]]

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

get_vdw_forces(nr_of_occurrence: int = -1) → dict

class dfttoolkit.output.ELSIOutput(elsi_csc: str = 'elsi.csc')

Bases: Output

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

…

data

The binary data from the ELSI csc file

Type:

bytes

path

Path to ELSI csc file.

Type:

str

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[tuple[int, ...], 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_array | ndarray[tuple[int, ...], 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:

csc_array | NDArray

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

Bases: Parser

Parse 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:

dict

dfttoolkit.parameters module

class dfttoolkit.parameters.AimsControl(control_in: str = 'control.in')

Bases: Parameters

FHI-aims control file parser.

…

path

path to the aims.out file

Type:

str

lines

contents of the aims.out file

Type:

List[str]

Examples

>>> ac = AimsControl(control_in="./control.in")

add_cube_cell_and_save(cell_matrix: ndarray[tuple[int, ...], dtype[_ScalarType_co]], resolution: int = 100) → None

Add cube output settings to control.in to cover the unit cell specified in cell_matrix and save to disk.

Since the default behaviour of FHI-AIMS for generating cube files for periodic structures with vacuum gives confusing results, this function ensures the cube output quantity is calculated for the full unit cell.

Parameters:

• cell_matrix (NDArray) – 2D array defining the unit cell.

• resolution (int) – Number of cube voxels to use for the shortest side of the unit cell.

add_keywords_and_save(*args: tuple[str, Any]) → None

Add keywords to the control.in file and write the new control.in to disk.

Note that files written by ASE or in a format where the keywords are at the top of the file followed by the basis sets are the only formats that are supported by this function. The keywords need to be added in a Tuple format rather than as **kwargs because we need to be able to add multiple of the same keyword.

Parameters:

*args (Tuple[str, Any]) – Keywords to be added to the control.in file.

check_periodic() → bool

Check if the system is periodic.

get_default_basis_funcs(elements: list[str] | None = None) → dict[str, str]

Get the basis functions.

Parameters:

elements (List[str], optional, default=None) – The elements to parse the basis functions for as chemical symbols.

Returns:

A dictionary of the basis functions for the specified elements.

Return type:

Dict[str, str]

get_keywords() → MultiDict

Get the keywords from the control.in file.

Returns:

Keywords in the control.in file.

Return type:

MultiDict

get_species() → list[str]

Get the species from a control.in file.

Returns:

A list of the species in the control.in file.

Return type:

List[str]

remove_keywords_and_save(*args: str) → None

Remove keywords from the control.in file and save to disk.

Note that this will not remove keywords that are commented with a ‘#’.

Parameters:

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

class dfttoolkit.parameters.CubeParameters(cube: str = 'cube.cube', text: str | None = None)

Bases: Parameters

Cube file settings that can be used to generate a control file.

type

type of cube file; all that comes after output cube

Type:

str

Parameters:

• cube (str) – path to the cube file

• text (str | None) – text to parse

• Functions

• ------------------- –

  parse(text): parses textlines

  getText(): returns cubefile specifications-string for ControlFile class

property divisions: float

property edges: ndarray[tuple[int, ...], dtype[float64]]

Set the edge vectors.

get_text() → str

TODO.

Return type:

TODO

property grid_vectors: float

has_vertical_unit_cell() → bool

property origin: ndarray[tuple[int, ...], dtype[float64]]

Origin of the cube file.

parse(text: str) → None

TODO.

Parameters:

str – TODO

property parsing_functions: dict[str, list[int | str]]

Parsing functions for specific cube keywords.

set_grid_by_box_dimensions(x_limits: tuple[float, float], y_limits: tuple[float, float], z_limits: tuple[float, float], spacing: float | tuple[float, float, float]) → None

Set origin and edge as a cuboid box.

The ranging is within the given limits, with voxel size specified by spacing.

Parameters:

• x_limits (tuple[float, float]) – min and max of…TODO

• y_limits (tuple[float, float]) – min and max of…TODO

• z_limits (tuple[float, float]) – min and max of…TODO

• spacing (float | tuple[float, float, float]) – TODO

set_z_slice(z_bottom: float, z_top: float) → None

Crops the cubefile to only include the space between z_bottom and z_top.

The cubefile could go slightly beyond z_bottom and z_top in order to preserve the distance between grid points.

Parameters:

• z_bottom (float) – TODO

• z_top (float) – TODO

property settings: MultiDict

Settings for the cube file.

property type: str

Everythin that comes after output cube as a single string.

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

Bases: Parser

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 and match statement in this class’ __init__(), and call the super().__init__() method, include the new file type as a kwarg in the super().__init__(). Optionally include the self.lines line in examples.

…

_supported_files

List of supported file types.

Type:

dict

dfttoolkit.vibrations module

class dfttoolkit.vibrations.AimsVibrations(filename: str | None = None)

Bases: Vibrations, AimsGeometry

TODO.

class dfttoolkit.vibrations.VaspVibrations(filename: str | None = None)

Bases: Vibrations, VaspGeometry

TODO.

class dfttoolkit.vibrations.Vibrations

Bases: object

TODO.

property eigenvalues: ndarray[tuple[int, ...], dtype[float64]]

property eigenvectors: ndarray[tuple[int, ...], dtype[float64]]

get_atom_type_index() → ndarray[tuple[int, ...], dtype[int64]]

get_cross_spectrum(velocities: ndarray[tuple[int, ...], dtype[float64]], index_pair: tuple, time_step: float, bootstrapping_blocks: int = 1, bootstrapping_overlap: int = 0, cutoff_at_last_maximum: bool = True, window_function: str = 'hann') → tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]]]

PLACEHOLDE.

Parameters:

• velocities (npt.NDArray[np.float64]) – Velocity time series.

• index_pair (tuple) – Indices of the two vibration between which the corss spectrum should be calculated. For instance (1, 4).

• time_step (float) – Time step in the velocity time series.

• bootstrapping_blocks (int, optional) – DESCRIPTION. The default is 1.

• bootstrapping_overlap (int, optional) – DESCRIPTION. The default is 0.

Returns:

• frequencies (np.array) – DESCRIPTION.

• cross_spectrum (np.array) – DESCRIPTION.

get_displacements(displacement: float = 0.0025) → list

Apply 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[tuple[int, ...], dtype[float64]] | None = None, only_real: bool = True, symmetrize_hessian: bool = True, eigenvectors_to_cartesian: bool = False) → tuple[ndarray[tuple[int, ...], dtype[float64]], ndarray[tuple[int, ...], dtype[float64]]]

Get all eigenvalues and eigenvectors of the hessian.

Note that the eigenvectors are mass weighted.

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) – Mass weighted eigenvectors of the Hessian given as a list of numpy arrays, where each array is a normalized displacement for the corresponding eigenfrequency.

get_eigenvalues_in_Hz(omega2: ndarray[tuple[int, ...], dtype[float64]] | None = None) → ndarray[tuple[int, ...], dtype[float64]]

Determine angular vibration frequencies in Hz.

Parameters:

omega2 (npt.NDArray[np.float64] | None, default=None) – Eigenvalues of the mass weighted hessian.

Returns:

omega_SI – Array of the eigenfrequencies in Hz.

Return type:

np.array

get_eigenvalues_in_eV(omega2: ndarray[tuple[int, ...], dtype[float64]] | None = None) → ndarray[tuple[int, ...], dtype[float64]]

get_eigenvalues_in_inverse_cm(omega2: ndarray[tuple[int, ...], dtype[float64]] | None = None) → ndarray[tuple[int, ...], 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[tuple[int, ...], dtype[float64]]

Calculate the Hessian from the forces.

This includes the atomic 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: str) → AimsVibrations | VaspVibrations

get_mass_tensor() → ndarray[tuple[int, ...], 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[tuple[int, ...], dtype[_ScalarType_co]], use_numba: bool = True) → ndarray[tuple[int, ...], dtype[_ScalarType_co]]

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: ndarray[tuple[int, ...], dtype[float64]] | None = None) → ndarray[tuple[int, ...], dtype[float64]]

Symmetrieses the Hessian by using the lower triangular matrix.

Parameters:

hessian (npt.NDArray[np.float64] | None, default=None) – Hessian matrix to be symmetrized. If None, the Hessian of the object

Returns:

Symmetrized Hessian matrix.

Return type:

npt.NDArray[np.float64]

get_velocity_mass_average(velocities: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], 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: ndarray[tuple[int, ...], dtype[float64]]

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

TODO.

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

property vibration_coors: list[ndarray[tuple[int, ...], dtype[float64]]]

property vibration_forces: list[ndarray[tuple[int, ...], dtype[float64]]]

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(conv_params: dict | None = None, scf_conv_acc_params: dict | None = None, title: str | None = None, forces: bool = False, ks_eigenvalues: bool = False, fig_size: tuple[int, int] = (24, 6)) → Figure

Plot the SCF convergence accuracy parameters.

Parameters:

• conv_params (dict | None, default=None) – convergence parameters which determine if the SCF cycle has converged

• scf_conv_acc_params (dict | None, default=None) – the scf convergence accuracy parameters

• title (str | None, default=None) – system name to use in title of the plot

• forces (bool, default=False) – whether to plot the change of forces and forces on atoms

• ks_eigenvalues (bool, default=False) – whether to plot the kohn-sham eigenvalues

• fig_size (tuple[int, int], default=(24, 6)) – the total size of the figure

Returns:

matplotlib figure object

Return type:

figure.Figure

class dfttoolkit.visualise.VisualiseCube(cube: str)

Bases: Cube

Cube visualisation tools.

…

path

path to the .cube file

Type:

str

lines

contents of the .cube file

Type:

list[str]

atoms

ASE atom or atoms object

Type:

Atom | Atoms

volume

volumetric data of the cube file

Type:

NDArray[float64]

Parameters:

cube (str) – path to the .cube file

weas_core_hole(viewer: WeasWidget | None = None, **kwargs: str) → WeasWidget

Visualise the core hole as an isosurface.

Parameters:

• viewer (WeasWidget | None, default=None) – viewer instance

• **kwargs – viewer settings keyword arguments

Returns:

viewer instance

Return type:

WeasWidget

Module contents