aim2dat.strct.mixin

Mixin classes for the Structure and StructureOperations classes.

Module Contents

Classes

AnalysisMixin

Mixin class to perform structural analysis tasks.

ConstraintsMixin

Mixin to implement structural constraints.

ManipulationMixin

Mixin class to perform structural manipulation tasks.

Functions

analysis_method(func)

Mark function as calculation function.

manipulates_structure(func)

Mark structure manipulating 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

Properties

analysis_methods

class Return calculation methods.

Methods

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.

class property analysis_methods : list

Return calculation methods.

Type:

list

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

Calculate angle between three atoms.

Parameters:
  • site_index1 (int) – Index of the site.

  • site_index2 (int) – Index of the site.

  • site_index3 (int) – Index of the site.

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

Returns:

float – Angle calculated via the vectors from atom 2 to atom 1 and atom 3.

calculate_coordination(r_max: float = 10.0, method: str = 'minimum_distance', 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. The default value is 'minimum_distance'.

  • 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 = 0, site_index2: int = 1, site_index3: int = 2, site_index4: int = 3, backfold_positions: bool = True) float[source]

Calculate dihedral angle between four atoms.

Parameters:
  • site_index1 (int) – Index of the site.

  • site_index2 (int) – Index of the site.

  • site_index3 (int) – Index of the site.

  • site_index4 (int) – Index of the site.

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

Returns:

float – Dihedral angle.

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) – Index of the site.

  • site_index2 (int) – 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 or None – Distance between the two atoms or a list of distances (if use_super_cell is set to True). If multiple indices are provided, a dictionary with the index pairs as keys 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.

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

Properties

manipulation_methods

class Return manipulation methods.

Methods

delete_atoms(elements, site_indices, change_label)

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

perform_manipulation(method, kwargs)

Perform structure manipulation using an external method.

scale_unit_cell(scaling_factor, change_label)

Scale unit cell of the structure.

substitute_elements(elements, radius_type, remove_kind, change_label)

Substitute all atoms of one or several elements.

class property manipulation_methods : list

Return manipulation methods.

Type:

list

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.

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_factor: float = 1.0, change_label: bool = False) aim2dat.strct.Structure | aim2dat.strct.StructureCollection[source]

Scale unit cell of the structure.

Parameters:

scaling_factor (float) – Scaling factor.

Returns:

aim2dat.strct.Structure – Structure with scaled unit cell.

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.

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

Mark function as calculation function.

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

Mark structure manipulating functions.