aim2dat.strct.mixin¶

Mixin classes for the Structure and StructureOperations classes.

Module Contents¶

Classes¶

Functions¶

exception aim2dat.strct.mixin.ConstraintError[source]¶

Bases: Exception

Constraint error.

class args¶

Overview

Methods¶

with_traceback()

Exception.with_traceback(tb) –

with_traceback()¶

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class aim2dat.strct.mixin.AnalysisMixin[source]¶

Mixin class to perform structural analysis tasks.

Overview

Methods¶

analysis_methods()	list: Return calculation methods. This property is depreciated and will be removed soon.
calculate_angle(site_index1, site_index2, site_index3, backfold_positions)	Calculate angle between three atoms.
calculate_coordination(r_max, method, min_dist_delta, n_nearest_neighbours, radius_type, atomic_radius_delta, econ_tolerance, econ_conv_threshold, voronoi_weight_type, voronoi_weight_threshold, okeeffe_weight_threshold)	Calculate coordination environment of each atomic site.
calculate_dihedral_angle(site_index1, site_index2, site_index3, site_index4, backfold_positions)	Calculate dihedral angle between four atoms.
calculate_distance(site_index1, site_index2, backfold_positions, use_supercell, r_max, return_pos)	Calculate distance between two atoms.
calculate_ffingerprint(r_max, delta_bin, sigma, use_legacy_smearing, distinguish_kinds)	Calculate f-fingerprint function for each element-pair and atomic site.
calculate_voronoi_tessellation(r_max)	Calculate voronoi polyhedron for each atomic site.
determine_point_group(threshold_distance, threshold_angle, threshold_inertia)	Determine the point group of a molecule.
determine_space_group(symprec, angle_tolerance, hall_number, return_sym_operations, return_primitive_structure, return_standardized_structure, no_idealize)	Determine the space group of the structure using spglib as backend.
list_analysis_methods()	class Get a list with the function names of all available analysis methods.

analysis_methods() → list¶

list: Return calculation methods. This property is depreciated and will be removed soon.

calculate_angle(site_index1: int | list[int] = 0, site_index2: int | list[int] = 1, site_index3: int | list[int] = 2, backfold_positions: bool = True) → float[source]¶

Calculate angle between three atoms.

Parameters:¶

• site_index1 (int, list or None) – Index of the site.

• site_index2 (int, list or None) – Index of the site.

• site_index3 (int, list or None) – Index of the site.

• backfold_positions (bool) – Whether to backfold the atomic sites and return the smallest distance.

Returns:¶

float or dict – Angle calculated via the vectors from atom 2 to atom 1 and atom 3. If one of the indices is a list, a dictionary with all index pairs as keys and angles as values is returned.

calculate_coordination(r_max: float = 10.0, method: str = 'atomic_radius', min_dist_delta: float = 0.1, n_nearest_neighbours: int = 5, radius_type: str = 'chen_manz', atomic_radius_delta: float = 0.0, econ_tolerance: float = 0.5, econ_conv_threshold: float = 0.001, voronoi_weight_type: float = 'rel_solid_angle', voronoi_weight_threshold: float = 0.5, okeeffe_weight_threshold: float = 0.5) → dict[source]¶

Calculate coordination environment of each atomic site.

Parameters:¶

• r_max (float (optional)) – Cut-off value for the maximum distance between two atoms in angstrom.

• method (str (optional)) – Method used to calculate the coordination environment.

• min_dist_delta (float (optional)) – Tolerance parameter that defines the relative distance from the nearest neighbour atom for the 'minimum_distance' method.

• n_nearest_neighbours (int (optional)) – Number of neighbours that are considered coordinated for the 'n_neighbours' method.

• radius_type (str (optional)) – Type of the atomic radius used for the 'atomic_radius' method ('covalent' is used as fallback in the radius for an element is not defined).

• atomic_radius_delta (float (optional)) – Tolerance relative to the sum of the atomic radii for the 'atomic_radius' method. If set to 0.0 the maximum threshold is defined by the sum of the atomic radii, positive (negative) values increase (decrease) the threshold.

• econ_tolerance (float (optional)) – Tolerance parameter for the econ method.

• econ_conv_threshold (float (optional)) – Convergence threshold for the econ method.

• voronoi_weight_type (str (optional)) – Weight type of the Voronoi facets. Supported options are 'covalent_atomic_radius', 'area' and 'solid_angle'. The prefix 'rel_' specifies that the relative weights with respect to the maximum value of the polyhedron are calculated.

• voronoi_weight_threshold (float (optional)) – Weight threshold to consider a neighbouring atom coordinated.

• okeeffe_weight_threshold (float (optional)) – Threshold parameter to distinguish indirect and direct neighbour atoms for the 'okeeffe'.

  This parameter is depreciated and will be removed in a future version. The original results can be obtained by using the voronoi_weight_threshold parameter and setting voronoi_weight_type to 'rel_solid_angle'.

Returns:¶

dict – Dictionary containing the coordination information of the structure.

calculate_dihedral_angle(site_index1: int | list[int] = 0, site_index2: int | list[int] = 1, site_index3: int | list[int] = 2, site_index4: int | list[int] = 3, backfold_positions: bool = True) → float[source]¶

Calculate dihedral angle between four atoms.

Parameters:¶

• site_index1 (int, list or None) – Index of the site.

• site_index2 (int, list or None) – Index of the site.

• site_index3 (int, list or None) – Index of the site.

• site_index4 (int, list or None) – Index of the site.

• backfold_positions (bool) – Whether to backfold the atomic sites and return the smallest distance.

Returns:¶

float or dict – Dihedral angle. If one of the indices is a list, a dictionary with all index pairs as keys and angles as values is returned.

calculate_distance(site_index1: int | list[int] = 0, site_index2: int | list[int] = 1, backfold_positions: bool = True, use_supercell: bool = False, r_max: float = 7.5, return_pos: bool = False) → float | list[source]¶

Calculate distance between two atoms.

Parameters:¶

• site_index1 (int, list or None) – Index of the site.

• site_index2 (int, list or None) – Index of the site.

• backfold_positions (bool) – Whether to backfold the atomic sites and return the smallest distance.

• use_supercell (bool) – User supercell to calculate all distances between the two atomic sites up to the radius r_max.

• r_max (float) – Cut-off value for the maximum distance between two atoms in angstrom.

• return_pos (bool) – Whether to return the positions. Useful if use_supercell is set to True or when trying to determine the closest periodic image.

Returns:¶

float, dict or None – Distance between the two atoms or a list of distances (if use_super_cell is set to True). If one of the indices is a list, a dictionary with all index pairs as keys and distances as values is returned. If return_pos is set to True, the positions are returned as well. In case use_super_cell is set to True and the distance between the two sites exceeds r_max, None is returned.

calculate_ffingerprint(r_max: float = 20.0, delta_bin: float = 0.005, sigma: float = 0.05, use_legacy_smearing: bool = False, distinguish_kinds: bool = False) → tuple[dict, dict][source]¶

Calculate f-fingerprint function for each element-pair and atomic site.

The calculation is based on equation (3) in doi:10.1063/1.3079326.

Parameters:¶

• r_max (float (optional)) – Cut-off value for the maximum distance between two atoms in angstrom.

• delta_bin (float (optional)) – Bin size to descritize the function in angstrom.

• sigma (float (optional)) – Smearing parameter for the Gaussian function.

• use_legacy_smearing (bool) – Use the depreciated smearing method.

• distinguish_kinds (bool (optional)) – Whether different kinds should be distinguished e.g. Ni0 and Ni1 would be considered as different elements if True.

Returns:¶

• element_fingerprints (dict) – Dictionary containing all fingerprint functions of the structure summed over all atoms of the same element.

• atomic_fingerprints (dict) – Dictionary containing all individual fingerprint functions for each atomic site.

calculate_voronoi_tessellation(r_max: float = 10.0) → list[list[dict]][source]¶

Calculate voronoi polyhedron for each atomic site.

Parameters:¶

r_max (float (optional)) – Cut-off value for the maximum distance between two atoms in angstrom.

Returns:¶

list – List of voronoi details for each atomic site.

determine_point_group(threshold_distance: float = 0.1, threshold_angle: float = 1.0, threshold_inertia: float = 0.1) → dict[source]¶

Determine the point group of a molecule.

Parameters:¶

• threshold_distance (float (optional)) – Tolerance parameter for distances.

• threshold_angle (float (optional)) – Tolerance parameter for angles.

• threshold_inertia (float (optional)) – Tolerance parameter for inertia.

Returns:¶

dict – Dictionary containing the point group and symmetry elements of the structure.

determine_space_group(symprec: float = 0.005, angle_tolerance: float = -1.0, hall_number: int = 0, return_sym_operations: bool = False, return_primitive_structure: bool = False, return_standardized_structure: bool = False, no_idealize: bool = False) → dict[source]¶

Determine the space group of the structure using spglib as backend.

Parameters:¶

• symprec (float (optional)) – Tolerance parameter for spglib

• angle_tolerance (float (optional)) – Tolerance parameter for spglib.

• hall_number (int (optional)) – The argument to constrain the space-group-type search only for the Hall symbol corresponding to it.

• return_sym_operations (bool (optional)) – Additionally, return all symmetry elements.

• return_primitive_structure (bool (optional)) – Whether to return the primitive standardized structure.

• return_standardized_structure (bool (optional)) – Whether to the non-primitive standardized structure.

• no_idealize (bool (optional)) – Whether to idealize unit cell vectors and angles.

Returns:¶

dict – Dictionary containing the internal space group number and labels.

classmethod list_analysis_methods() → list[source]¶

Get a list with the function names of all available analysis methods.

Returns:¶

list – Return a list of all available analysis methods.

class aim2dat.strct.mixin.ConstraintsMixin[source]¶

Mixin to implement structural constraints.

Overview

Properties¶

attribute_constraints	Attribute constraints.
chem_formula_constraints	Constraints on the chemical formula.
concentration_constraints	Elemental concentration constraints.
neglect_elemental_structures	Whether to neglect elemental phases.

Methods¶

add_chem_formula_constraint(chem_formula, reduced_formula)	Add a chemical formula as a constraint.
remove_constraints()	Remove all constraints.
set_attribute_constraint(attribute, min_value, max_value)	Set a constraint on attributes.
set_concentration_constraint(element, min_conc, max_conc)	Set a constraint on the concentration of an element in the structure.

property attribute_constraints¶

Attribute constraints.

property chem_formula_constraints¶

Constraints on the chemical formula.

property concentration_constraints¶

Elemental concentration constraints.

property neglect_elemental_structures¶

Whether to neglect elemental phases.

add_chem_formula_constraint(chem_formula, reduced_formula=True)[source]¶

Add a chemical formula as a constraint.

The formula can be given as a string, dictionary or list of strings or dictionaries.

Parameters:¶

• chem_formula (list, dict or str) – Chemical formula given as list, dict or str.

• reduced_formula (bool (optional)) – If set to True the reduced formulas are compared. The default value is True.

remove_constraints()[source]¶

Remove all constraints.

set_attribute_constraint(attribute, min_value=None, max_value=None)[source]¶

Set a constraint on attributes.

Parameters:¶

• attribute (str) – Attribute to be constraint.

• min_value (float) – Minimum value of the attribute. In case of no limit the variable can be set to 0.0.

• max_value (float) – Maximum value of the attribute. In case of no limit the variable can be set to 1.0.

set_concentration_constraint(element, min_conc=0.0, max_conc=1.0)[source]¶

Set a constraint on the concentration of an element in the structure.

The minimum and maximum values have to be set between 0.0 and 1.0.

Parameters:¶

• element (str) – Element to be constraint.

• min_conc (float) – Minimum concentration. In case of no limit the variable can be set to 0.0.

• max_conc (float) – Maximum concentration. In case of no limit the variable can be set to 1.0.

class aim2dat.strct.mixin.ManipulationMixin[source]¶

Mixin class to perform structural manipulation tasks.

Overview

Methods¶

delete_atoms(elements, site_indices, change_label)	Delete atoms by element, list of elements, site index or list of site indices.
list_manipulation_methods()	class Get a list with the function names of all available manipulation methods.
manipulation_methods()	list: Return manipulation methods. This property is depreciated and will be removed soon.
perform_manipulation(method, kwargs)	Perform structure manipulation using an external method.
scale_unit_cell(scaling_factors, pressure, bulk_modulus, change_label)	Scale the unit cell of the structure, supporting isotropic and anisotropic strain,
substitute_elements(elements, radius_type, remove_kind, change_label)	Substitute all atoms of one or several elements.

delete_atoms(elements: str | list[str] = [], site_indices: int | list[int] = [], change_label: bool = False) → aim2dat.strct.Structure | aim2dat.strct.StructureCollection[source]¶

Delete atoms by element, list of elements, site index or list of site indices.

Parameters:¶

• elements (str, list or tuple) – Element or tuple or list of the elements to be deleted.

• site_indices (list or tuple) – Site index or tuple or list of site indices to be deleted.

Returns:¶

aim2dat.strct.Structure – Structure with deleted atoms.

classmethod list_manipulation_methods() → list[source]¶

Get a list with the function names of all available manipulation methods.

Returns:¶

list – Return a list of all available manipulation methods.

manipulation_methods() → list¶

list: Return manipulation methods. This property is depreciated and will be removed soon.

perform_manipulation(method: collections.abc.Callable, kwargs: dict = {})[source]¶

Perform structure manipulation using an external method.

Parameters:¶

• method (function) – Function which manipulates the structure(s).

• kwargs (dict) – Arguments to be passed to the function.

Returns:¶

• aim2dat.strct.Structure or

• aim2dat.strct.StructureCollection – Manipulated structure(s).

scale_unit_cell(scaling_factors: float | list[float] = None, pressure: float = None, bulk_modulus: float = None, change_label: bool = True) → aim2dat.strct.Structure | aim2dat.strct.StructureCollection[source]¶

Scale the unit cell of the structure, supporting isotropic and anisotropic strain, and pressure-based strain.

Parameters:¶

• scaling_factors (float, list of floats, or arry-like, optional) – Scaling factor(s) to scale the unit cell. - If a single float, isotropic scaling is applied. - If a list of 3 floats or a 1D array, anisotropic scaling is

  applied along the principal axes.

  • If a 3x3 nested list or a 2D array, it defines a full transformation matrix.

  Scaling factors are interpreted as 1 + strain. For example: - A 1% strain corresponds to a scaling factor of 1.01. - A -2% strain (compression) corresponds to a scaling factor of 0.98.

• pressure (float, optional) – Hydrostatic pressure to apply. Requires bulk_modulus to calculate scaling.

• bulk_modulus (float, optional) – Bulk modulus of the material. Required if pressure is provided. Ensure the units of bulk_modulus and pressure are consistent.

• change_label (bool, optional) – If True, appends a suffix to the structure’s label to reflect the scaling applied. Defaults to True

Returns:¶

Structure or StructureCollection – The scaled structure or a collection of scaled structures.

Raises:¶

ValueError – If required parameters are missing or invalid, such as when pressure is given without bulk_modulus, or invalid scaling_factors inputs.

Notes

• The pressure and bulk_modulus inputs are mutually exclusive with direct

scaling_factors input. - Scaling factors directly modify the unit cell dimensions and are applied such that

fractional atomic positions remain unchanged.

substitute_elements(elements: list[tuple[str]] | list[tuple[int]] = [], radius_type: str | None = 'covalent', remove_kind: bool = False, change_label: bool = False) → aim2dat.strct.Structure | aim2dat.strct.StructureCollection[source]¶

Substitute all atoms of one or several elements.

Parameters:¶

• elements (list or tuple) – Tuple or list of tuples of the elements that are substituted.

• remove_kind (bool (optional)) – Sets the entries of the substituted sites in kinds to None.

• radius_type (str or None (optional)) – Radius type used to calculate the scaling factor for the unit cell. If set to None no scaling is applied. The default value is covalent.

Returns:¶

aim2dat.strct.Structure – Structure with substituted elements.

class aim2dat.strct.mixin.classproperty(func)[source]¶

Custom, temporary decorator to depreciate class properties.

aim2dat.strct.mixin.analysis_method(func)[source]¶

Mark function as calculation function.

aim2dat.strct.mixin.manipulates_structure(func)[source]¶

Mark structure manipulating functions.